Telemere 1.0.0-beta12
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-beta12"]
Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.
Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- check-intakes
- comp-middleware
- default-ctx
- default-handler-dispatch-opts
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-min-level
- handler:console
- handler:file
- help:filters
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-filters
- help:signal-flow
- help:signal-handlers
- 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!
- shut-down-handlers!
- signal!
- spy!
- 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-beta13 Telemere 1.0.0-beta13
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-beta13"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *auto-stop-handlers?*
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- check-intakes
- comp-middleware
- default-ctx
- 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
- 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!
- 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`, Ref. <https://github.com/open-telemetry/opentelemetry-java>.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`, Ref. <https://github.com/julienXX/clj-slack>Public variables and functions:
taoensso.telemere.streams
Intake support for standard stream/s -> Telemere.Public variables and functions:
taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. diff --git a/index.cljs.html b/index.cljs.html index 3b9ecc7..e21cc8d 100644 --- a/index.cljs.html +++ b/index.cljs.html @@ -1,4 +1,4 @@ -Telemere 1.0.0-beta12 Telemere 1.0.0-beta12
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-beta12"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- comp-middleware
- default-ctx
- default-handler-dispatch-opts
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-min-level
- handler:console
- handler:console-raw
- help:filters
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-filters
- help:signal-flow
- help:signal-handlers
- 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!
- shut-down-handlers!
- signal!
- spy!
- 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-beta13 \ No newline at end of file diff --git a/index.html b/index.html index f946763..f9aa50f 100644 --- a/index.html +++ b/index.html @@ -1,3 +1,3 @@ -Telemere 1.0.0-beta13
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-beta13"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- comp-middleware
- default-ctx
- 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!
- 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. Intended to help ease migration from Timbre to Telemere.Public variables and functions:
taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.Public variables and functions:
Telemere 1.0.0-beta12 \ No newline at end of file +Telemere 1.0.0-beta12
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-beta12"]Platforms
This project includes code for multiple platforms, please choose a platform to view its documentation:
Telemere 1.0.0-beta13 \ No newline at end of file diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html index a748283..20b94ed 100644 --- a/taoensso.telemere.cljs.html +++ b/taoensso.telemere.cljs.html @@ -1,6 +1,6 @@ -Telemere 1.0.0-beta13
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-beta13"]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 \ No newline at end of file diff --git a/taoensso.telemere.html b/taoensso.telemere.html index 4a2dc38..3f254f6 100644 --- a/taoensso.telemere.html +++ b/taoensso.telemere.html @@ -1,9 +1,12 @@ -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
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals. @@ -22,103 +22,25 @@ Compose multiple middleware fns together with `comp-middleware`. Re/bind dynamic value using `with-middleware`, `binding`. Modify root (base) value using `set-middleware!`.add-handler!
clj
cljs
(add-handler! handler-id handler-fn)(add-handler! handler-id handler-fn dispatch-opts)Registers given signal handler and returns -{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers +{<handler-id> {:keys [dispatch-opts handler-fn]}} for all handlers now registered. -`handler-fn` should be a fn of 2 arities: +`handler-fn` should be a fn of 1 or 2 arities: - [handler-arg] ; Handle the given argument (e.g. write to disk/db, etc.) - [] ; Called exactly once on system shutdown to provide an opportunity for - handler to close/release any resources that it may have opened/acquired. - See also `:max-shutdown-msecs` dispatch option. + [signal] ; Single argument + Called asynchronously or synchronously (depending on dispatch options) + to do something useful with the given signal. -See the relevant docstring/s for `handler-arg` details. + Example actions: + Save data to disk or db, `tap>`, log, `put!` to an appropriate + `core.async` channel, filter, aggregate, use for a realtime analytics + dashboard, examine for outliers or unexpected data, etc. -Handler ideas: + [] ; No arguments + Called exactly once when gracefully stopping handler to provide an opportunity + for handler to close/release any resources that it may have opened/acquired, etc. - Save to a db, `tap>`, log, `put!` to an appropriate `core.async` - channel, filter, aggregate, use for a realtime analytics dashboard, - examine for outliers or unexpected data, etc. - -Dispatch options include (see also `default-handler-dispatch-opts`): - - `:async` (Clj only) - Options for running handler asynchronously via `taoensso.encore/runner`, - {:keys [mode buffer-size n-threads daemon-threads? ...]} - - Supports `:blocking`, `:dropping`, and `:sliding` back-pressure modes. - NB handling order may be non-sequential when `n-threads` > 1. - - Options: - `:mode` - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}. - `:buffer-size` - Size of buffer before back-pressure mechanism is engaged. - `:n-threads` - Number of threads for asynchronously executing fns. - NB execution order may be non-sequential when n > 1. - - Default: {:mode :blocking, :buffer-size 1024, :n-threads 1 ...}, - i.e. async but will block when >1024 handler-args already waiting. - - `:max-shutdown-msecs` (Clj only) - Maximum time (in milliseconds) that handler will block system shutdown - to drain its async buffer and/or close/release its resources. - - `:priority` - Optional handler priority ∈ℤ (default 100). - Handlers will be called in descending priority order. - - `:sample-rate` - Optional sample rate ∈ℝ[0,1], or (fn dyamic-sample-rate []) => ℝ[0,1]. - When present, handle only this (random) proportion of args: - 1.0 => handle every arg (same as `nil` rate, default) - 0.0 => noop every arg - 0.5 => handle random 50% of args - - `:kind-filter` - Kind filter as in `set-kind-filter!` (when relevant) - `:ns-filter` - Namespace filter as in `set-ns-filter!` - `:id-filter` - Id filter as in `set-id-filter!` (when relevant) - `:min-level` - Minimum level as in `set-min-level!` - - `:when-fn` - Optional nullary (fn allow? []) that must return truthy for handler to be - called. When present, called *after* sampling and other filters, but before - rate limiting. - - `:rate-limit` - Optional rate limit spec as provided to `taoensso.encore/rate-limiter`, - {<limit-id> [<n-max-calls> <msecs-window>]}. - - Examples: - {"1/sec" [1 1000]} => Max 1 call per 1000 msecs - {"1/sec" [1 1000] - "10/min" [10 60000]} => Max 1 call per 1000 msecs, - and 10 calls per 60 secs - - `:middleware` - Optional (fn [handler-arg]) => ?modified-handler-arg to apply before - handling. When middleware returns nil, skips handler. - - Compose multiple middleware fns together with `comp-middleware`. - - `:error-fn` - (fn [{:keys [handler-id handler-arg error]}]) to call on handler error. - `:backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back-pressure. - -Flow sequence: - - 1. Per call (n=1) - a. Sampling - b. Filtering (kind, namespace, id, level, when-form) - c. Rate limiting - d. Middleware - - 2. Per handler (n>=0) - a. Sampling - b. Filtering (kind, namespace, id, level, when-fn) - c. Rate limiting - d. Middleware - e. Hander fn - - Note: call filters should generally be at least as permissive as handler filters, - otherwise calls will be suppressed before reaching handlers.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 ctx parent 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 sample-rate kind ns id level when rate-limit ctx parent 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], @@ -151,11 +73,11 @@ Tips: See also `error!`. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)chance
clj
cljs
(chance prob)Returns true with given probability ∈ ℝ[0,1]. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)comp-middleware
clj
cljs
added in Encore v3.106.0 (2024-05-01)
(comp-middleware fs)(comp-middleware f1 f2)(comp-middleware f1 f2 f3)(comp-middleware f1 f2 f3 & fs)Returns a single (composite) unary fn that applies all given unary fns sequentially (left->right!: f1, f2, ...). If any given fn returns nil, the returned composite fn immediately returns nil: @@ -193,11 +115,11 @@ Tips: - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`). - Can conveniently be wrapped by `throw`: (throw (error! ...)). -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)error-signal?
clj
cljs
(error-signal? signal)Experimental, subject to change. +[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 ctx parent trace? do let data msg error & kvs]})"Event" signal creator, emphasizing id + level. @@ -230,11 +152,11 @@ Tips: Mnemonic: the arg that's typically larger is *always* in the rightmost position, and for `event!` that's the `level-or-opts` arg. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)format-signal-fn
clj
cljs
(format-signal-fn)(format-signal-fn {:keys [incl-newline? preamble-fn content-fn], :or {incl-newline? true, preamble-fn (signal-preamble-fn), content-fn (signal-content-fn)}})Experimental, subject to change. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)format-signal-fn
clj
cljs
(format-signal-fn)(format-signal-fn {:keys [incl-newline? preamble-fn content-fn], :or {incl-newline? true, preamble-fn (signal-preamble-fn), content-fn (signal-content-fn)}})Experimental, subject to change. Returns a (fn format [signal]) that: - Takes a Telemere signal (map). - Returns a human-readable signal string. @@ -297,8 +219,50 @@ macro-expansion. Symbols in edn will be evaluated during expansion. TIP!: Use the {:return :explain} option in tests or at the REPL to verify/inspect resulting config value, config source, and specific search order of prop/env/res ids.get-handlers
clj
cljs
(get-handlers)Returns ?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all -registered signal handlers.get-min-level
clj
cljs
(get-min-level)(get-min-level kind)(get-min-level kind ns)Returns current ?{:keys [compile-time runtime]} minimum levels. +get-handlers
clj
cljs
(get-handlers)Returns ?{<handler-id> {:keys [dispatch-opts handler-fn handler-stats_]}} +for all registered signal handlers.get-handlers-stats
clj
cljs
(get-handlers-stats)Alpha, subject to change. +Returns ?{<handler-id> {:keys [handling-nsecs counts]}} for all registered +signal handlers that have the `:track-stats?` dispatch option enabled +(it is by default). + +Stats include: + + `:handling-nsecs` - Summary stats of nanosecond handling times, keys: + `:min` - Minimum handling time + `:max` - Maximum handling time + `:mean` - Arithmetic mean handling time + `:mad` - Mean absolute deviation of handling time (measure of dispersion) + `:var` - Variance of handling time (measure of dispersion) + `:p50` - 50th percentile of handling time (50% of times <= this) + `:p90` - 90th percentile of handling time (90% of times <= this) + `:p99` - 99th percentile of handling time + `:last` - Most recent handling time + ... + + `:counts` - Integer counts for handler outcomes, keys (chronologically): + + `:dropped` - Noop handler calls due to stopped handler + `:back-pressure` - Handler calls that experienced (async) back-pressure + (possible noop, depending on back-pressure mode) + + `:sampled` - Noop handler calls due to sample rate + `:filtered` - Noop handler calls due to kind/ns/id/level/when filtering + `:rate-limited` - Noop handler calls due to rate limit + `:disallowed` - Noop handler calls due to sampling/filtering/rate-limiting + `:allowed` - Other handler calls (no sampling/filtering/rate-limiting) + + `:suppressed` - Noop handler calls due to nil middleware result + `:handled` - Handler calls that completed successfully + `:errors` - Handler calls that threw an error + + Note that for performance reasons returned counts are not mutually atomic, + e.g. `:sampled` count may be incremented before `:disallowed` count is. + +Useful for understanding/debugging how your handlers behave in practice, +especially when they're under stress (high-volumes, etc.). + +Handler stats are tracked from the time each handler is last registered +(e.g. with an `add-handler!` call).get-min-levels
clj
cljs
(get-min-levels)(get-min-levels kind)(get-min-levels kind ns)Returns current ?{:keys [compile-time runtime]} minimum signal levels.handler:console
clj
cljs
(handler:console)(handler:console {:keys [output-fn], :or {output-fn (utils/format-signal-fn)}})Experimental, subject to change. If `js/console` exists, returns a (fn handler [signal]) that: @@ -320,37 +284,10 @@ Ref. <https://github.com Options: `:preamble-fn` - (fn [signal]) => string. - `:format-nsecs-fn` - (fn [nanosecs]) => string.help:filters
clj
cljs
Your filter config determines which signal calls will be allowed. + `:format-nsecs-fn` - (fn [nanosecs]) => string.help:environmental-config
clj
cljs
Telemere supports extensive environmental config via JVM properties, +environment variables, or classpath resources. - Filtering can occur at compile-time, runtime, or both. - Compile-time filtering elides (permanently removes!) code for - disallowed signals. Most users will want only runtime filtering. - - Both compile-time and runtime config can be specified via - environmental config (JVM properties, environment variables, or - classpath resources) [1]. - - Runtime config can also be specified with: - - `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant) - `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace - `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant) - `set-min-level!`, `with-min-level!` - for filtering calls by signal level - - See the relevant docstrings for details. - - Filtering can also be applied per handler, see `add-handler!` for details. - - See also: - - `get-filters` - to see current filter config - `get-min-level` - to see current minimum level - `without-filters` - to disable all runtime filtering - - If anything is unclear, please ping me (@ptaoussanis) so that I can - improve these docs! - - [1] Environmental filter config includes: +Environmental filter config includes: Kind filter: JVM property: `taoensso.telemere.rt-kind-filter.edn` @@ -375,10 +312,12 @@ Options: Examples: `taoensso.telemere.rt-min-level.edn` -> ":info" - `TAOENSSO_TELEMERE_RT_NS_FILTER_EDN` -> "{:deny \"taoensso.*\"}" + `TAOENSSO_TELEMERE_RT_NS_FILTER_EDN` -> "{:disallow \"taoensso.*\"}" `taoensso.telemere.rt-id-filter.cljs.edn` -> "#{:my-id1 :my-id2}" `TAOENSSO_TELEMERE_RT_KIND_FILTER_CLJ_EDN` -> "nil" +For other (non-filter) environmental config, see the relevant docstrings. + Tips: - The above ids are for runtime filters (the most common). @@ -401,16 +340,174 @@ Tips: - Classpath resources are files accessible on your project's classpath. This usually includes files in your project's - `resources/` dir.help:filters
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: - `get-handlers` - Returns info on registered handlers - `shut-down-handlers!` - Shuts down registered handlers + 1. Signal (creation) is allowed by compile-time "signal filters" + 2. Signal (creation) is allowed by runtime "signal filters" + 3. Signal (handling) is allowed by runtime "handler filters" - `add-handler!` - Registers given handler - `remove-handler!` - Unregisters given handler + 4. Signal middleware does not suppress the signal (return nil) + 5. Handler middleware does not suppress the signal (return nil) + +So we have: + + - Signal filters - applied at compile-time and/or runtime, + determine which signals are/not created. + + - Handler filters - applied at runtime only, determine which (created) + signals are/not handled by each registered handler. + +All filters (1-3) may depend on (in order): + + Sample rate → namespace → kind → id → level → when form/fn → rate limit + +Setting signal filters (1-2): + + Both compile-time and runtime signal filters can be specified via environmental + config (see `help:environmental-config` for details). + + Runtime signal filters can also be specified with: + + `with-kind-filter`, `set-kind-filter!` - filters by signal kind (when relevant) + `with-ns-filter`, `set-ns-filter!` - filters by signal namespace + `with-id-filter`, `set-id-filter!` - filters by signal id (when relevant) + `with-min-level`, `set-min-level!` - filters by signal level + +Setting handler filters (3): + + These are set when calling `add-handler!` or `with-handler/+`, + see `help:handler-dispatch-options` for details. + + Note that signal filters should generally be AT LEAST as permissive as handler + filters, otherwise signals will be suppressed before reaching handlers. + +Compile-time vs runtime filters: + + Compile-time filters are an advanced feature that can be tricky to set + and use correctly. Most folks will want ONLY runtime filters. + + Compile-time filters works by eliding (completely removing the code for) + disallowed signals. This means zero performance cost for these signals, + but also means that compile-time filters are PERMANENT once applied. + + So if you set `:info` as the compile-time minimum level, that'll REMOVE + CODE for every signal below `:info` level. To decrease that minimum level, + you'll need to rebuild. + + Compile-time filters can be set ONLY with environmental config + (see `help:environmental-config` for details). + +Signal and handler sampling is multiplicative: + + Both signals and handlers can have independent sample rates, and these + MULTIPLY! If a signal is created with 20% sampling and a handler + handles 50% of received signals, then 10% of possible signals will be + handled (50% of 20%). + + The final (multiplicative) rate is helpfully reflected in each signal's + `:sample-rate` value. + +For more info: + + - On signal filters, see: `help:filters` + - On handler filters, see: `help:handler-dispatch-options` + +If anything is unclear, please ping me (@ptaoussanis) so that I can +improve these docs!help:handler-dispatch-options
clj
cljs
Dispatch options can be provided for each signal handler when calling +`add-handler!` or `with-handler/+`. These options will be merged over the +defaults specified by `default-handler-dispatch-opts`. + +All handlers support the same dispatch options, including: + + `:async` (Clj only) options include: + + `:buffer-size` (default 1024) + Size of request buffer, and the max number of pending requests before + configured back-pressure behaviour is triggered (see `:mode`). + + `:mode` (default `:blocking`) + Back-pressure mode ∈ #{:blocking :dropping :sliding}. + Controls what happens when a new request is made while request buffer is full: + `:blocking` => Blocks caller until buffer space is available + `:dropping` => Drops the newest request (noop) + `:sliding` => Drops the oldest request + + `:n-threads` (default 1) + Number of threads to use for executing fns (servicing request buffer). + NB execution order may be non-sequential when n > 1. + + `:drain-msecs` (default 6000 msecs) + Maximum time (in milliseconds) to try allow pending execution requests to + complete during JVM shutdown, etc. See `*auto-stop-handlers?*` for more. + + `:needs-stopping?` (default false) + Enable this (only) for handlers that need to close/release resources or otherwise + finalize themselves. Iff true, `handler-fn` will be called with no arguments when: + 1. Handler is removed by `remove-handler!` call + 2. Handler is removed after `with-handler/+` call + 3. `stop-handlers!` is called (typically on system shutdown) + + `:priority` (default 100) + Optional handler priority ∈ℤ. + Handlers will be called in descending priority order. + + `:sample-rate` (default nil => no sampling) + Optional sample rate ∈ℝ[0,1], or (fn dyamic-sample-rate []) => ℝ[0,1]. + When present, handle only this (random) proportion of args: + 1.0 => handle every arg (same as `nil` rate, default) + 0.0 => noop every arg + 0.5 => handle random 50% of args + + `:kind-filter` - Kind filter as in `set-kind-filter!` (when relevant) + `:ns-filter` - Namespace filter as in `set-ns-filter!` + `:id-filter` - Id filter as in `set-id-filter!` (when relevant) + `:min-level` - Minimum level as in `set-min-level!` + + `:when-fn` (default nil => always allow) + Optional nullary (fn allow? []) that must return truthy for handler to be + called. When present, called *after* sampling and other filters, but before + rate limiting. + + `:rate-limit` (default nil => no rate limit) + Optional rate limit spec as provided to `taoensso.encore/rate-limiter`, + {<limit-id> [<n-max-calls> <msecs-window>]}. + + Examples: + {"1/sec" [1 1000]} => Max 1 call per 1000 msecs + {"1/sec" [1 1000] + "10/min" [10 60000]} => Max 1 call per 1000 msecs, + and 10 calls per 60 secs + + `:middleware` (default nil => no middleware) + Optional (fn [signal]) => ?modified-signal to apply before + handling signal. When middleware returns nil, skips handler. + + Compose multiple middleware fns together with `comp-middleware`. + + `:error-fn` - (fn [{:keys [handler-id signal error]}]) to call on handler error. + `:backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back-pressure. + +If anything is unclear, please ping me (@ptaoussanis) so that I can +improve these docs!help:handlers
clj
cljs
Signal handlers process created signals to do something with them (analyse them, + write them to console/file/queue/db, etc.). + +Manage handlers with: + + `get-handlers` - Returns info on registered handlers (dispatch options, etc.) + `get-handlers-stats` - Returns stats for registered handlers (handling times, etc.) + `stop-handlers!` - Stops (relevant) registered handlers + + `add-handler!` - Registers given handler + `remove-handler!` - Unregisters given handler + + `with-handler` - Executes form with ONLY the given handler registered + `with-handler+` - Executes form with the given handler (also) registered See the relevant docstrings for details. -Clj only: `shut-down-handlers!` is called automatically on JVM shutdown. +See `help:handler-dispatch-options` for handler filters, etc. + +Clj only: `stop-handlers!` is called automatically on JVM shutdown +when `*auto-stop-handlers?*` is true (it is by default). If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!help:signal-content
clj
cljs
Signals are maps with {:keys [inst id ns level data msg_ ...]}, @@ -479,58 +576,10 @@ and return values), making them more/less convenient for certain use cases: - `log!` emphasizes messages, while `event!` emphasizes ids. - `signal!` is the generic creator, and is used by all the others. -------------------------------------------------------------------- +---------------------------------------------------------------------- [2] See `help:signal-options` - {:keys [kind level id data ...]} [3] See `help:signal-content` - {:keys [kind level id data ...]} -[4] See `help:signal-flow` - (filters, handling, etc.)help:signal-flow
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: - - 1. Signal (creation) is allowed by compile-time filters - 2. Signal (creation) is allowed by runtime filters - 3. Signal (handling) is allowed by handler filters - - 4. Signal middleware does not suppress the signal (return nil) - 5. Handler middleware does not suppress the signal (return nil) - -For 1-3, filtering may depend on (in order): - - Sample rate → namespace → kind → id → level → when form/fn → rate limit - -Compile-time vs runtime filtering: - - Compile-time filtering is an advanced feature that can be tricky to set - and use correctly. Most folks will want ONLY runtime filtering. - - Compile-time filtering works by eliding (completely removing the code for) - disallowed signals. This means zero performance cost for these signals, - but also means that compile-time filtering is PERMANENT once applied. - - So if you set `:info` as the compile-time minimum level, that'll REMOVE - CODE for every signal call below `:info` level. To decrease that minimum - level, you'll need to rebuild. - - Compile-time filtering can be set ONLY with environmental config - (JVM properties, environment variables, or classpath resources). - -Signal and handler sampling is multiplicative: - - Both signals and handlers can have independent sample rates, and these - MULTIPLY! - - If a signal is created with 20% sampling and a handler handles 50% - of received signals, then 10% of possible signals will be handled - (50% of 20%). - - The multiplicative rate is helpfully reflected in each signal's final - `:sample-rate` value. - -For more info: - - - Signal visual flowchart, Ref. <https://www.taoensso.com/telemere/flow> - - On signal filters, see: `help:signal-filters` docstring - - On handler filters, see: `help:signal-handlers` docstring - -If anything is unclear, please ping me (@ptaoussanis) so that I can -improve these docs!help:signal-options
clj
cljs
Signal options (shared by all signal creators): +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)help:signal-options
clj
cljs
Signal options (shared by all signal creators): `:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>} `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} @@ -597,11 +646,11 @@ Tips: - `msg` arg may be a string, or vector of strings to join with `\space`. - See also `msg-splice`, `msg-skip` utils. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)msg-splice
clj
cljs
(msg-splice args)For use within signal message vectors. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)msg-splice
clj
cljs
(msg-splice args)For use within signal message vectors. Wraps given arguments so that they're spliced when creating message. Useful for conditionally splicing in extra message content, etc.: @@ -658,26 +707,26 @@ Example: (if-let [fail (my-rate-limiter username)] (throw (ex-info "Sorry, rate limited!" {:fail fail})) <send message>))remove-handler!
clj
cljs
(remove-handler! handler-id)Deregisters signal handler with given id, and returns -?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers +?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all handlers still registered.set-ctx!
macro
clj
cljs
(set-ctx! root-ctx-val)Set `*ctx*` var's root (base) value. See `*ctx*` for details. -set-id-filter!
clj
cljs
(set-id-filter! id-filter)Sets signal call id filter based on given `id-filter` spec. +set-id-filter!
clj
cljs
(set-id-filter! id-filter)Sets signal id filter based on given `id-filter` spec. `id-filter` may be: - A str/kw/sym, in which "*"s act as wildcards. - A regex pattern of id/s to allow. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above. - If present, `:allow` spec MUST match, AND - If present, `:deny` spec MUST NOT match.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal call kind filter based on given `kind-filter` spec. + - {:allow <spec> :disallow <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:disallow` spec MUST NOT match.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal kind filter based on given `kind-filter` spec. `kind-filter` may be: - A str/kw/sym, in which "*"s act as wildcards. - A regex pattern of kind/s to allow. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above. - If present, `:allow` spec MUST match, AND - If present, `:deny` spec MUST NOT match.set-middleware!
macro
clj
cljs
(set-middleware! ?root-middleware-fn)Set `*middleware*` var's root (base) value. See `*middleware*` for details. -set-min-level!
clj
cljs
(set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)Sets minimum signal call level based on given `min-level` spec. + - {:allow <spec> :disallow <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:disallow` spec MUST NOT match.set-middleware!
macro
clj
cljs
(set-middleware! ?root-middleware-fn)Set `*middleware*` var's root (base) value. See `*middleware*` for details. +set-min-level!
clj
cljs
(set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)Sets minimum signal level based on given `min-level` spec. `min-level` may be: - `nil` (=> no minimum level). @@ -692,28 +741,23 @@ If non-nil `kind` is provided, then the given minimum level will apply only for that signal kind. Examples: - (set-min-level! nil) ; Disable minimum level (set-min-level! :info) ; Set `:info` as minimum level (set-min-level! 100) ; Set 100 as minimum level ;; Set `:debug` as minimum level for current namespace - ;; (nil `kind` => apply to all kinds) - (set-min-level! nil *ns* :debug)set-ns-filter!
clj
cljs
(set-ns-filter! ns-filter)Sets signal call namespace filter based on given `ns-filter` spec. + ;; (nil `kind` => all kinds) + (set-min-level! nil *ns* :debug)set-ns-filter!
clj
cljs
(set-ns-filter! ns-filter)Sets signal namespace filter based on given `ns-filter` spec. `ns-filter` may be: - A namespace. - A str/kw/sym, in which "*"s act as wildcards. - A regex pattern of namespace/s to allow. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above. - If present, `:allow` spec MUST match, AND - If present, `:deny` 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!`.shut-down-handlers!
clj
cljs
(shut-down-handlers!)Shuts down all registered signal handlers in parallel, and returns -?{<handler-id> {:keys [okay error]}}. - -Future calls to handlers will no-op. -Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]})Low-level generic signal creator. + - {: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 ctx parent trace? do let data msg error run & kvs]})Low-level generic signal creator. API: [opts] => depends on options [2] Default kind: none (optional) @@ -736,11 +780,11 @@ Tips: - Test using `with-signal`: (with-signal (signal! ...)). - Supports the same options [2] as other signals [1]. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)spy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)"Spy" signal creator, emphasizing form + level. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)spy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent 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` @@ -776,11 +820,17 @@ Tips: - Can be useful to wrap with `catch->error!`: (catch->error! ::error-id (spy! ...)). -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)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 ctx parent trace? do let data msg error run & kvs]} form)"Trace" signal creator, emphasizing form + id. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)stop-handlers!
clj
cljs
(stop-handlers!)Stops relevant registered signal handlers in parallel, and returns +?{<handler-id> {:keys [okay error]}}. + +Future calls to stopped handlers will noop. + +Clj only: `stop-handlers!` is called automatically on JVM shutdown +when `*auto-stop-handlers?*` is true (it is by default).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 ctx parent 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` @@ -820,11 +870,11 @@ Tips: refers to the general action of tracing program flow rather than to the common logging level of the same name. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, 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 ctx parent 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 sample-rate kind ns id level when rate-limit ctx parent 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 @@ -840,19 +890,19 @@ See also `set-var-root!`.with-err->telemere
macro
clj
cljs
(with-err->telemere form)(with-err->telemere opts form)Executes form with `*err*` bound to flush to Telemere signals with given opts. -with-handler
macro
clj
cljs
(with-handler handler-id handler-fn dispatch-opts form)Executes form with ONLY the given handler-fn registered. +with-handler
macro
clj
cljs
(with-handler handler-id handler-fn form)(with-handler handler-id handler-fn dispatch-opts form)Executes form with ONLY the given signal handler registered. Useful for tests/debugging. -See `add-handler!` for info on `dispatch-opts`. -See also `with-handler+`.with-handler+
macro
clj
cljs
(with-handler+ handler-id handler-fn dispatch-opts form)Executes form with the given handler-fn registered. +See `help:handler-dispatch-options` for handler filters, etc. +See also `with-handler+`.with-handler+
macro
clj
cljs
(with-handler+ handler-id handler-fn form)(with-handler+ handler-id handler-fn dispatch-opts form)Executes form with the given signal handler (also) registered. Useful for tests/debugging. -See `add-handler!` for info on `dispatch-opts`. -See also `with-handler`.with-id-filter
macro
clj
cljs
(with-id-filter id-filter form)Executes form with given signal call 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 call kind filter in effect. +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-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 call 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 call namespace filter in effect. +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.with-signal
macro
clj
cljs
(with-signal form)(with-signal trap-signals? form)(with-signal raw-msg? trap-signals? form)Experimental. Executes given form, trapping errors. Returns the LAST signal created by form. @@ -870,5 +920,5 @@ Options: See also `with-signals`.with-signals
macro
clj
cljs
(with-signals form)(with-signals trap-signals? form)(with-signals raw-msgs? trap-signals? form)Experimental. Like `with-signal` but returns [[<form-value> <form-error>] [<signal1> ...]]. Useful for tests/debugging.with-streams->telemere
macro
clj
cljs
(with-streams->telemere form)(with-streams->telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals -with given opts.without-filters
macro
clj
cljs
(without-filters form)Executes form without any runtime filters. +with given opts.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>\ No newline at end of file diff --git a/taoensso.telemere.open-telemetry.html b/taoensso.telemere.open-telemetry.html index 9acdc97..15ddf8a 100644 --- a/taoensso.telemere.open-telemetry.html +++ b/taoensso.telemere.open-telemetry.html @@ -1,6 +1,6 @@ -*ctx*
dynamic
clj
cljs
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals. + <https://www.taoensso.com/telemere>*auto-stop-handlers?*
dynamic
clj
Automatically call `stop-handlers!` on JVM shutdown iff this is +enabled (it is by default). Advanced users may want to disable this in order +to instead call `stop-handlers!` manually as part of their own shutdown +procedure (e.g. AFTER successful app shutdown).*ctx*
dynamic
clj
cljs
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals. Value may be any type, but is usually nil or a map. Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`. @@ -22,103 +25,25 @@ Compose multiple middleware fns together with `comp-middleware`. Re/bind dynamic value using `with-middleware`, `binding`. Modify root (base) value using `set-middleware!`.add-handler!
clj
cljs
(add-handler! handler-id handler-fn)(add-handler! handler-id handler-fn dispatch-opts)Registers given signal handler and returns -{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers +{<handler-id> {:keys [dispatch-opts handler-fn]}} for all handlers now registered. -`handler-fn` should be a fn of 2 arities: +`handler-fn` should be a fn of 1 or 2 arities: - [handler-arg] ; Handle the given argument (e.g. write to disk/db, etc.) - [] ; Called exactly once on system shutdown to provide an opportunity for - handler to close/release any resources that it may have opened/acquired. - See also `:max-shutdown-msecs` dispatch option. + [signal] ; Single argument + Called asynchronously or synchronously (depending on dispatch options) + to do something useful with the given signal. -See the relevant docstring/s for `handler-arg` details. + Example actions: + Save data to disk or db, `tap>`, log, `put!` to an appropriate + `core.async` channel, filter, aggregate, use for a realtime analytics + dashboard, examine for outliers or unexpected data, etc. -Handler ideas: + [] ; No arguments + Called exactly once when gracefully stopping handler to provide an opportunity + for handler to close/release any resources that it may have opened/acquired, etc. - Save to a db, `tap>`, log, `put!` to an appropriate `core.async` - channel, filter, aggregate, use for a realtime analytics dashboard, - examine for outliers or unexpected data, etc. - -Dispatch options include (see also `default-handler-dispatch-opts`): - - `:async` (Clj only) - Options for running handler asynchronously via `taoensso.encore/runner`, - {:keys [mode buffer-size n-threads daemon-threads? ...]} - - Supports `:blocking`, `:dropping`, and `:sliding` back-pressure modes. - NB handling order may be non-sequential when `n-threads` > 1. - - Options: - `:mode` - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}. - `:buffer-size` - Size of buffer before back-pressure mechanism is engaged. - `:n-threads` - Number of threads for asynchronously executing fns. - NB execution order may be non-sequential when n > 1. - - Default: {:mode :blocking, :buffer-size 1024, :n-threads 1 ...}, - i.e. async but will block when >1024 handler-args already waiting. - - `:max-shutdown-msecs` (Clj only) - Maximum time (in milliseconds) that handler will block system shutdown - to drain its async buffer and/or close/release its resources. - - `:priority` - Optional handler priority ∈ℤ (default 100). - Handlers will be called in descending priority order. - - `:sample-rate` - Optional sample rate ∈ℝ[0,1], or (fn dyamic-sample-rate []) => ℝ[0,1]. - When present, handle only this (random) proportion of args: - 1.0 => handle every arg (same as `nil` rate, default) - 0.0 => noop every arg - 0.5 => handle random 50% of args - - `:kind-filter` - Kind filter as in `set-kind-filter!` (when relevant) - `:ns-filter` - Namespace filter as in `set-ns-filter!` - `:id-filter` - Id filter as in `set-id-filter!` (when relevant) - `:min-level` - Minimum level as in `set-min-level!` - - `:when-fn` - Optional nullary (fn allow? []) that must return truthy for handler to be - called. When present, called *after* sampling and other filters, but before - rate limiting. - - `:rate-limit` - Optional rate limit spec as provided to `taoensso.encore/rate-limiter`, - {<limit-id> [<n-max-calls> <msecs-window>]}. - - Examples: - {"1/sec" [1 1000]} => Max 1 call per 1000 msecs - {"1/sec" [1 1000] - "10/min" [10 60000]} => Max 1 call per 1000 msecs, - and 10 calls per 60 secs - - `:middleware` - Optional (fn [handler-arg]) => ?modified-handler-arg to apply before - handling. When middleware returns nil, skips handler. - - Compose multiple middleware fns together with `comp-middleware`. - - `:error-fn` - (fn [{:keys [handler-id handler-arg error]}]) to call on handler error. - `:backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back-pressure. - -Flow sequence: - - 1. Per call (n=1) - a. Sampling - b. Filtering (kind, namespace, id, level, when-form) - c. Rate limiting - d. Middleware - - 2. Per handler (n>=0) - a. Sampling - b. Filtering (kind, namespace, id, level, when-fn) - c. Rate limiting - d. Middleware - e. Hander fn - - Note: call filters should generally be at least as permissive as handler filters, - otherwise calls will be suppressed before reaching handlers.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 ctx parent 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 sample-rate kind ns id level when rate-limit ctx parent 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], @@ -151,11 +76,11 @@ Tips: See also `error!`. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)chance
clj
cljs
(chance prob)Returns true with given probability ∈ ℝ[0,1]. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)check-intakes
clj
(check-intakes)Experimental, subject to change. Runs Telemere's registered intake checks and returns {<source-id> {:keys [sending->telemere? telemere-receiving? ...]}}. @@ -171,8 +96,8 @@ Useful for composing Ring-style middleware fns.default-handler-dispatch-opts
clj
cljs
Default `add-handler!` dispatch options. -See `add-handler!` docstring 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 ctx parent trace? do let data msg error & kvs]} error)"Error" signal creator, emphasizing error + id. +See `get-env` for details.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 ctx parent 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` @@ -198,11 +123,11 @@ Tips: - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`). - Can conveniently be wrapped by `throw`: (throw (error! ...)). -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)error-signal?
clj
cljs
(error-signal? signal)Experimental, subject to change. +[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 ctx parent trace? do let data msg error & kvs]})"Event" signal creator, emphasizing id + level. @@ -235,11 +160,11 @@ Tips: Mnemonic: the arg that's typically larger is *always* in the rightmost position, and for `event!` that's the `level-or-opts` arg. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)format-signal-fn
clj
cljs
(format-signal-fn)(format-signal-fn {:keys [incl-newline? preamble-fn content-fn], :or {incl-newline? true, preamble-fn (signal-preamble-fn), content-fn (signal-content-fn)}})Experimental, subject to change. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)format-signal-fn
clj
cljs
(format-signal-fn)(format-signal-fn {:keys [incl-newline? preamble-fn content-fn], :or {incl-newline? true, preamble-fn (signal-preamble-fn), content-fn (signal-content-fn)}})Experimental, subject to change. Returns a (fn format [signal]) that: - Takes a Telemere signal (map). - Returns a human-readable signal string. @@ -302,8 +227,50 @@ macro-expansion. Symbols in edn will be evaluated during expansion. TIP!: Use the {:return :explain} option in tests or at the REPL to verify/inspect resulting config value, config source, and specific search order of prop/env/res ids.get-handlers
clj
cljs
(get-handlers)Returns ?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all -registered signal handlers.get-min-level
clj
cljs
(get-min-level)(get-min-level kind)(get-min-level kind ns)Returns current ?{:keys [compile-time runtime]} minimum levels. +get-handlers
clj
cljs
(get-handlers)Returns ?{<handler-id> {:keys [dispatch-opts handler-fn handler-stats_]}} +for all registered signal handlers.get-handlers-stats
clj
cljs
(get-handlers-stats)Alpha, subject to change. +Returns ?{<handler-id> {:keys [handling-nsecs counts]}} for all registered +signal handlers that have the `:track-stats?` dispatch option enabled +(it is by default). + +Stats include: + + `:handling-nsecs` - Summary stats of nanosecond handling times, keys: + `:min` - Minimum handling time + `:max` - Maximum handling time + `:mean` - Arithmetic mean handling time + `:mad` - Mean absolute deviation of handling time (measure of dispersion) + `:var` - Variance of handling time (measure of dispersion) + `:p50` - 50th percentile of handling time (50% of times <= this) + `:p90` - 90th percentile of handling time (90% of times <= this) + `:p99` - 99th percentile of handling time + `:last` - Most recent handling time + ... + + `:counts` - Integer counts for handler outcomes, keys (chronologically): + + `:dropped` - Noop handler calls due to stopped handler + `:back-pressure` - Handler calls that experienced (async) back-pressure + (possible noop, depending on back-pressure mode) + + `:sampled` - Noop handler calls due to sample rate + `:filtered` - Noop handler calls due to kind/ns/id/level/when filtering + `:rate-limited` - Noop handler calls due to rate limit + `:disallowed` - Noop handler calls due to sampling/filtering/rate-limiting + `:allowed` - Other handler calls (no sampling/filtering/rate-limiting) + + `:suppressed` - Noop handler calls due to nil middleware result + `:handled` - Handler calls that completed successfully + `:errors` - Handler calls that threw an error + + Note that for performance reasons returned counts are not mutually atomic, + e.g. `:sampled` count may be incremented before `:disallowed` count is. + +Useful for understanding/debugging how your handlers behave in practice, +especially when they're under stress (high-volumes, etc.). + +Handler stats are tracked from the time each handler is last registered +(e.g. with an `add-handler!` call).get-min-levels
clj
cljs
(get-min-levels)(get-min-levels kind)(get-min-levels kind ns)Returns current ?{:keys [compile-time runtime]} minimum signal levels.handler:console
clj
cljs
(handler:console)(handler:console {:keys [stream output-fn], :or {stream :auto, output-fn (utils/format-signal-fn)}})Experimental, subject to change. Returns a (fn handler [signal]) that: @@ -348,37 +315,10 @@ Options: Maximum number of numbered archives to retain for any particular interval. `:max-num-intervals` ∈ #{nil <pos-int>} (default 6) - Maximum number of intervals (days/weeks/months) to retain.help:filters
clj
cljs
Your filter config determines which signal calls will be allowed. + Maximum number of intervals (days/weeks/months) to retain.help:environmental-config
clj
cljs
Telemere supports extensive environmental config via JVM properties, +environment variables, or classpath resources. - Filtering can occur at compile-time, runtime, or both. - Compile-time filtering elides (permanently removes!) code for - disallowed signals. Most users will want only runtime filtering. - - Both compile-time and runtime config can be specified via - environmental config (JVM properties, environment variables, or - classpath resources) [1]. - - Runtime config can also be specified with: - - `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant) - `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace - `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant) - `set-min-level!`, `with-min-level!` - for filtering calls by signal level - - See the relevant docstrings for details. - - Filtering can also be applied per handler, see `add-handler!` for details. - - See also: - - `get-filters` - to see current filter config - `get-min-level` - to see current minimum level - `without-filters` - to disable all runtime filtering - - If anything is unclear, please ping me (@ptaoussanis) so that I can - improve these docs! - - [1] Environmental filter config includes: +Environmental filter config includes: Kind filter: JVM property: `taoensso.telemere.rt-kind-filter.edn` @@ -403,10 +343,12 @@ Options: Examples: `taoensso.telemere.rt-min-level.edn` -> ":info" - `TAOENSSO_TELEMERE_RT_NS_FILTER_EDN` -> "{:deny \"taoensso.*\"}" + `TAOENSSO_TELEMERE_RT_NS_FILTER_EDN` -> "{:disallow \"taoensso.*\"}" `taoensso.telemere.rt-id-filter.cljs.edn` -> "#{:my-id1 :my-id2}" `TAOENSSO_TELEMERE_RT_KIND_FILTER_CLJ_EDN` -> "nil" +For other (non-filter) environmental config, see the relevant docstrings. + Tips: - The above ids are for runtime filters (the most common). @@ -429,16 +371,174 @@ Tips: - Classpath resources are files accessible on your project's classpath. This usually includes files in your project's - `resources/` dir.help:filters
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: - `get-handlers` - Returns info on registered handlers - `shut-down-handlers!` - Shuts down registered handlers + 1. Signal (creation) is allowed by compile-time "signal filters" + 2. Signal (creation) is allowed by runtime "signal filters" + 3. Signal (handling) is allowed by runtime "handler filters" - `add-handler!` - Registers given handler - `remove-handler!` - Unregisters given handler + 4. Signal middleware does not suppress the signal (return nil) + 5. Handler middleware does not suppress the signal (return nil) + +So we have: + + - Signal filters - applied at compile-time and/or runtime, + determine which signals are/not created. + + - Handler filters - applied at runtime only, determine which (created) + signals are/not handled by each registered handler. + +All filters (1-3) may depend on (in order): + + Sample rate → namespace → kind → id → level → when form/fn → rate limit + +Setting signal filters (1-2): + + Both compile-time and runtime signal filters can be specified via environmental + config (see `help:environmental-config` for details). + + Runtime signal filters can also be specified with: + + `with-kind-filter`, `set-kind-filter!` - filters by signal kind (when relevant) + `with-ns-filter`, `set-ns-filter!` - filters by signal namespace + `with-id-filter`, `set-id-filter!` - filters by signal id (when relevant) + `with-min-level`, `set-min-level!` - filters by signal level + +Setting handler filters (3): + + These are set when calling `add-handler!` or `with-handler/+`, + see `help:handler-dispatch-options` for details. + + Note that signal filters should generally be AT LEAST as permissive as handler + filters, otherwise signals will be suppressed before reaching handlers. + +Compile-time vs runtime filters: + + Compile-time filters are an advanced feature that can be tricky to set + and use correctly. Most folks will want ONLY runtime filters. + + Compile-time filters works by eliding (completely removing the code for) + disallowed signals. This means zero performance cost for these signals, + but also means that compile-time filters are PERMANENT once applied. + + So if you set `:info` as the compile-time minimum level, that'll REMOVE + CODE for every signal below `:info` level. To decrease that minimum level, + you'll need to rebuild. + + Compile-time filters can be set ONLY with environmental config + (see `help:environmental-config` for details). + +Signal and handler sampling is multiplicative: + + Both signals and handlers can have independent sample rates, and these + MULTIPLY! If a signal is created with 20% sampling and a handler + handles 50% of received signals, then 10% of possible signals will be + handled (50% of 20%). + + The final (multiplicative) rate is helpfully reflected in each signal's + `:sample-rate` value. + +For more info: + + - On signal filters, see: `help:filters` + - On handler filters, see: `help:handler-dispatch-options` + +If anything is unclear, please ping me (@ptaoussanis) so that I can +improve these docs!help:handler-dispatch-options
clj
cljs
Dispatch options can be provided for each signal handler when calling +`add-handler!` or `with-handler/+`. These options will be merged over the +defaults specified by `default-handler-dispatch-opts`. + +All handlers support the same dispatch options, including: + + `:async` (Clj only) options include: + + `:buffer-size` (default 1024) + Size of request buffer, and the max number of pending requests before + configured back-pressure behaviour is triggered (see `:mode`). + + `:mode` (default `:blocking`) + Back-pressure mode ∈ #{:blocking :dropping :sliding}. + Controls what happens when a new request is made while request buffer is full: + `:blocking` => Blocks caller until buffer space is available + `:dropping` => Drops the newest request (noop) + `:sliding` => Drops the oldest request + + `:n-threads` (default 1) + Number of threads to use for executing fns (servicing request buffer). + NB execution order may be non-sequential when n > 1. + + `:drain-msecs` (default 6000 msecs) + Maximum time (in milliseconds) to try allow pending execution requests to + complete during JVM shutdown, etc. See `*auto-stop-handlers?*` for more. + + `:needs-stopping?` (default false) + Enable this (only) for handlers that need to close/release resources or otherwise + finalize themselves. Iff true, `handler-fn` will be called with no arguments when: + 1. Handler is removed by `remove-handler!` call + 2. Handler is removed after `with-handler/+` call + 3. `stop-handlers!` is called (typically on system shutdown) + + `:priority` (default 100) + Optional handler priority ∈ℤ. + Handlers will be called in descending priority order. + + `:sample-rate` (default nil => no sampling) + Optional sample rate ∈ℝ[0,1], or (fn dyamic-sample-rate []) => ℝ[0,1]. + When present, handle only this (random) proportion of args: + 1.0 => handle every arg (same as `nil` rate, default) + 0.0 => noop every arg + 0.5 => handle random 50% of args + + `:kind-filter` - Kind filter as in `set-kind-filter!` (when relevant) + `:ns-filter` - Namespace filter as in `set-ns-filter!` + `:id-filter` - Id filter as in `set-id-filter!` (when relevant) + `:min-level` - Minimum level as in `set-min-level!` + + `:when-fn` (default nil => always allow) + Optional nullary (fn allow? []) that must return truthy for handler to be + called. When present, called *after* sampling and other filters, but before + rate limiting. + + `:rate-limit` (default nil => no rate limit) + Optional rate limit spec as provided to `taoensso.encore/rate-limiter`, + {<limit-id> [<n-max-calls> <msecs-window>]}. + + Examples: + {"1/sec" [1 1000]} => Max 1 call per 1000 msecs + {"1/sec" [1 1000] + "10/min" [10 60000]} => Max 1 call per 1000 msecs, + and 10 calls per 60 secs + + `:middleware` (default nil => no middleware) + Optional (fn [signal]) => ?modified-signal to apply before + handling signal. When middleware returns nil, skips handler. + + Compose multiple middleware fns together with `comp-middleware`. + + `:error-fn` - (fn [{:keys [handler-id signal error]}]) to call on handler error. + `:backp-fn` - (fn [{:keys [handler-id ]}]) to call on handler back-pressure. + +If anything is unclear, please ping me (@ptaoussanis) so that I can +improve these docs!help:handlers
clj
cljs
Signal handlers process created signals to do something with them (analyse them, + write them to console/file/queue/db, etc.). + +Manage handlers with: + + `get-handlers` - Returns info on registered handlers (dispatch options, etc.) + `get-handlers-stats` - Returns stats for registered handlers (handling times, etc.) + `stop-handlers!` - Stops (relevant) registered handlers + + `add-handler!` - Registers given handler + `remove-handler!` - Unregisters given handler + + `with-handler` - Executes form with ONLY the given handler registered + `with-handler+` - Executes form with the given handler (also) registered See the relevant docstrings for details. -Clj only: `shut-down-handlers!` is called automatically on JVM shutdown. +See `help:handler-dispatch-options` for handler filters, etc. + +Clj only: `stop-handlers!` is called automatically on JVM shutdown +when `*auto-stop-handlers?*` is true (it is by default). If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!help:signal-content
clj
cljs
Signals are maps with {:keys [inst id ns level data msg_ ...]}, @@ -507,151 +607,10 @@ and return values), making them more/less convenient for certain use cases: - `log!` emphasizes messages, while `event!` emphasizes ids. - `signal!` is the generic creator, and is used by all the others. -------------------------------------------------------------------- +---------------------------------------------------------------------- [2] See `help:signal-options` - {:keys [kind level id data ...]} [3] See `help:signal-content` - {:keys [kind level id data ...]} -[4] See `help:signal-flow` - (filters, handling, etc.)help:signal-filters
clj
cljs
Your filter config determines which signal calls will be allowed. - - Filtering can occur at compile-time, runtime, or both. - Compile-time filtering elides (permanently removes!) code for - disallowed signals. Most users will want only runtime filtering. - - Both compile-time and runtime config can be specified via - environmental config (JVM properties, environment variables, or - classpath resources) [1]. - - Runtime config can also be specified with: - - `set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant) - `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace - `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant) - `set-min-level!`, `with-min-level!` - for filtering calls by signal level - - See the relevant docstrings for details. - - Filtering can also be applied per handler, see `add-handler!` for details. - - See also: - - `get-filters` - to see current filter config - `get-min-level` - to see current minimum level - `without-filters` - to disable all runtime filtering - - If anything is unclear, please ping me (@ptaoussanis) so that I can - improve these docs! - - [1] Environmental filter config includes: - - Kind filter: - JVM property: `taoensso.telemere.rt-kind-filter.edn` - Env variable: `TAOENSSO_TELEMERE_RT_KIND_FILTER_EDN` - Classpath resource: `taoensso.telemere.rt-kind-filter.edn` - - Namespace filter: - JVM property: `taoensso.telemere.rt-ns-filter.edn` - Env variable: `TAOENSSO_TELEMERE_RT_NS_FILTER_EDN` - Classpath resource: `taoensso.telemere.rt-ns-filter.edn` - - Id filter: - JVM property: `taoensso.telemere.rt-id-filter.edn` - Env variable: `TAOENSSO_TELEMERE_RT_ID_FILTER_EDN` - Classpath resource: `taoensso.telemere.rt-id-filter.edn` - - Minimum level: - JVM property: `taoensso.telemere.rt-min-level.edn` - Env variable: `TAOENSSO_TELEMERE_RT_MIN_LEVEL_EDN` - Classpath resource: `taoensso.telemere.rt-min-level.edn` - -Examples: - - `taoensso.telemere.rt-min-level.edn` -> ":info" - `TAOENSSO_TELEMERE_RT_NS_FILTER_EDN` -> "{:deny \"taoensso.*\"}" - `taoensso.telemere.rt-id-filter.cljs.edn` -> "#{:my-id1 :my-id2}" - `TAOENSSO_TELEMERE_RT_KIND_FILTER_CLJ_EDN` -> "nil" - -Tips: - - - The above ids are for runtime filters (the most common). - For compile-time filters, change `rt`->`ct` / `RT`->`CT`. - - - The above ids will affect both Clj AND Cljs. - For platform-specific filters, use - ".clj.edn" / "_CLJ_EDN" or - ".cljs.edn" / "_CLJS_EDN" suffixes instead. - - - ".edn" / "_EDN" suffixes are optional. - - - Config values should be edn. To get the right syntax, first set - your runtime filters using the standard utils (`set-min-level!`, - etc.). Then call `get-filters` and serialize the relevant parts - to edn with `pr-str`. - - - All environmental config uses `get-env` underneath. - See the `get-env` docstring for more/advanced details. - - - Classpath resources are files accessible on your project's - classpath. This usually includes files in your project's - `resources/` dir.help:signal-flow
clj
cljs
A signal will be provided to a handler iff ALL of the following are true: - - 1. Signal (creation) is allowed by compile-time filters - 2. Signal (creation) is allowed by runtime filters - 3. Signal (handling) is allowed by handler filters - - 4. Signal middleware does not suppress the signal (return nil) - 5. Handler middleware does not suppress the signal (return nil) - -For 1-3, filtering may depend on (in order): - - Sample rate → namespace → kind → id → level → when form/fn → rate limit - -Compile-time vs runtime filtering: - - Compile-time filtering is an advanced feature that can be tricky to set - and use correctly. Most folks will want ONLY runtime filtering. - - Compile-time filtering works by eliding (completely removing the code for) - disallowed signals. This means zero performance cost for these signals, - but also means that compile-time filtering is PERMANENT once applied. - - So if you set `:info` as the compile-time minimum level, that'll REMOVE - CODE for every signal call below `:info` level. To decrease that minimum - level, you'll need to rebuild. - - Compile-time filtering can be set ONLY with environmental config - (JVM properties, environment variables, or classpath resources). - -Signal and handler sampling is multiplicative: - - Both signals and handlers can have independent sample rates, and these - MULTIPLY! - - If a signal is created with 20% sampling and a handler handles 50% - of received signals, then 10% of possible signals will be handled - (50% of 20%). - - The multiplicative rate is helpfully reflected in each signal's final - `:sample-rate` value. - -For more info: - - - Signal visual flowchart, Ref. <https://www.taoensso.com/telemere/flow> - - On signal filters, see: `help:signal-filters` docstring - - On handler filters, see: `help:signal-handlers` docstring - -If anything is unclear, please ping me (@ptaoussanis) so that I can -improve these docs!help:signal-handlers
clj
cljs
Manage handlers with: - - `get-handlers` - Returns info on registered handlers - `shut-down-handlers!` - Shuts down registered handlers - - `add-handler!` - Registers given handler - `remove-handler!` - Unregisters given handler - -See the relevant docstrings for details. -Clj only: `shut-down-handlers!` is called automatically on JVM shutdown. - -If anything is unclear, please ping me (@ptaoussanis) so that I can -improve these docs!help:signal-options
clj
cljs
Signal options (shared by all signal creators): +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)help:signal-options
clj
cljs
Signal options (shared by all signal creators): `:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>} `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} @@ -719,12 +678,12 @@ Tips: - `msg` arg may be a string, or vector of strings to join with `\space`. - See also `msg-splice`, `msg-skip` utils. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)msg-skip
clj
cljs
For use within signal message vectors. -Special value that will be ignored (no-op) when creating message. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)msg-skip
clj
cljs
For use within signal message vectors. +Special value that will be ignored (noop) when creating message. Useful for conditionally skipping parts of message content, etc.: (signal! {:msg ["Hello" (if <cond> <then> msg-skip) "world"] <...>}) or @@ -787,26 +746,26 @@ Example: (if-let [fail (my-rate-limiter username)] (throw (ex-info "Sorry, rate limited!" {:fail fail})) <send message>))remove-handler!
clj
cljs
(remove-handler! handler-id)Deregisters signal handler with given id, and returns -?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers +?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all handlers still registered.set-ctx!
macro
clj
cljs
(set-ctx! root-ctx-val)Set `*ctx*` var's root (base) value. See `*ctx*` for details. -set-id-filter!
clj
cljs
(set-id-filter! id-filter)Sets signal call id filter based on given `id-filter` spec. +set-id-filter!
clj
cljs
(set-id-filter! id-filter)Sets signal id filter based on given `id-filter` spec. `id-filter` may be: - A str/kw/sym, in which "*"s act as wildcards. - A regex pattern of id/s to allow. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above. - If present, `:allow` spec MUST match, AND - If present, `:deny` spec MUST NOT match.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal call kind filter based on given `kind-filter` spec. + - {:allow <spec> :disallow <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:disallow` spec MUST NOT match.set-kind-filter!
clj
cljs
(set-kind-filter! kind-filter)Sets signal kind filter based on given `kind-filter` spec. `kind-filter` may be: - A str/kw/sym, in which "*"s act as wildcards. - A regex pattern of kind/s to allow. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above. - If present, `:allow` spec MUST match, AND - If present, `:deny` spec MUST NOT match.set-middleware!
macro
clj
cljs
(set-middleware! ?root-middleware-fn)Set `*middleware*` var's root (base) value. See `*middleware*` for details. -set-min-level!
clj
cljs
(set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)Sets minimum signal call level based on given `min-level` spec. + - {:allow <spec> :disallow <spec>} with specs as above. + If present, `:allow` spec MUST match, AND + If present, `:disallow` spec MUST NOT match.set-middleware!
macro
clj
cljs
(set-middleware! ?root-middleware-fn)Set `*middleware*` var's root (base) value. See `*middleware*` for details. +set-min-level!
clj
cljs
(set-min-level! min-level)(set-min-level! kind min-level)(set-min-level! kind ns-filter min-level)Sets minimum signal level based on given `min-level` spec. `min-level` may be: - `nil` (=> no minimum level). @@ -821,28 +780,23 @@ If non-nil `kind` is provided, then the given minimum level will apply only for that signal kind. Examples: - (set-min-level! nil) ; Disable minimum level (set-min-level! :info) ; Set `:info` as minimum level (set-min-level! 100) ; Set 100 as minimum level ;; Set `:debug` as minimum level for current namespace - ;; (nil `kind` => apply to all kinds) - (set-min-level! nil *ns* :debug)set-ns-filter!
clj
cljs
(set-ns-filter! ns-filter)Sets signal call namespace filter based on given `ns-filter` spec. + ;; (nil `kind` => all kinds) + (set-min-level! nil *ns* :debug)set-ns-filter!
clj
cljs
(set-ns-filter! ns-filter)Sets signal namespace filter based on given `ns-filter` spec. `ns-filter` may be: - A namespace. - A str/kw/sym, in which "*"s act as wildcards. - A regex pattern of namespace/s to allow. - A vector or set of regex patterns or strs/kws/syms. - - {:allow <spec> :deny <spec>} with specs as above. - If present, `:allow` spec MUST match, AND - If present, `:deny` 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!`.shut-down-handlers!
clj
cljs
(shut-down-handlers!)Shuts down all registered signal handlers in parallel, and returns -?{<handler-id> {:keys [okay error]}}. - -Future calls to handlers will no-op. -Clj only: `shut-down-handlers!` is called automatically on JVM shutdown.signal!
macro
clj
cljs
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]})Low-level generic signal creator. + - {: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 ctx parent trace? do let data msg error run & kvs]})Low-level generic signal creator. API: [opts] => depends on options [2] Default kind: none (optional) @@ -865,11 +819,11 @@ Tips: - Test using `with-signal`: (with-signal (signal! ...)). - Supports the same options [2] as other signals [1]. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)spy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & kvs]} form)"Spy" signal creator, emphasizing form + level. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)spy!
macro
clj
cljs
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent 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` @@ -905,11 +859,17 @@ Tips: - Can be useful to wrap with `catch->error!`: (catch->error! ::error-id (spy! ...)). -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, etc.)streams->reset!
clj
(streams->reset!)Experimental, subject to change. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)stop-handlers!
clj
cljs
(stop-handlers!)Stops relevant registered signal handlers in parallel, and returns +?{<handler-id> {:keys [okay error]}}. + +Future calls to stopped handlers will noop. + +Clj only: `stop-handlers!` is called automatically on JVM shutdown +when `*auto-stop-handlers?*` is true (it is by default).streams->reset!
clj
(streams->reset!)Experimental, subject to change. Resets `System/out` and `System/err` to their original value (prior to any `streams->telemere!` call).streams->telemere!
clj
(streams->telemere!)(streams->telemere! {:keys [out err], :or {out default-out-opts, err default-err-opts}})Experimental, subject to change. @@ -962,11 +922,11 @@ Tips: refers to the general action of tracing program flow rather than to the common logging level of the same name. -------------------------------------------------------------------- +---------------------------------------------------------------------- [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-flow` - (filters, handling, 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 ctx parent 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 sample-rate kind ns id level when rate-limit ctx parent 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 @@ -985,19 +945,19 @@ See also `set-var-root!`.with-err->telemere
macro
clj
cljs
(with-err->telemere form)(with-err->telemere opts form)Executes form with `*err*` bound to flush to Telemere signals with given opts. -with-handler
macro
clj
cljs
(with-handler handler-id handler-fn dispatch-opts form)Executes form with ONLY the given handler-fn registered. +with-handler
macro
clj
cljs
(with-handler handler-id handler-fn form)(with-handler handler-id handler-fn dispatch-opts form)Executes form with ONLY the given signal handler registered. Useful for tests/debugging. -See `add-handler!` for info on `dispatch-opts`. -See also `with-handler+`.with-handler+
macro
clj
cljs
(with-handler+ handler-id handler-fn dispatch-opts form)Executes form with the given handler-fn registered. +See `help:handler-dispatch-options` for handler filters, etc. +See also `with-handler+`.with-handler+
macro
clj
cljs
(with-handler+ handler-id handler-fn form)(with-handler+ handler-id handler-fn dispatch-opts form)Executes form with the given signal handler (also) registered. Useful for tests/debugging. -See `add-handler!` for info on `dispatch-opts`. -See also `with-handler`.with-id-filter
macro
clj
cljs
(with-id-filter id-filter form)Executes form with given signal call 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 call kind filter in effect. +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-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 call 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 call namespace filter in effect. +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.with-signal
macro
clj
cljs
(with-signal form)(with-signal trap-signals? form)(with-signal raw-msg? trap-signals? form)Experimental. Executes given form, trapping errors. Returns the LAST signal created by form. @@ -1015,5 +975,5 @@ Options: See also `with-signals`.with-signals
macro
clj
cljs
(with-signals form)(with-signals trap-signals? form)(with-signals raw-msgs? trap-signals? form)Experimental. Like `with-signal` but returns [[<form-value> <form-error>] [<signal1> ...]]. Useful for tests/debugging.with-streams->telemere
macro
clj
cljs
(with-streams->telemere form)(with-streams->telemere {:keys [out err], :or {out default-out-opts, err default-err-opts}} form)Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals -with given opts.without-filters
macro
clj
cljs
(without-filters form)Executes form without any runtime filters. +with given opts.taoensso.telemere.open-telemetry documentation taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`, +taoensso.telemere.open-telemetry documentation taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`, Ref. <https://github.com/open-telemetry/opentelemetry-java>.default-logger-provider
clj
(default-logger-provider)Experimental, subject to change. Feedback welcome! Returns `io.opentelemetry.api.logs.LoggerProvider` via: diff --git a/taoensso.telemere.postal.html b/taoensso.telemere.postal.html index 9a85358..c71ce28 100644 --- a/taoensso.telemere.postal.html +++ b/taoensso.telemere.postal.html @@ -1,6 +1,6 @@ -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 e781148..b14112c 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 407f423..e1a01b7 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 (fn handler [signal]) that: diff --git a/taoensso.telemere.streams.html b/taoensso.telemere.streams.html index 7db2199..a7ae0ce 100644 --- a/taoensso.telemere.streams.html +++ b/taoensso.telemere.streams.html @@ -1,6 +1,6 @@ -taoensso.telemere.streams documentation taoensso.telemere.streams
Intake support for standard stream/s -> Telemere. +taoensso.telemere.streams documentation taoensso.telemere.streams
Intake support for standard stream/s -> Telemere.check-err-intake
clj
(check-err-intake)Returns {:keys [sending->telemere? telemere-receiving?]}.check-out-intake
clj
(check-out-intake)Returns {:keys [sending->telemere? telemere-receiving?]}.streams->reset!
clj
(streams->reset!)Experimental, subject to change. diff --git a/taoensso.telemere.timbre.cljs.html b/taoensso.telemere.timbre.cljs.html index 4161b06..622f5aa 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 f3809af..ef7306a 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. @@ -22,7 +22,7 @@ Intended to help ease migration from Timbre to Telemere.reportf
macro
clj
(reportf & args)Prefer `telemere/log!`, etc.set-ns-min-level!
macro
clj
(set-ns-min-level! ?min-level)(set-ns-min-level! ns ?min-level)Prefer `telemere/set-min-level!`. -spy!
macro
clj
(spy! form)(spy! level form)(spy! level form-name form)Prefer `telemere/spy!`.trace
macro
clj
(trace & args)Prefer `telemere/log!`, etc.tracef
macro
clj
(tracef & args)Prefer `telemere/log!`, etc. diff --git a/taoensso.telemere.tools-logging.html b/taoensso.telemere.tools-logging.html index 3956809..6e9bab6 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
Intake support for `clojure.tools.logging` -> Telemere. +taoensso.telemere.tools-logging documentation taoensso.telemere.tools-logging
Intake support for `clojure.tools.logging` -> Telemere. Telemere will attempt to load this ns automatically when possible.check-intake
clj
(check-intake)Returns {:keys [present? sending->telemere? telemere-receiving?]}.tools-logging->telemere!
clj
(tools-logging->telemere!)Configures `clojure.tools.logging` to use Telemere as its logging implementation. diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html index faf2732..3aaefce 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.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.format-error-fn
clj
cljs
(format-error-fn)(format-error-fn {:as _opts})Experimental, subject to change. diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html index 2e028b6..909d6dc 100644 --- a/taoensso.telemere.utils.html +++ b/taoensso.telemere.utils.html @@ -1,11 +1,11 @@ -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.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.file-writer
clj
(file-writer {:keys [file append?], :or {append? true}})Experimental, subject to change. Opens the specified file and returns a stateful fn of 2 arities: - [content] => Writes given content to file, or no-ops if closed. + [content] => Writes given content to file, or noops if closed. [] => Closes the writer. Useful for basic handlers that write to a file, etc. @@ -90,7 +90,7 @@ Returns a (fn preamble [signal]) that: Options: `:format-inst-fn` - (fn format [instant]) => string.tcp-socket-writer
clj
(tcp-socket-writer {:keys [host port ssl? connect-timeout-msecs socket-fn ssl-socket-fn], :as opts, :or {connect-timeout-msecs 3000, socket-fn default-socket-fn, ssl-socket-fn default-ssl-socket-fn}})Experimental, subject to change. Connects to specified TCP socket and returns a stateful fn of 2 arities: - [content] => Writes given content to socket, or no-ops if closed. + [content] => Writes given content to socket, or noops if closed. [] => Closes the writer. Useful for basic handlers that write to a TCP socket, etc.