Telemere 1.0.0-beta25
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-beta25"]
Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.
Public variables and functions:
- *ctx*
- *middleware*
- *otel-tracer*
- *uid-fn*
- add-handler!
- call-on-shutdown!
- catch->error!
- chance
- check-interop
- clean-signal-fn
- comp-middleware
- default-handler-dispatch-opts
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-handlers-stats
- get-min-levels
- handler:console
- handler:file
- help:environmental-config
- help:filters
- help:handler-dispatch-options
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- otel-default-providers_
- otel-get-default-providers
- otel-tracing?
- pr-signal-fn
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- signal!
- signal-allowed?
- spy!
- stop-handlers!
- streams->reset!
- streams->telemere!
- trace!
- uncaught->error!
- uncaught->handler!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`, +Telemere 1.0.0-RC1 Telemere 1.0.0-RC1
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-RC1"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- *otel-tracer*
- *uid-fn*
- add-handler!
- call-on-shutdown!
- catch->error!
- chance
- check-interop
- clean-signal-fn
- comp-middleware
- default-handler-dispatch-opts
- dispatch-signal!
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-handlers-stats
- get-min-levels
- handler:console
- handler:file
- help:environmental-config
- help:filters
- help:handler-dispatch-options
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- otel-default-providers_
- otel-tracing?
- pr-signal-fn
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- signal!
- signal-allowed?
- spy!
- stop-handlers!
- streams->reset!
- streams->telemere!
- trace!
- uncaught->error!
- uncaught->handler!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-middleware+
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`, Ref. <https://github.com/open-telemetry/opentelemetry-java>, <https://javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/index.html>Public variables and functions:
taoensso.telemere.postal
Email handler using `postal`, Ref. <https://github.com/drewr/postal>.Public variables and functions:
taoensso.telemere.slack
Slack handler using `clj-slack`, diff --git a/index.cljs.html b/index.cljs.html index 9a2bb98..7c15059 100644 --- a/index.cljs.html +++ b/index.cljs.html @@ -1,4 +1,4 @@ -Telemere 1.0.0-beta25 Telemere 1.0.0-beta25
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-beta25"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- *uid-fn*
- add-handler!
- catch->error!
- chance
- clean-signal-fn
- comp-middleware
- default-handler-dispatch-opts
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-handlers-stats
- get-min-levels
- handler:console
- handler:console-raw
- help:environmental-config
- help:filters
- help:handler-dispatch-options
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- pr-signal-fn
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- signal!
- signal-allowed?
- spy!
- stop-handlers!
- trace!
- uncaught->error!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +Telemere 1.0.0-RC1 \ No newline at end of file diff --git a/index.html b/index.html index 5365ed4..5c5c97e 100644 --- a/index.html +++ b/index.html @@ -1,3 +1,3 @@ -Telemere 1.0.0-RC1
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-RC1"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- *uid-fn*
- add-handler!
- catch->error!
- chance
- clean-signal-fn
- comp-middleware
- default-handler-dispatch-opts
- dispatch-signal!
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-handlers-stats
- get-min-levels
- handler:console
- handler:console-raw
- help:environmental-config
- help:filters
- help:handler-dispatch-options
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- pr-signal-fn
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- signal!
- signal-allowed?
- spy!
- stop-handlers!
- trace!
- uncaught->error!
- update-var-root!
- with-ctx
- with-ctx+
- with-err->telemere
- with-handler
- with-handler+
- with-id-filter
- with-kind-filter
- with-middleware
- with-middleware+
- with-min-level
- with-ns-filter
- with-out->telemere
- with-signal
- with-signals
- with-streams->telemere
- without-filters
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.Public variables and functions:
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.Telemere 1.0.0-beta25 \ No newline at end of file +Telemere 1.0.0-beta25
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-beta25"]Platforms
This project includes code for multiple platforms, please choose a platform to view its documentation:
Telemere 1.0.0-RC1 \ No newline at end of file diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html index 2823d2f..3a82015 100644 --- a/taoensso.telemere.cljs.html +++ b/taoensso.telemere.cljs.html @@ -1,6 +1,6 @@ -Telemere 1.0.0-RC1
Released under the Eclipse Public License - v 1.0
Structured telemetry library for Clojure/Script.
Installation
To install, add the following dependency to your project or build file:
[com.taoensso/telemere "1.0.0-RC1"]Platforms
This project includes code for multiple platforms, please choose a platform to view its documentation:
taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. +taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. See the GitHub page (esp. Wiki) for info on motivation and design: <https://www.taoensso.com/telemere>*ctx*
dynamic
clj
cljs
Optional context (state) attached to all signals. @@ -23,7 +23,7 @@ When middleware returns nil, skips all handlers. Default (root) value is nil. Useful for dynamically transforming signals and/or filtering signals by signal data/content/etc. -Re/bind dynamic value using `with-middleware`, `binding`. +Re/bind dynamic value using `with-middleware`, `with-middleware+`, `binding`. Modify root (default) value using `set-middleware!`. As with all dynamic Clojure vars, "binding conveyance" applies when using @@ -31,19 +31,23 @@ futures, agents, etc. Examples: - ;; Filter signals by returning nil: + ;; Filter all signals by returning nil: (t/set-middleware! (fn [signal] (when-not (:skip-me? signal) signal))) - ;; Remove key/s from signals: + ;; Remove key/s from all signals: (t/set-middleware! (fn [signal] (dissoc signal :unwanted-key1 ...))) ;; Remove key/s from signals to specific handler: (t/add-handler! ::my-handler my-handler {:middleware (fn [signal] (dissoc signal :unwanted-key1 ...))}) + ;; Set middleware for specific signal/s: + (binding [*middleware* (fn [signal] ...)] + (...)) + Tips: - Compose multiple middleware fns together with `comp-middleware`. - - Use `get-env` to set default (root) value based on environmental config.*uid-fn*
dynamic
clj
cljs
Experimental, subject to change. + - Use `get-env` to set default (root) value based on environmental config.*uid-fn*
dynamic
clj
cljs
Experimental, subject to change. Feedback welcome! (fn [root?]) used to generate signal `:uid` values (unique instance ids) when tracing. @@ -88,7 +92,7 @@ NB you should always call `stop-handlers!` somewhere appropriate - usually near the end of your `-main` or shutdown procedure, AFTER all other code has completed that could create signals. -See `help:handler-dispatch-options` for handler filters, etc.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} form)Unconditionally executes given form and- +See `help:handler-dispatch-options` for handler filters, etc.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} form)Unconditionally executes given form and- If form succeeds: return the form's result. If form throws: Call `error!` with the thrown error and the given signal options [2], @@ -149,7 +153,14 @@ returned composite fn immediately returns nil: ((comp-middleware inc #(* % 2) inc) 1) => 5 ; (inc (* (inc 1) 2)) ((comp-middleware inc (fn [_] nil) (fn [_] (throw (Exception. "Never thrown!")))) 1) => nil -Useful for composing Ring-style middleware fns.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} error)"Error" signal creator, emphasizing error + id. +Useful for composing Ring-style middleware fns.dispatch-signal!
clj
cljs
(dispatch-signal! signal)Dispatches given signal to registered handlers, supports `with-signal/s`. +Normally called automatically (internally) by signal creators, this util +is provided publicly since it's also handy for manually re/dispatching +custom/modified signals, etc.: + + (let [original-signal (with-signal :trap (event! ::my-id1)) + modified-signal (assoc original-signal :id ::my-id2)] + (dispatch-signal! modified-signal))error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} error)"Error" signal creator, emphasizing error + id. API: [error] [id-or-opts error] => given error (unconditional) Default kind: `:error` @@ -181,7 +192,7 @@ Tips: [3] See `help:signal-content` - {:keys [kind level id data ...]} [4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)error-signal?
clj
cljs
(error-signal? signal)Experimental, subject to change. Returns true iff given signal has an `:error` value, or a `:kind` or `:level` -that indicates that it's an error.event!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]})"Event" signal creator, emphasizing id + level. +that indicates that it's an error.event!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})"Event" signal creator, emphasizing id + level. API: [id] [id level-or-opts] => true iff signal was allowed Default kind: `:event` @@ -588,7 +599,7 @@ Default signal keys: `:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) `:uid` --------- ?id of signal instance (unique to each signal created at callsite when tracing, contrast with `:id`) -`:msg` --------- Arb app-level message ?str given to signal creator +`:msg_` -------- Arb app-level message ?str given to signal creator - may be a delay, always use `force` to unwrap! `:data` -------- Arb app-level data ?val (usu. a map) given to signal creator `:error` ------- Arb app-level platform ?error [2] given to signal creator @@ -667,17 +678,19 @@ and return values), making them more/less convenient for certain use cases: `:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding `:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) -`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal `:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal tracing info `:root` -------- Custom ?{:keys [id uid]} to override auto (dynamic) root signal tracing info `:location` ---- Custom ?{:keys [ns line column file]} to override auto signal creator callsite location +`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal, as per `with-ctx` +`:ctx+` -------- Custom ?val to update auto (dynamic `*ctx*`) in signal, as per `with-ctx+` `:elidable?` --- Should signal be subject to compile-time elision? (Default: true) `:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all) `:when` -------- Arb ?form; when present, form must return truthy to allow signal `:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details `:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!) -`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created +`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware` +`:middleware+` - Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware+` `:trace?` ------ Should tracing be enabled for `:run` form? <kvs> ---------- Other arb app-level ?kvs to incl. in signal. Typically NOT included in @@ -687,7 +700,7 @@ and return values), making them more/less convenient for certain use cases: If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! [1] `java.time.Instant` or `js/Date` -[2] `java.lang.Throwable` or `js/Error`log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} msg)"Log" signal creator, emphasizing message + level. +[2] `java.lang.Throwable` or `js/Error`log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} msg)"Log" signal creator, emphasizing message + level. API: [msg] [level-or-opts msg] => true iff signal was allowed. Default kind: `:log` @@ -831,7 +844,7 @@ Examples: - A map, {:allow <spec> :disallow <spec>} with specs as above: If present, `:allow` spec MUST match, AND If present, `:disallow` spec MUST NOT match.set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)Sets root binding (value) of the var identified by given symbol, and returns -the new value. Cross-platform. See also `update-var-root!`.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]})Low-level generic signal creator. +the new value. Cross-platform. See also `update-var-root!`.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]})Low-level generic signal creator. API: [opts] => depends on options [2] Default kind: none (optional) @@ -868,7 +881,7 @@ under a single set of conditions (incl. rate-limiting, sampling, etc.): ;; Logs exactly 2 or 0 messages (never 1): (when (signal-allowed? {:level :info, :sample-rate 0.5}) (log! {:allow? true} "Message 1") - (log! {:allow? true} "Message 2"))spy!
macro
clj
cljs
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)"Spy" signal creator, emphasizing form + level. + (log! {:allow? true} "Message 2"))spy!
macro
clj
cljs
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)"Spy" signal creator, emphasizing form + level. API: [form] [level-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:spy` @@ -878,8 +891,26 @@ When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to console/file/queue/db, etc.). -`form` is generally expected to be synchronous and eager (not a lazy seq, -async call, or IOT code like a core.async `go` block, etc.). +Enables tracing of given `form` arg: + + - Resulting signal will include {:keys [run-form run-val run-nsecs]}. + - Nested signals will include this signal's id and uid under `:parent`. + +Limitations: + + 1. Traced code (`form` arg) is usually expected to be synchronous and eager. + So no lazy seqs, async calls, or inversion of flow control (IoC) macros like + core.async `go` blocks, etc. + + 2. Tracing call (`spy!`) is usually expected to occur *within* normally flowing code. + IoC macros can arbitrarily (and often opaquely) alter program flow and tracing + across flow boundaries can be fragile or even fundamentally illogical. + + So use within IoC macro bodies might not make conceptual sense, or could produce + errors or unreliable/confusing results. + + Basically- if possible, prefer tracing normal Clojure fns running within normal + Clojure fns unless you deeply understand what your IoC macros are up to. Examples: @@ -907,6 +938,17 @@ Tips: - Can be useful to wrap with `catch->error!`: (catch->error! ::error-id (spy! ...)). + - Runtime of async or lazy code in `form` will intentionally NOT be included + in resulting signal's `:run-nsecs` value. If you want to measure such + runtimes, make sure that your form wraps where the relevant costs are + actually realized. Compare: + (spy! (delay (my-slow-code))) ; Doesn't measure slow code + (spy! @(delay (my-slow-code))) ; Does measure slow code + + - See also Tufte (https://www.taoensso.com/tufte) for a complementary/partner + Clj/s library that offers more advanced performance measurment and shares + the same signal engine (filtering and handler API) as Telemere. + ---------------------------------------------------------------------- [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]} @@ -922,7 +964,7 @@ handler's `:drain-msecs` value (see `help:handler-dispatch-options`). NB you should always call `stop-handlers!` somewhere appropriate - usually near the end of your `-main` or shutdown procedure, AFTER all other code has -completed that could create signals.trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)"Trace" signal creator, emphasizing form + id. +completed that could create signals.trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)"Trace" signal creator, emphasizing form + id. API: [form] [id-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:trace` @@ -932,8 +974,26 @@ When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to console/file/queue/db, etc.). -`form` is generally expected to be synchronous and eager (not a lazy seq, -async call, or IOT code like a core.async `go` block, etc.). +Enables tracing of given `form` arg: + + - Resulting signal will include {:keys [run-form run-val run-nsecs]}. + - Nested signals will include this signal's id and uid under `:parent`. + +Limitations: + + 1. Traced code (`form` arg) is usually expected to be synchronous and eager. + So no lazy seqs, async calls, or inversion of flow control (IoC) macros like + core.async `go` blocks, etc. + + 2. Tracing call (`trace!`) is usually expected to occur *within* normally flowing code. + IoC macros can arbitrarily (and often opaquely) alter program flow and tracing + across flow boundaries can be fragile or even fundamentally illogical. + + So use within IoC macro bodies might not make conceptual sense, or could produce + errors or unreliable/confusing results. + + Basically- if possible, prefer tracing normal Clojure fns running within normal + Clojure fns unless you deeply understand what your IoC macros are up to. Examples: @@ -965,11 +1025,22 @@ Tips: refers to the general action of tracing program flow rather than to the common logging level of the same name. + - Runtime of async or lazy code in `form` will intentionally NOT be included + in resulting signal's `:run-nsecs` value. If you want to measure such + runtimes, make sure that your form wraps where the relevant costs are + actually realized. Compare: + (trace! (delay (my-slow-code))) ; Doesn't measure slow code + (trace! @(delay (my-slow-code))) ; Does measure slow code + + - See also Tufte (https://www.taoensso.com/tufte) for a complementary/partner + Clj/s library that offers more advanced performance measurment and shares + the same signal engine (filtering and handler API) as Telemere. + ---------------------------------------------------------------------- [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]} [3] See `help:signal-content` - {:keys [kind level id data ...]} -[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]})Uses `uncaught->handler!` so that `error!` will be called for +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})Uses `uncaught->handler!` so that `error!` will be called for uncaught JVM errors. See `uncaught->handler!` and `error!` for details.update-var-root!
macro
clj
cljs
added in Encore v3.68.0 (2023-09-25)
(update-var-root! var-sym update-fn)Updates root binding (value) of the var identified by given symbol, and returns @@ -996,6 +1067,8 @@ See `help:handler-dispatch-options` for handler filters, etc. See also `with-handler`.with-id-filter
macro
clj
cljs
(with-id-filter id-filter form)Executes form with given signal id filter in effect. See `set-id-filter!` for details.with-kind-filter
macro
clj
cljs
(with-kind-filter kind-filter form)Executes form with given signal kind filter in effect. See `set-kind-filter!` for details.with-middleware
macro
clj
cljs
(with-middleware ?middleware-fn form)Evaluates given form with given `*middleware*` value. +See `*middleware*` for details.with-middleware+
macro
clj
cljs
(with-middleware+ ?middleware-fn form)Evaluates given form with composed `*middleware*` value. +Same as (with-middleware (comp-middleware *middleware* ?middleware-fn) ...). See `*middleware*` for details.with-min-level
macro
clj
cljs
(with-min-level min-level form)(with-min-level kind min-level form)(with-min-level kind ns-filter min-level form)Executes form with given minimum signal level in effect. See `set-min-level!` for details.with-ns-filter
macro
clj
cljs
(with-ns-filter ns-filter form)Executes form with given signal namespace filter in effect. See `set-ns-filter!` for details.with-out->telemere
macro
clj
cljs
(with-out->telemere form)(with-out->telemere opts form)Executes form with `*out*` bound to flush to Telemere signals with given opts. diff --git a/taoensso.telemere.html b/taoensso.telemere.html index 3c01dee..10d7f0d 100644 --- a/taoensso.telemere.html +++ b/taoensso.telemere.html @@ -1,6 +1,6 @@ -taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. +taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. See the GitHub page (esp. Wiki) for info on motivation and design: <https://www.taoensso.com/telemere>*ctx*
dynamic
clj
cljs
Optional context (state) attached to all signals. @@ -23,7 +23,7 @@ When middleware returns nil, skips all handlers. Default (root) value is nil. Useful for dynamically transforming signals and/or filtering signals by signal data/content/etc. -Re/bind dynamic value using `with-middleware`, `binding`. +Re/bind dynamic value using `with-middleware`, `with-middleware+`, `binding`. Modify root (default) value using `set-middleware!`. As with all dynamic Clojure vars, "binding conveyance" applies when using @@ -31,19 +31,23 @@ futures, agents, etc. Examples: - ;; Filter signals by returning nil: + ;; Filter all signals by returning nil: (t/set-middleware! (fn [signal] (when-not (:skip-me? signal) signal))) - ;; Remove key/s from signals: + ;; Remove key/s from all signals: (t/set-middleware! (fn [signal] (dissoc signal :unwanted-key1 ...))) ;; Remove key/s from signals to specific handler: (t/add-handler! ::my-handler my-handler {:middleware (fn [signal] (dissoc signal :unwanted-key1 ...))}) + ;; Set middleware for specific signal/s: + (binding [*middleware* (fn [signal] ...)] + (...)) + Tips: - Compose multiple middleware fns together with `comp-middleware`. - - Use `get-env` to set default (root) value based on environmental config.*otel-tracer*
dynamic
clj
*uid-fn*
dynamic
clj
cljs
Experimental, subject to change. + - Use `get-env` to set default (root) value based on environmental config.*otel-tracer*
dynamic
clj
*uid-fn*
dynamic
clj
cljs
Experimental, subject to change. Feedback welcome! (fn [root?]) used to generate signal `:uid` values (unique instance ids) when tracing. @@ -67,7 +71,7 @@ Override default by setting one of the following: `:hex/insecure` - hex-style string (32/16 chars) w/ strong RNG `:hex/secure` - hex-style string (32/16 chars) w/ fast RNGcall-on-shutdown!
clj
added in Encore v3.114.0 (2024-08-07)
(call-on-shutdown! f)Registers given nullary fn as a JVM shutdown hook. (f) will be called sometime during shutdown. While running, it will -attempt to block shutdown.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} form)Unconditionally executes given form and- +attempt to block shutdown.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} form)Unconditionally executes given form and- If form succeeds: return the form's result. If form throws: Call `error!` with the thrown error and the given signal options [2], @@ -138,7 +142,14 @@ returned composite fn immediately returns nil: ((comp-middleware inc (fn [_] nil) (fn [_] (throw (Exception. "Never thrown!")))) 1) => nil Useful for composing Ring-style middleware fns.default-handler-dispatch-opts
clj
cljs
Default handler dispatch options, see -`help:handler-dispatch-options` for details.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} error)"Error" signal creator, emphasizing error + id. +`help:handler-dispatch-options` for details.dispatch-signal!
clj
cljs
(dispatch-signal! signal)Dispatches given signal to registered handlers, supports `with-signal/s`. +Normally called automatically (internally) by signal creators, this util +is provided publicly since it's also handy for manually re/dispatching +custom/modified signals, etc.: + + (let [original-signal (with-signal :trap (event! ::my-id1)) + modified-signal (assoc original-signal :id ::my-id2)] + (dispatch-signal! modified-signal))error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} error)"Error" signal creator, emphasizing error + id. API: [error] [id-or-opts error] => given error (unconditional) Default kind: `:error` @@ -170,7 +181,7 @@ Tips: [3] See `help:signal-content` - {:keys [kind level id data ...]} [4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)error-signal?
clj
cljs
(error-signal? signal)Experimental, subject to change. Returns true iff given signal has an `:error` value, or a `:kind` or `:level` -that indicates that it's an error.event!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]})"Event" signal creator, emphasizing id + level. +that indicates that it's an error.event!
macro
clj
cljs
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})"Event" signal creator, emphasizing id + level. API: [id] [id level-or-opts] => true iff signal was allowed Default kind: `:event` @@ -598,7 +609,7 @@ Default signal keys: `:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) `:uid` --------- ?id of signal instance (unique to each signal created at callsite when tracing, contrast with `:id`) -`:msg` --------- Arb app-level message ?str given to signal creator +`:msg_` -------- Arb app-level message ?str given to signal creator - may be a delay, always use `force` to unwrap! `:data` -------- Arb app-level data ?val (usu. a map) given to signal creator `:error` ------- Arb app-level platform ?error [2] given to signal creator @@ -677,17 +688,19 @@ and return values), making them more/less convenient for certain use cases: `:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding `:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) -`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal `:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal tracing info `:root` -------- Custom ?{:keys [id uid]} to override auto (dynamic) root signal tracing info `:location` ---- Custom ?{:keys [ns line column file]} to override auto signal creator callsite location +`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal, as per `with-ctx` +`:ctx+` -------- Custom ?val to update auto (dynamic `*ctx*`) in signal, as per `with-ctx+` `:elidable?` --- Should signal be subject to compile-time elision? (Default: true) `:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all) `:when` -------- Arb ?form; when present, form must return truthy to allow signal `:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details `:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!) -`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created +`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware` +`:middleware+` - Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware+` `:trace?` ------ Should tracing be enabled for `:run` form? <kvs> ---------- Other arb app-level ?kvs to incl. in signal. Typically NOT included in @@ -698,7 +711,7 @@ If anything is unclear, please ping me (@ptaoussanis) so that I can improve thes [1] `java.time.Instant` or `js/Date` [2] `java.lang.Throwable` or `js/Error`log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} msg)"Log" signal creator, emphasizing message + level. +log!
macro
clj
cljs
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]} msg)"Log" signal creator, emphasizing message + level. API: [msg] [level-or-opts msg] => true iff signal was allowed. Default kind: `:log` @@ -748,19 +761,7 @@ Useful for conditionally splicing in extra message content, etc.: (log! [(when <cond> (msg-splice ["Username:" "Steve"]))]) %> {:msg_ "Username: Steve"}otel-default-providers_
clj
otel-get-default-providers
clj
(otel-get-default-providers)Experimental, subject to change. Feedback welcome! - -When OpenTelemetry Java API [1] is present, returns map with keys: - :logger-provider - default `io.opentelemetry.api.logs.LoggerProvider` - :tracer-provider - default `io.opentelemetry.api.trace.TracerProvider` - :via - ∈ #{:sdk-extension-autoconfigure :global} - -Uses `AutoConfiguredOpenTelemetrySdk` when possible, or -`GlobalOpenTelemetry` otherwise. - -See the relevant OpenTelemetry Java docs for details. - -[1] Ref. <https://github.com/open-telemetry/opentelemetry-java>otel-tracing?
clj
Experimental, subject to change. Feedback welcome! +otel-default-providers_
clj
otel-tracing?
clj
Experimental, subject to change. Feedback welcome! Should Telemere's tracing signal creators (`trace!`, `spy!`, etc.) interop with OpenTelemetry Java [1]? This will affect relevant @@ -782,7 +783,7 @@ Override default by setting one of the following to "true" or "false": Env variable: `TAOENSSO_TELEMERE_otel-tracing` Classpath resource: `taoensso.telemere.otel-tracing` -See also: `otel-get-default-providers`, `*otel-tracer*`, +See also: `otel-default-providers_`, `*otel-tracer*`, `taoensso.telemere.open-telemere/handler:open-telemetry`. [1] Ref. <https://github.com/open-telemetry/opentelemetry-java>pr-signal-fn
clj
cljs
(pr-signal-fn)(pr-signal-fn {:keys [pr-fn clean-fn incl-newline?], :as opts, :or {pr-fn :edn, clean-fn (clean-signal-fn), incl-newline? true}})Experimental, subject to change. @@ -886,7 +887,7 @@ Examples: - A map, {:allow <spec> :disallow <spec>} with specs as above: If present, `:allow` spec MUST match, AND If present, `:disallow` spec MUST NOT match.set-var-root!
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)Sets root binding (value) of the var identified by given symbol, and returns -the new value. Cross-platform. See also `update-var-root!`.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]})Low-level generic signal creator. +the new value. Cross-platform. See also `update-var-root!`.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]})Low-level generic signal creator. API: [opts] => depends on options [2] Default kind: none (optional) @@ -923,7 +924,7 @@ under a single set of conditions (incl. rate-limiting, sampling, etc.): ;; Logs exactly 2 or 0 messages (never 1): (when (signal-allowed? {:level :info, :sample-rate 0.5}) (log! {:allow? true} "Message 1") - (log! {:allow? true} "Message 2"))spy!
macro
clj
cljs
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)"Spy" signal creator, emphasizing form + level. + (log! {:allow? true} "Message 2"))spy!
macro
clj
cljs
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)"Spy" signal creator, emphasizing form + level. API: [form] [level-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:spy` @@ -933,8 +934,26 @@ When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to console/file/queue/db, etc.). -`form` is generally expected to be synchronous and eager (not a lazy seq, -async call, or IOT code like a core.async `go` block, etc.). +Enables tracing of given `form` arg: + + - Resulting signal will include {:keys [run-form run-val run-nsecs]}. + - Nested signals will include this signal's id and uid under `:parent`. + +Limitations: + + 1. Traced code (`form` arg) is usually expected to be synchronous and eager. + So no lazy seqs, async calls, or inversion of flow control (IoC) macros like + core.async `go` blocks, etc. + + 2. Tracing call (`spy!`) is usually expected to occur *within* normally flowing code. + IoC macros can arbitrarily (and often opaquely) alter program flow and tracing + across flow boundaries can be fragile or even fundamentally illogical. + + So use within IoC macro bodies might not make conceptual sense, or could produce + errors or unreliable/confusing results. + + Basically- if possible, prefer tracing normal Clojure fns running within normal + Clojure fns unless you deeply understand what your IoC macros are up to. Examples: @@ -962,6 +981,17 @@ Tips: - Can be useful to wrap with `catch->error!`: (catch->error! ::error-id (spy! ...)). + - Runtime of async or lazy code in `form` will intentionally NOT be included + in resulting signal's `:run-nsecs` value. If you want to measure such + runtimes, make sure that your form wraps where the relevant costs are + actually realized. Compare: + (spy! (delay (my-slow-code))) ; Doesn't measure slow code + (spy! @(delay (my-slow-code))) ; Does measure slow code + + - See also Tufte (https://www.taoensso.com/tufte) for a complementary/partner + Clj/s library that offers more advanced performance measurment and shares + the same signal engine (filtering and handler API) as Telemere. + ---------------------------------------------------------------------- [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]} @@ -990,7 +1020,7 @@ and setting `System/err` won't necessarily affect Clojure's `*err*`. See also: `with-out->telemere`, `with-err->telemere`, - `with-streams->telemere`.trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)"Trace" signal creator, emphasizing form + id. + `with-streams->telemere`.trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error run & kvs]} form)"Trace" signal creator, emphasizing form + id. API: [form] [id-or-opts form] => form's result (value/throw) (unconditional) Default kind: `:trace` @@ -1000,8 +1030,26 @@ When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to console/file/queue/db, etc.). -`form` is generally expected to be synchronous and eager (not a lazy seq, -async call, or IOT code like a core.async `go` block, etc.). +Enables tracing of given `form` arg: + + - Resulting signal will include {:keys [run-form run-val run-nsecs]}. + - Nested signals will include this signal's id and uid under `:parent`. + +Limitations: + + 1. Traced code (`form` arg) is usually expected to be synchronous and eager. + So no lazy seqs, async calls, or inversion of flow control (IoC) macros like + core.async `go` blocks, etc. + + 2. Tracing call (`trace!`) is usually expected to occur *within* normally flowing code. + IoC macros can arbitrarily (and often opaquely) alter program flow and tracing + across flow boundaries can be fragile or even fundamentally illogical. + + So use within IoC macro bodies might not make conceptual sense, or could produce + errors or unreliable/confusing results. + + Basically- if possible, prefer tracing normal Clojure fns running within normal + Clojure fns unless you deeply understand what your IoC macros are up to. Examples: @@ -1033,11 +1081,22 @@ Tips: refers to the general action of tracing program flow rather than to the common logging level of the same name. + - Runtime of async or lazy code in `form` will intentionally NOT be included + in resulting signal's `:run-nsecs` value. If you want to measure such + runtimes, make sure that your form wraps where the relevant costs are + actually realized. Compare: + (trace! (delay (my-slow-code))) ; Doesn't measure slow code + (trace! @(delay (my-slow-code))) ; Does measure slow code + + - See also Tufte (https://www.taoensso.com/tufte) for a complementary/partner + Clj/s library that offers more advanced performance measurment and shares + the same signal engine (filtering and handler API) as Telemere. + ---------------------------------------------------------------------- [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]} [3] See `help:signal-content` - {:keys [kind level id data ...]} -[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]})Uses `uncaught->handler!` so that `error!` will be called for +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)uncaught->error!
macro
clj
cljs
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware middleware+ sample-rate kind ns id level when rate-limit rate-limit-by ctx ctx+ parent root trace? do let data msg error & kvs]})Uses `uncaught->handler!` so that `error!` will be called for uncaught JVM errors. See `uncaught->handler!` and `error!` for details.uncaught->handler!
clj
(uncaught->handler! handler)Sets JVM's global `DefaultUncaughtExceptionHandler` to given @@ -1067,6 +1126,8 @@ See `help:handler-dispatch-options` for handler filters, etc. See also `with-handler`.with-id-filter
macro
clj
cljs
(with-id-filter id-filter form)Executes form with given signal id filter in effect. See `set-id-filter!` for details.with-kind-filter
macro
clj
cljs
(with-kind-filter kind-filter form)Executes form with given signal kind filter in effect. See `set-kind-filter!` for details.with-middleware
macro
clj
cljs
(with-middleware ?middleware-fn form)Evaluates given form with given `*middleware*` value. +See `*middleware*` for details.with-middleware+
macro
clj
cljs
(with-middleware+ ?middleware-fn form)Evaluates given form with composed `*middleware*` value. +Same as (with-middleware (comp-middleware *middleware* ?middleware-fn) ...). See `*middleware*` for details.with-min-level
macro
clj
cljs
(with-min-level min-level form)(with-min-level kind min-level form)(with-min-level kind ns-filter min-level form)Executes form with given minimum signal level in effect. See `set-min-level!` for details.with-ns-filter
macro
clj
cljs
(with-ns-filter ns-filter form)Executes form with given signal namespace filter in effect. See `set-ns-filter!` for details.with-out->telemere
macro
clj
cljs
(with-out->telemere form)(with-out->telemere opts form)\ No newline at end of file diff --git a/taoensso.telemere.postal.html b/taoensso.telemere.postal.html index 6ae59fc..15d6875 100644 --- a/taoensso.telemere.postal.html +++ b/taoensso.telemere.postal.html @@ -1,6 +1,6 @@ -Executes form with `*out*` bound to flush to Telemere signals with given opts. diff --git a/taoensso.telemere.open-telemetry.html b/taoensso.telemere.open-telemetry.html index 9fc9872..f76841a 100644 --- a/taoensso.telemere.open-telemetry.html +++ b/taoensso.telemere.open-telemetry.html @@ -1,6 +1,6 @@ -taoensso.telemere.open-telemetry documentation taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`, +taoensso.telemere.open-telemetry documentation \ No newline at end of file + (see `telemere/otel-default-providers_` for default). + +Optional signal keys: + `:otel/attrs` - Attributes [1] to add to log records AND tracing spans/events + `:otel/log-attrs` - Attributes [1] to add to log records ONLY + `:otel/trace-attrs` - Attributes [1] to add to tracing spans/events ONLY + +[1] `io.opentelemetry.api.common.Attributes` or Clojure map with str/kw keys and vals ∈ + #{nil boolean keyword string UUID long double string-vec long-vec double-vec boolean-vec}. + Other val types (incl. maps) will be printed as EDN if possible, or skipped otherwise.taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`, Ref. <https://github.com/open-telemetry/opentelemetry-java>, <https://javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/index.html>check-interop
clj
(check-interop)Returns interop debug info map.handler:open-telemetry
clj
(handler:open-telemetry)(handler:open-telemetry {:keys [emit-tracing? logger-provider], :or {emit-tracing? true}})Highly experimental, possibly buggy, and subject to change!! @@ -19,4 +19,13 @@ Returns a signal handler that: Options: `:logger-provider` - nil or `io.opentelemetry.api.logs.LoggerProvider`, - (see `telemere/get-default-providers` for default).taoensso.telemere.postal documentation taoensso.telemere.postal
Email handler using `postal`, +taoensso.telemere.postal documentation taoensso.telemere.postal
Email handler using `postal`, Ref. <https://github.com/drewr/postal>.default-dispatch-opts
clj
handler:postal
clj
(handler:postal {:keys [conn-opts msg-opts subject-fn body-fn], :or {subject-fn (signal-subject-fn), body-fn (utils/format-signal-fn)}})Experimental, subject to change. Needs `postal`, Ref. <https://github.com/drewr/postal>. diff --git a/taoensso.telemere.slack.html b/taoensso.telemere.slack.html index ea2ff31..11d4a13 100644 --- a/taoensso.telemere.slack.html +++ b/taoensso.telemere.slack.html @@ -1,6 +1,6 @@ -taoensso.telemere.slack documentation taoensso.telemere.slack
Slack handler using `clj-slack`, +taoensso.telemere.slack documentation taoensso.telemere.slack
Slack handler using `clj-slack`, Ref. <https://github.com/julienXX/clj-slack>default-dispatch-opts
clj
handler:slack
clj
(handler:slack {:keys [conn-opts post-opts output-fn], :or {conn-opts {:api-url "https://slack.com/api", :token nil}, post-opts {:channel-id nil, :username nil}, output-fn (utils/format-signal-fn)}})Experimental, subject to change. Needs `clj-slack`, Ref. <https://github.com/julienXX/clj-slack>. diff --git a/taoensso.telemere.sockets.html b/taoensso.telemere.sockets.html index a47a320..6ac7a22 100644 --- a/taoensso.telemere.sockets.html +++ b/taoensso.telemere.sockets.html @@ -1,6 +1,6 @@ -taoensso.telemere.sockets documentation taoensso.telemere.sockets
Basic TCP/UDP socket handlers. +taoensso.telemere.sockets documentation taoensso.telemere.sockets
Basic TCP/UDP socket handlers.handler:tcp-socket
clj
(handler:tcp-socket {:keys [socket-opts output-fn], :or {output-fn (utils/format-signal-fn)}})Experimental, subject to change. Returns a signal handler that: diff --git a/taoensso.telemere.streams.html b/taoensso.telemere.streams.html index a6dcbe2..b61403c 100644 --- a/taoensso.telemere.streams.html +++ b/taoensso.telemere.streams.html @@ -1,6 +1,6 @@ -taoensso.telemere.streams documentation taoensso.telemere.streams
Interop support for standard stream/s -> Telemere. +taoensso.telemere.streams documentation taoensso.telemere.streams
Interop support for standard stream/s -> Telemere.check-err-interop
clj
(check-err-interop)Returns interop debug info map.check-out-interop
clj
(check-out-interop)Returns interop debug info map.streams->reset!
clj
(streams->reset!)Experimental, subject to change. diff --git a/taoensso.telemere.timbre.cljs.html b/taoensso.telemere.timbre.cljs.html index 6602870..86fa59c 100644 --- a/taoensso.telemere.timbre.cljs.html +++ b/taoensso.telemere.timbre.cljs.html @@ -1,6 +1,6 @@ -taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +taoensso.telemere.timbre documentation \ No newline at end of file diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html index b99030e..6603bb5 100644 --- a/taoensso.telemere.timbre.html +++ b/taoensso.telemere.timbre.html @@ -1,6 +1,6 @@ -taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.debug
macro
clj
(debug & args)Prefer `telemere/log!`, etc.debugf
macro
clj
(debugf & args)Prefer `telemere/log!`, etc.error
macro
clj
(error & args)Prefer `telemere/log!`, etc. diff --git a/taoensso.telemere.tools-logging.html b/taoensso.telemere.tools-logging.html index 3eea0fd..1439b6f 100644 --- a/taoensso.telemere.tools-logging.html +++ b/taoensso.telemere.tools-logging.html @@ -1,6 +1,6 @@ -taoensso.telemere.tools-logging documentation taoensso.telemere.tools-logging
Interop support for tools.logging -> Telemere. +taoensso.telemere.tools-logging documentation taoensso.telemere.tools-logging
Interop support for tools.logging -> Telemere. Telemere will attempt to load this ns automatically when possible. Naming conventions: diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html index 02cd2c2..4a05945 100644 --- a/taoensso.telemere.utils.cljs.html +++ b/taoensso.telemere.utils.cljs.html @@ -1,6 +1,6 @@ -taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc. +taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.clean-signal-fn
clj
cljs
(clean-signal-fn)(clean-signal-fn {:keys [incl-kvs? incl-nils? incl-keys], :as opts})Experimental, subject to change. Returns a (fn clean [signal]) that: - Takes a Telemere signal (map). @@ -28,13 +28,16 @@ Returns a (fn format [instant]) that: - Returns a formatted human-readable instant string. Options: - `:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC). `:formatter` - `java.time.format.DateTimeFormatter` (Clj) or - `goog.i18n.DateTimeFormat` (Cljs), + Clj: `java.time.format.DateTimeFormatter` + Cljs: `goog.i18n.DateTimeFormat` Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`), - e.g.: "2011-12-03T10:15:130Z".format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})Experimental, subject to change. + e.g.: "2011-12-03T10:15:130Z". + + `:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC). + Note that zone may be ignored by some `DateTimeFormatter`s, + including the default (`DateTimeFormatter/ISO_INSTANT`)!format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})Experimental, subject to change. Returns a (fn format [nanosecs]) that: - Takes a long nanoseconds (e.g. runtime). - Returns a human-readable string like: diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html index 51c4f7d..e5dfc83 100644 --- a/taoensso.telemere.utils.html +++ b/taoensso.telemere.utils.html @@ -1,6 +1,6 @@ -taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc. +taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.clean-signal-fn
clj
cljs
(clean-signal-fn)(clean-signal-fn {:keys [incl-kvs? incl-nils? incl-keys], :as opts})Experimental, subject to change. Returns a (fn clean [signal]) that: - Takes a Telemere signal (map). @@ -39,13 +39,16 @@ Returns a (fn format [instant]) that: - Returns a formatted human-readable instant string. Options: - `:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC). `:formatter` - `java.time.format.DateTimeFormatter` (Clj) or - `goog.i18n.DateTimeFormat` (Cljs), + Clj: `java.time.format.DateTimeFormatter` + Cljs: `goog.i18n.DateTimeFormat` Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`), - e.g.: "2011-12-03T10:15:130Z".format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})Experimental, subject to change. + e.g.: "2011-12-03T10:15:130Z". + + `:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC). + Note that zone may be ignored by some `DateTimeFormatter`s, + including the default (`DateTimeFormatter/ISO_INSTANT`)!format-nsecs-fn
clj
cljs
(format-nsecs-fn)(format-nsecs-fn {:as _opts})Experimental, subject to change. Returns a (fn format [nanosecs]) that: - Takes a long nanoseconds (e.g. runtime). - Returns a human-readable string like: