Telemere 1.0.0-beta14
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-beta14"]
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`, +Telemere 1.0.0-beta15 Telemere 1.0.0-beta15
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-beta15"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- call-on-shutdown!
- catch->error!
- chance
- check-intakes
- comp-middleware
- default-handler-dispatch-opts
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-handlers-stats
- get-min-levels
- handler:console
- handler:file
- help:environmental-config
- help:filters
- help:handler-dispatch-options
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- 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 00c5c43..b4014a2 100644 --- a/index.cljs.html +++ b/index.cljs.html @@ -1,4 +1,4 @@ -Telemere 1.0.0-beta14 Telemere 1.0.0-beta14
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-beta14"]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. +Telemere 1.0.0-beta15 \ No newline at end of file diff --git a/index.html b/index.html index 51707a6..ad17c6b 100644 --- a/index.html +++ b/index.html @@ -1,3 +1,3 @@ -Telemere 1.0.0-beta15
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-beta15"]Namespaces
taoensso.telemere
Structured telemetry for Clojure/Script applications.Public variables and functions:
- *ctx*
- *middleware*
- add-handler!
- catch->error!
- chance
- comp-middleware
- default-handler-dispatch-opts
- error!
- error-signal?
- event!
- format-signal-fn
- get-env
- get-filters
- get-handlers
- get-handlers-stats
- get-min-levels
- handler:console
- handler:console-raw
- help:environmental-config
- help:filters
- help:handler-dispatch-options
- help:handlers
- help:signal-content
- help:signal-creators
- help:signal-options
- level-aliases
- log!
- msg-skip
- msg-splice
- newline
- pr-signal-fn
- rate-limiter
- remove-handler!
- set-ctx!
- set-id-filter!
- set-kind-filter!
- set-middleware!
- set-min-level!
- set-ns-filter!
- set-var-root!
- signal!
- 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-beta14 \ No newline at end of file +Telemere 1.0.0-beta14
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-beta14"]Platforms
This project includes code for multiple platforms, please choose a platform to view its documentation:
Telemere 1.0.0-beta15 \ No newline at end of file diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html index e83d7a8..20d8058 100644 --- a/taoensso.telemere.cljs.html +++ b/taoensso.telemere.cljs.html @@ -1,31 +1,41 @@ -Telemere 1.0.0-beta15
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-beta15"]Platforms
This project includes code for multiple platforms, please choose a platform to view its documentation:
taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. +taoensso.telemere documentation taoensso.telemere
Structured telemetry for Clojure/Script applications. See the GitHub page (esp. Wiki) for info on motivation and design: - <https://www.taoensso.com/telemere>*ctx*
dynamic
clj
cljs
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals. -Value may be any type, but is usually nil or a map. + <https://www.taoensso.com/telemere>*ctx*
dynamic
clj
cljs
Optional context (state) attached to all signals. +Value may be any type, but is usually nil or a map. Default (root) value is nil. -Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`. -Modify root (base) value using `set-ctx!`. -Default root (base) value is `default-ctx`. +Useful for dynamically attaching arbitrary app-level state to signals. -Note that as with all dynamic Clojure vars, "binding conveyance" applies -when using futures, agents, etc. +Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`. +Modify root (default) value using `set-ctx!`. + +As with all dynamic Clojure vars, "binding conveyance" applies when using +futures, agents, etc. Tips: - - Value may be (or may contain) an atom if you want mutable semantics - - Value may be of form {<scope-id> <data>} for custom scoping, etc.*middleware*
dynamic
clj
cljs
Optional (fn [signal]) => ?modified-signal to apply (once) when -signal is created. When middleware returns nil, skips all handlers. + - Value may be (or may contain) an atom if you want mutable semantics. + - Value may be of form {<scope-id> <data>} for custom scoping, etc. + - Use `get-env` to set default (root) value based on environmental config.*middleware*
dynamic
clj
cljs
Optional (fn [signal]) => ?modified-signal to apply to all signals. +When middleware returns nil, skips all handlers. Default (root) value is nil. -Compose multiple middleware fns together with `comp-middleware`. +Useful for dynamically transforming signals and/or filtering signals +by signal data/content/etc. -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 +Re/bind dynamic value using `with-middleware`, `binding`. +Modify root (default) value using `set-middleware!`. + +As with all dynamic Clojure vars, "binding conveyance" applies when using +futures, agents, etc. + +Tips: + - Compose multiple middleware fns together with `comp-middleware`. + - Use `get-env` to set default (root) value based on environmental config.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 handlers now registered. -`handler-fn` should be a fn of 1 or 2 arities: +`handler-fn` should be a fn of exactly 2 arities: [signal] ; Single argument Called asynchronously or synchronously (depending on dispatch options) @@ -37,8 +47,12 @@ now registered. dashboard, examine for outliers or unexpected data, etc. [] ; 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. + Called exactly once when stopping handler to provide an opportunity + for handler to flush buffers, close files, etc. May just noop. + +NB you should always call `stop-handlers!` somewhere appropriate - usually +near the end of your `-main` or shutdown procedure, AFTER all other code has +completed that could create signals. See `help:handler-dispatch-options` for handler filters, etc.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & kvs]} form)Unconditionally executes given form and- If form succeeds: return the form's result. @@ -85,11 +99,7 @@ returned composite fn immediately returns nil: ((comp-middleware inc #(* % 2) inc) 1) => 5 ; (inc (* (inc 1) 2)) ((comp-middleware inc (fn [_] nil) (fn [_] (throw (Exception. "Never thrown!")))) 1) => nil -Useful for composing Ring-style middleware fns.default-ctx
clj
cljs
Default root (base) value of `*ctx*` var. -Defaults to `nil`, controlled by: - (get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>) - -See `get-env` 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. +Useful for composing Ring-style middleware fns.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit 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` @@ -166,8 +176,8 @@ Options: `:preamble-fn` - (fn [signal]) => signal preamble string. `:content-fn` - (fn [signal]) => signal content string. -See also `pr-signal-fn` for machine-readable output.get-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return], :or {as :str, return :value}} spec)Flexible cross-platform util for embedding a config value during -macro expansion. Used by other Taoensso libraries. +See also `pr-signal-fn` for machine-readable output.get-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return], :or {as :str, return :value}} spec)Flexible cross-platform util for embedding an environmental config value +during macro expansion. Used by other Taoensso libraries. Given a const kw/string id or vector of desc-priority alternative ids, parse and return the first of the following that exists: @@ -265,7 +275,7 @@ 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: +If `js/console` exists, returns a signal handler that: - Takes a Telemere signal (map). - Writes the signal as a string to JavaScript console. @@ -275,7 +285,7 @@ signals as human or machine-readable (edn, JSON) strings. Options: `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn`handler:console-raw
cljs
(handler:console-raw)(handler:console-raw {:keys [preamble-fn format-nsecs-fn], :as opts, :or {preamble-fn (utils/signal-preamble-fn), format-nsecs-fn (utils/format-nsecs-fn)}})Experimental, subject to change. -If `js/console` exists, returns a (fn handler [signal]) that: +If `js/console` exists, returns a signal handler that: - Takes a Telemere signal (map). - Writes the raw signal to JavaScript console. @@ -342,44 +352,41 @@ Tips: 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: - 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" + 1. Signal creation is allowed by "signal filters": + a. Compile-time: sample rate, kind, ns, id, level, when form, rate limit + b. Runtime: sample rate, kind, ns, id, level, when form, rate limit - 4. Signal middleware does not suppress the signal (return nil) - 5. Handler middleware does not suppress the signal (return nil) + 2. Signal handling is allowed by "handler filters": + a. Compile-time: not applicable + b. Runtime: sample rate, kind, ns, id, level, when fn, rate limit -So we have: + 3. Signal middleware (fn [signal]) => ?modified-signal does not return nil + 4. Handler middleware (fn [signal]) => ?modified-signal does not return nil - - Signal filters - applied at compile-time and/or runtime, - determine which signals are/not created. +Note that middleware provides a flexible way to filter signals by arbitrary +signal data/content conditions (return nil to suppress signal). - - Handler filters - applied at runtime only, determine which (created) - signals are/not handled by each registered handler. +Config: -All filters (1-3) may depend on (in order): + To set signal filters (1a, 1b): - Sample rate → namespace → kind → id → level → when form/fn → rate limit + Use: + `set-kind-filter!`, `with-kind-filter` + `set-ns-filter!`, `with-ns-filter` + `set-id-filter!`, `with-id-filter` + `set-min-level!`, `with-min-level` + or see `help:environmental-config`. -Setting signal filters (1-2): + To set handler filters (2b) or handler middleware (4): - Both compile-time and runtime signal filters can be specified via environmental - config (see `help:environmental-config` for details). + Provide relevant opts when calling `add-handler!` or `with-handler/+`. + See `help:handler-dispatch-options` for details. - Runtime signal filters can also be specified with: + Note: signal filters (1a, 1b) should generally be AT LEAST as permissive as + handler filters (2b), otherwise signals will be suppressed before reaching + handlers. - `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. + To set signal middleware (3): use `set-middleware!`, `with-middleware` Compile-time vs runtime filters: @@ -438,23 +445,16 @@ All handlers support the same dispatch options, including: `: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) + complete when stopping handler. nil => no maximum. `:priority` (default 100) Optional handler priority ∈ℤ. - Handlers will be called in descending priority order. + Handlers will be called in descending priority order (larger ints first). `: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) + 1.0 => handle every arg (same as nil rate, default) 0.0 => noop every arg 0.5 => handle random 50% of args @@ -466,7 +466,9 @@ All handlers support the same dispatch options, including: `: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 limiting. Useful for filtering based on external state/context. + + See `:middleware` for an alternative that takes a signal argument. `:rate-limit` (default nil => no rate limit) Optional rate limit spec as provided to `taoensso.encore/rate-limiter`, @@ -495,7 +497,6 @@ 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 @@ -503,12 +504,14 @@ Manage handlers with: `with-handler` - Executes form with ONLY the given handler registered `with-handler+` - Executes form with the given handler (also) registered + `stop-handlers!` - Stops registered handlers + NB you should always call `stop-handlers!` somewhere appropriate - usually + near the end of your `-main` or shutdown procedure, AFTER all other code has + completed that could create signals. + See the relevant docstrings for details. 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_ ...]}, though they can be modified by signal and/or handler middleware. @@ -518,20 +521,20 @@ Default signal keys: `:schema` ------ Int version of signal schema (current: 1) `:inst` -------- Platform instant [1] when signal was created `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy :slf4j :tools-logging <user-val> ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy :slf4j :tools-logging <app-val> ...} `:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) `:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) -`:msg` --------- Arb user-level message ?str given to signal creator -`:data` -------- Arb user-level data ?val (usu. a map) given to signal creator -`:error` ------- Arb user-level platform ?error [2] given to signal creator +`:msg` --------- Arb app-level message ?str given to signal creator +`:data` -------- Arb app-level data ?val (usu. a map) given to signal creator +`:error` ------- Arb app-level platform ?error [2] given to signal creator `:run-form` ---- Unevaluated ?form given to signal creator as `:run` `:run-val` ----- Successful return ?val of `:run` ?form `:run-nsecs` --- ?int nanosecs runtime of `:run` ?form `:end-inst` ---- Platform ?instant [1] when `:run` ?form completed -`:ctx` --------- ?val of `*ctx*` (arb user-level state) when signal was created +`:ctx` --------- ?val of `*ctx*` (arb app-level state) when signal was created `:parent` ------ ?{:keys [id uid]} of parent signal, present in nested signals when tracing `:location` ---- ?{:keys [ns file line column]} signal creator callsite `:ns` ---------- ?str namespace of signal creator callsite, same as (:ns location) @@ -541,7 +544,7 @@ Default signal keys: `:thread` ------ (Clj only) {:keys [group name id]} thread info for thread that called signal creator `:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all) -<kvs> ---------- Other arb user-level ?kvs given to signal creator. Typically NOT included +<kvs> ---------- Other arb app-level ?kvs given to signal creator. Typically NOT included in handler output, so a great way to provide custom data/opts for use (only) by custom middleware/handlers. @@ -581,15 +584,15 @@ and return values), making them more/less convenient for certain use cases: [3] See `help:signal-content` - {:keys [kind level id data ...]} [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>} +`:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <[1]>} `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <app-val> ...} `:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) `:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) -`:msg` --------- Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`) -`:data` -------- Arb user-level ?data to incl. in signal: usu. a map -`:error` ------- Arb user-level ?error to incl. in signal: platform error [2] +`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`) +`:data` -------- Arb app-level ?data to incl. in signal: usu. a map +`:error` ------- Arb app-level ?error to incl. in signal: platform error [2] `:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal `:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding @@ -606,7 +609,7 @@ and return values), making them more/less convenient for certain use cases: `:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created `:trace?` ------ Should tracing be enabled for `:run` form? -<kvs> ---------- Other arb user-level ?kvs to incl. in signal. Typically NOT included in +<kvs> ---------- Other arb app-level ?kvs to incl. in signal. Typically NOT included in handler output, so a great way to provide custom data/opts for use (only) by custom middleware/handlers. @@ -665,7 +668,7 @@ Returns a (fn pr [signal]) that: Options: `:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)} - `:incl-kvs?` - Include signal's user-level kvs? (default false) + `:incl-kvs?` - Include signal's app-level kvs? (default false) `:incl-nils?` - Include signal's keys with nil values? (default false) `:incl-newline?` - Include terminating system newline? (default true) `:incl-keys` - Subset of signal keys to retain from those otherwise @@ -706,13 +709,13 @@ Example: (defn send-message! [username msg-content] (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 + <send message>))remove-handler!
clj
cljs
(remove-handler! handler-id)Stops and deregisters signal handler with given id, and returns ?{<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. +still registered.set-ctx!
clj
cljs
(set-ctx! root-ctx-val)Set `*ctx*` var's default (root) value. See `*ctx*` for details.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 str/kw/sym to allow, 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> :disallow <spec>} with specs as above. @@ -720,16 +723,16 @@ still registered.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 str/kw/sym to allow, 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> :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. + If present, `:disallow` spec MUST NOT match.set-middleware!
clj
cljs
(set-middleware! ?root-middleware-fn)Set `*middleware*` var's default (root) 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). + - nil (=> no minimum level). - A level keyword (see `level-aliases` var for details). - An integer. @@ -751,7 +754,7 @@ Examples: `ns-filter` may be: - A namespace. - - A str/kw/sym, in which "*"s act as wildcards. + - A str/kw/sym to allow, 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> :disallow <spec>} with specs as above. @@ -824,13 +827,18 @@ Tips: [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]} [3] See `help:signal-content` - {:keys [kind level id data ...]} -[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)stop-handlers!
clj
cljs
(stop-handlers!)Stops relevant registered signal handlers in parallel, and returns -?{<handler-id> {:keys [okay error]}}. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)stop-handlers!
clj
cljs
(stop-handlers!)Stops registered signal handlers in parallel by calling each +handler-fn with no arguments. This gives each handler the opportunity +to flush buffers, close files, etc. -Future calls to stopped handlers will noop. +Each handler will immediately stop accepting new signals, nooping if called. -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. +Blocks to return ?{<handler-id> {:keys [okay error]}}, honouring each +handler's `:drain-msecs` value (see `help:handler-dispatch-options`). + +NB you should always call `stop-handlers!` somewhere appropriate - usually +near the end of your `-main` or shutdown procedure, AFTER all other code has +completed that could create signals.trace!
macro
clj
cljs
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit 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` @@ -891,11 +899,11 @@ 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 form)(with-handler handler-id handler-fn dispatch-opts form)Executes form with ONLY the given signal handler registered. -Useful for tests/debugging. +Stops handler after use. Useful for tests/debugging. 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. +Stops handler after use. Useful for tests/debugging. 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. diff --git a/taoensso.telemere.html b/taoensso.telemere.html index b985ef4..817c589 100644 --- a/taoensso.telemere.html +++ b/taoensso.telemere.html @@ -1,34 +1,41 @@ -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>*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. + <https://www.taoensso.com/telemere>*ctx*
dynamic
clj
cljs
Optional context (state) attached to all signals. +Value may be any type, but is usually nil or a map. Default (root) value is nil. -Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`. -Modify root (base) value using `set-ctx!`. -Default root (base) value is `default-ctx`. +Useful for dynamically attaching arbitrary app-level state to signals. -Note that as with all dynamic Clojure vars, "binding conveyance" applies -when using futures, agents, etc. +Re/bind dynamic value using `with-ctx`, `with-ctx+`, or `binding`. +Modify root (default) value using `set-ctx!`. + +As with all dynamic Clojure vars, "binding conveyance" applies when using +futures, agents, etc. Tips: - - Value may be (or may contain) an atom if you want mutable semantics - - Value may be of form {<scope-id> <data>} for custom scoping, etc.*middleware*
dynamic
clj
cljs
Optional (fn [signal]) => ?modified-signal to apply (once) when -signal is created. When middleware returns nil, skips all handlers. + - Value may be (or may contain) an atom if you want mutable semantics. + - Value may be of form {<scope-id> <data>} for custom scoping, etc. + - Use `get-env` to set default (root) value based on environmental config.*middleware*
dynamic
clj
cljs
Optional (fn [signal]) => ?modified-signal to apply to all signals. +When middleware returns nil, skips all handlers. Default (root) value is nil. -Compose multiple middleware fns together with `comp-middleware`. +Useful for dynamically transforming signals and/or filtering signals +by signal data/content/etc. -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 +Re/bind dynamic value using `with-middleware`, `binding`. +Modify root (default) value using `set-middleware!`. + +As with all dynamic Clojure vars, "binding conveyance" applies when using +futures, agents, etc. + +Tips: + - Compose multiple middleware fns together with `comp-middleware`. + - Use `get-env` to set default (root) value based on environmental config.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 handlers now registered. -`handler-fn` should be a fn of 1 or 2 arities: +`handler-fn` should be a fn of exactly 2 arities: [signal] ; Single argument Called asynchronously or synchronously (depending on dispatch options) @@ -40,10 +47,16 @@ now registered. dashboard, examine for outliers or unexpected data, etc. [] ; 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. + Called exactly once when stopping handler to provide an opportunity + for handler to flush buffers, close files, etc. May just noop. -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- +NB you should always call `stop-handlers!` somewhere appropriate - usually +near the end of your `-main` or shutdown procedure, AFTER all other code has +completed that could create signals. + +See `help:handler-dispatch-options` for handler filters, etc.call-on-shutdown!
clj
added in Encore v3.114.0 (2024-08-07)
(call-on-shutdown! f)Registers given nullary fn as a JVM shutdown hook. +(f) will be called sometime during shutdown. While running, it will +attempt to block shutdown.catch->error!
macro
clj
cljs
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit 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], @@ -92,11 +105,7 @@ returned composite fn immediately returns nil: ((comp-middleware inc #(* % 2) inc) 1) => 5 ; (inc (* (inc 1) 2)) ((comp-middleware inc (fn [_] nil) (fn [_] (throw (Exception. "Never thrown!")))) 1) => nil -Useful for composing Ring-style middleware fns.default-ctx
clj
cljs
Default root (base) value of `*ctx*` var. -Defaults to `nil`, controlled by: - (get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>) - -See `get-env` for details.default-handler-dispatch-opts
clj
cljs
Default handler dispatch options, see +Useful for composing Ring-style middleware fns.default-handler-dispatch-opts
clj
cljs
Default handler dispatch options, see `help:handler-dispatch-options` for details.error!
macro
clj
cljs
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit 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) @@ -174,8 +183,8 @@ Options: `:preamble-fn` - (fn [signal]) => signal preamble string. `:content-fn` - (fn [signal]) => signal content string. -See also `pr-signal-fn` for machine-readable output.get-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return], :or {as :str, return :value}} spec)Flexible cross-platform util for embedding a config value during -macro expansion. Used by other Taoensso libraries. +See also `pr-signal-fn` for machine-readable output.get-env
macro
clj
cljs
added in Encore v3.75.0 (2024-01-29)
(get-env {:keys [as default return], :or {as :str, return :value}} spec)Flexible cross-platform util for embedding an environmental config value +during macro expansion. Used by other Taoensso libraries. Given a const kw/string id or vector of desc-priority alternative ids, parse and return the first of the following that exists: @@ -273,7 +282,7 @@ 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: +Returns a signal handler that: - Takes a Telemere signal (map). - Writes the signal as a string to specified stream. @@ -285,7 +294,7 @@ Options: `:stream` - `java.io.writer` Defaults to `*err*` if `utils/error-signal?` is true, and `*out*` otherwise.handler:file
clj
(handler:file)(handler:file {:keys [output-fn path interval max-file-size max-num-parts max-num-intervals gzip-archives?], :or {output-fn (utils/format-signal-fn), path "logs/telemere.log", interval :monthly, max-file-size (* 1024 1024 4), max-num-parts 8, max-num-intervals 6, gzip-archives? true}})Experimental, subject to change. -Returns a (fn handler [signal]) that: +Returns a signal handler that: - Takes a Telemere signal (map). - Writes (appends) the signal as a string to file specified by `path`. @@ -373,44 +382,41 @@ Tips: 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: - 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" + 1. Signal creation is allowed by "signal filters": + a. Compile-time: sample rate, kind, ns, id, level, when form, rate limit + b. Runtime: sample rate, kind, ns, id, level, when form, rate limit - 4. Signal middleware does not suppress the signal (return nil) - 5. Handler middleware does not suppress the signal (return nil) + 2. Signal handling is allowed by "handler filters": + a. Compile-time: not applicable + b. Runtime: sample rate, kind, ns, id, level, when fn, rate limit -So we have: + 3. Signal middleware (fn [signal]) => ?modified-signal does not return nil + 4. Handler middleware (fn [signal]) => ?modified-signal does not return nil - - Signal filters - applied at compile-time and/or runtime, - determine which signals are/not created. +Note that middleware provides a flexible way to filter signals by arbitrary +signal data/content conditions (return nil to suppress signal). - - Handler filters - applied at runtime only, determine which (created) - signals are/not handled by each registered handler. +Config: -All filters (1-3) may depend on (in order): + To set signal filters (1a, 1b): - Sample rate → namespace → kind → id → level → when form/fn → rate limit + Use: + `set-kind-filter!`, `with-kind-filter` + `set-ns-filter!`, `with-ns-filter` + `set-id-filter!`, `with-id-filter` + `set-min-level!`, `with-min-level` + or see `help:environmental-config`. -Setting signal filters (1-2): + To set handler filters (2b) or handler middleware (4): - Both compile-time and runtime signal filters can be specified via environmental - config (see `help:environmental-config` for details). + Provide relevant opts when calling `add-handler!` or `with-handler/+`. + See `help:handler-dispatch-options` for details. - Runtime signal filters can also be specified with: + Note: signal filters (1a, 1b) should generally be AT LEAST as permissive as + handler filters (2b), otherwise signals will be suppressed before reaching + handlers. - `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. + To set signal middleware (3): use `set-middleware!`, `with-middleware` Compile-time vs runtime filters: @@ -469,23 +475,16 @@ All handlers support the same dispatch options, including: `: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) + complete when stopping handler. nil => no maximum. `:priority` (default 100) Optional handler priority ∈ℤ. - Handlers will be called in descending priority order. + Handlers will be called in descending priority order (larger ints first). `: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) + 1.0 => handle every arg (same as nil rate, default) 0.0 => noop every arg 0.5 => handle random 50% of args @@ -497,7 +496,9 @@ All handlers support the same dispatch options, including: `: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 limiting. Useful for filtering based on external state/context. + + See `:middleware` for an alternative that takes a signal argument. `:rate-limit` (default nil => no rate limit) Optional rate limit spec as provided to `taoensso.encore/rate-limiter`, @@ -526,7 +527,6 @@ 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 @@ -534,12 +534,14 @@ Manage handlers with: `with-handler` - Executes form with ONLY the given handler registered `with-handler+` - Executes form with the given handler (also) registered + `stop-handlers!` - Stops registered handlers + NB you should always call `stop-handlers!` somewhere appropriate - usually + near the end of your `-main` or shutdown procedure, AFTER all other code has + completed that could create signals. + See the relevant docstrings for details. 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_ ...]}, though they can be modified by signal and/or handler middleware. @@ -549,20 +551,20 @@ Default signal keys: `:schema` ------ Int version of signal schema (current: 1) `:inst` -------- Platform instant [1] when signal was created `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy :slf4j :tools-logging <user-val> ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy :slf4j :tools-logging <app-val> ...} `:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) `:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) -`:msg` --------- Arb user-level message ?str given to signal creator -`:data` -------- Arb user-level data ?val (usu. a map) given to signal creator -`:error` ------- Arb user-level platform ?error [2] given to signal creator +`:msg` --------- Arb app-level message ?str given to signal creator +`:data` -------- Arb app-level data ?val (usu. a map) given to signal creator +`:error` ------- Arb app-level platform ?error [2] given to signal creator `:run-form` ---- Unevaluated ?form given to signal creator as `:run` `:run-val` ----- Successful return ?val of `:run` ?form `:run-nsecs` --- ?int nanosecs runtime of `:run` ?form `:end-inst` ---- Platform ?instant [1] when `:run` ?form completed -`:ctx` --------- ?val of `*ctx*` (arb user-level state) when signal was created +`:ctx` --------- ?val of `*ctx*` (arb app-level state) when signal was created `:parent` ------ ?{:keys [id uid]} of parent signal, present in nested signals when tracing `:location` ---- ?{:keys [ns file line column]} signal creator callsite `:ns` ---------- ?str namespace of signal creator callsite, same as (:ns location) @@ -572,7 +574,7 @@ Default signal keys: `:thread` ------ (Clj only) {:keys [group name id]} thread info for thread that called signal creator `:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all) -<kvs> ---------- Other arb user-level ?kvs given to signal creator. Typically NOT included +<kvs> ---------- Other arb app-level ?kvs given to signal creator. Typically NOT included in handler output, so a great way to provide custom data/opts for use (only) by custom middleware/handlers. @@ -612,15 +614,15 @@ and return values), making them more/less convenient for certain use cases: [3] See `help:signal-content` - {:keys [kind level id data ...]} [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>} +`:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <[1]>} `:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...} -`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...} +`:kind` -------- Signal ?kind ∈ #{nil :event :error :log :trace :spy <app-val> ...} `:id` ---------- ?id of signal (common to all signals created at callsite, contrast with `:uid`) `:uid` --------- ?id of signal instance (unique to each signal created at callsite, contrast with `:id`) -`:msg` --------- Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`) -`:data` -------- Arb user-level ?data to incl. in signal: usu. a map -`:error` ------- Arb user-level ?error to incl. in signal: platform error [2] +`:msg` --------- Arb app-level ?message to incl. in signal: str or vec of strs to join (with `\space`) +`:data` -------- Arb app-level ?data to incl. in signal: usu. a map +`:error` ------- Arb app-level ?error to incl. in signal: platform error [2] `:run` --------- ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal `:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding @@ -637,7 +639,7 @@ and return values), making them more/less convenient for certain use cases: `:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created `:trace?` ------ Should tracing be enabled for `:run` form? -<kvs> ---------- Other arb user-level ?kvs to incl. in signal. Typically NOT included in +<kvs> ---------- Other arb app-level ?kvs to incl. in signal. Typically NOT included in handler output, so a great way to provide custom data/opts for use (only) by custom middleware/handlers. @@ -704,7 +706,7 @@ Returns a (fn pr [signal]) that: Options: `:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)} - `:incl-kvs?` - Include signal's user-level kvs? (default false) + `:incl-kvs?` - Include signal's app-level kvs? (default false) `:incl-nils?` - Include signal's keys with nil values? (default false) `:incl-newline?` - Include terminating system newline? (default true) `:incl-keys` - Subset of signal keys to retain from those otherwise @@ -745,13 +747,13 @@ Example: (defn send-message! [username msg-content] (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 + <send message>))remove-handler!
clj
cljs
(remove-handler! handler-id)Stops and deregisters signal handler with given id, and returns ?{<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. +still registered.set-ctx!
clj
cljs
(set-ctx! root-ctx-val)Set `*ctx*` var's default (root) value. See `*ctx*` for details.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 str/kw/sym to allow, 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> :disallow <spec>} with specs as above. @@ -759,16 +761,16 @@ still registered.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 str/kw/sym to allow, 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> :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. + If present, `:disallow` spec MUST NOT match.set-middleware!
clj
cljs
(set-middleware! ?root-middleware-fn)Set `*middleware*` var's default (root) 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). + - nil (=> no minimum level). - A level keyword (see `level-aliases` var for details). - An integer. @@ -790,7 +792,7 @@ Examples: `ns-filter` may be: - A namespace. - - A str/kw/sym, in which "*"s act as wildcards. + - A str/kw/sym to allow, 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> :disallow <spec>} with specs as above. @@ -863,13 +865,18 @@ Tips: [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]} [3] See `help:signal-content` - {:keys [kind level id data ...]} -[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)stop-handlers!
clj
cljs
(stop-handlers!)Stops relevant registered signal handlers in parallel, and returns -?{<handler-id> {:keys [okay error]}}. +[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)stop-handlers!
clj
cljs
(stop-handlers!)Stops registered signal handlers in parallel by calling each +handler-fn with no arguments. This gives each handler the opportunity +to flush buffers, close files, etc. -Future calls to stopped handlers will noop. +Each handler will immediately stop accepting new signals, nooping if called. -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. +Blocks to return ?{<handler-id> {:keys [okay error]}}, honouring each +handler's `:drain-msecs` value (see `help:handler-dispatch-options`). + +NB you should always call `stop-handlers!` somewhere appropriate - usually +near the end of your `-main` or shutdown procedure, AFTER all other code has +completed that could create signals.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. @@ -946,11 +953,11 @@ 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 form)(with-handler handler-id handler-fn dispatch-opts form)Executes form with ONLY the given signal handler registered. -Useful for tests/debugging. +Stops handler after use. Useful for tests/debugging. 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. +Stops handler after use. Useful for tests/debugging. 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. diff --git a/taoensso.telemere.open-telemetry.html b/taoensso.telemere.open-telemetry.html index 1ec1766..e855246 100644 --- a/taoensso.telemere.open-telemetry.html +++ b/taoensso.telemere.open-telemetry.html @@ -1,6 +1,6 @@ -taoensso.telemere.open-telemetry documentation taoensso.telemere.open-telemetry
OpenTelemetry handler using `opentelemetry-java`, +taoensso.telemere.open-telemetry documentation 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: @@ -12,7 +12,7 @@ See the relevant `opentelemetry-java` docs for details.https://github.com/open-telemetry/opentelemetry-java>. -Returns a (fn handler [signal]) that: +Returns a signal handler that: - Takes a Telemere signal (map). - Emits the signal to `io.opentelemetry.api.logs.Logger` returned by given `io.opentelemetry.api.logs.LoggerProvider`. diff --git a/taoensso.telemere.postal.html b/taoensso.telemere.postal.html index 680fbd1..af3d9f4 100644 --- a/taoensso.telemere.postal.html +++ b/taoensso.telemere.postal.html @@ -1,11 +1,11 @@ -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>. -Returns a (fn handler [signal]) that: +Returns a signal handler that: - Takes a Telemere signal (map). - Sends the signal as an email to specified recipient. diff --git a/taoensso.telemere.slack.html b/taoensso.telemere.slack.html index 6a33e9f..a141811 100644 --- a/taoensso.telemere.slack.html +++ b/taoensso.telemere.slack.html @@ -1,11 +1,11 @@ -taoensso.telemere.slack documentation taoensso.telemere.slack
Slack handler using `clj-slack`, +taoensso.telemere.slack documentation \ No newline at end of file diff --git a/taoensso.telemere.sockets.html b/taoensso.telemere.sockets.html index eabc2a8..daee917 100644 --- a/taoensso.telemere.sockets.html +++ b/taoensso.telemere.sockets.html @@ -1,43 +1,43 @@ -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>. -Returns a (fn handler [signal]) that: +Returns a signal handler that: - Takes a Telemere signal (map). - Writes the signal as a string to specified Slack channel. @@ -21,6 +21,7 @@ Default handler dispatch options (override when calling `add-handler!`): ] Options: + `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` `:conn-opts` - Map of connection opts given to `clj-slack.chat/post-message` Examples: {:token "MY-TOKEN"} @@ -30,7 +31,5 @@ Options: Examples: {:channel-id "C12345678", :username "MY_BOT"} - `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` - Tips: - See `clj-slack` docs for more info on its options.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: +Returns a signal handler that: - Takes a Telemere signal (map). - Sends the signal as a string to specified TCP socket. Can output signals as human or machine-readable (edn, JSON) strings. Options: + `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` `:socket-opts` - {:keys [host port ssl? connect-timeout-msecs]} `:host` - Destination TCP socket hostname string `:port` - Destination TCP socket port int `:ssl?` - Use SSL/TLS (default false) `:connect-timeout-msecs` - Connection timeout (default 3000 msecs) - `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` - Limitations: - Failed writes will be retried only once. - Writes lock on a single underlying socket, so IO won't benefit from adding extra handler threads. Let me know if there's demand for socket pooling.handler:udp-socket
clj
(handler:udp-socket {:keys [socket-opts output-fn truncation-warning-fn], :or {socket-opts {:max-packet-bytes 512}, output-fn (utils/format-signal-fn)}})Experimental, subject to change. Feedback welcome! -Returns a (fn handler [signal]) that: +Returns a signal handler that: - Takes a Telemere signal (map). - Sends the signal as a string to specified UDP socket. Can output signals as human or machine-readable (edn, JSON) strings. Options: + `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` `:socket-opts` - {:keys [host port max-packet-bytes]} `:host` - Destination UDP socket hostname string `:port` - Destination UDP socket port int `:max-packet-bytes` - Max packet size (in bytes) before truncating output (default 512) - `:output-fn` - (fn [signal]) => string, see `format-signal-fn` or `pr-signal-fn` - `:truncation-warning-fn` - Optional (fn [{:keys [max actual signal]}]) to call whenever - output is truncated. Should be appropriately rate-limited! + `:truncation-warning-fn` + Optional (fn [{:keys [max actual signal]}]) to call whenever output is truncated. + Should be appropriately rate-limited! Limitations: - Due to UDP limitations, truncates output to `max-packet-bytes`! diff --git a/taoensso.telemere.streams.html b/taoensso.telemere.streams.html index 8a562b8..b62d86a 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 741a384..e0ae01f 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 f6cc0ce..5fc5d8c 100644 --- a/taoensso.telemere.timbre.html +++ b/taoensso.telemere.timbre.html @@ -1,6 +1,6 @@ -taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. +taoensso.telemere.timbre documentation taoensso.telemere.timbre
Main Timbre macros, reimplemented on top of Telemere. Intended to help ease migration from Timbre to Telemere.debug
macro
clj
(debug & args)Prefer `telemere/log!`, etc.debugf
macro
clj
(debugf & args)Prefer `telemere/log!`, etc.error
macro
clj
(error & args)Prefer `telemere/log!`, etc. diff --git a/taoensso.telemere.tools-logging.html b/taoensso.telemere.tools-logging.html index 4aa8ec5..a0f0fa2 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 `tools.logging` -> Telemere. +taoensso.telemere.tools-logging documentation taoensso.telemere.tools-logging
Intake support for `tools.logging` -> Telemere. Telemere will attempt to load this ns automatically when possible. Naming conventions: diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html index 24e2de1..8f23505 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. @@ -48,7 +48,7 @@ Returns a (fn pr [signal]) that: Options: `:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)} - `:incl-kvs?` - Include signal's user-level kvs? (default false) + `:incl-kvs?` - Include signal's app-level kvs? (default false) `:incl-nils?` - Include signal's keys with nil values? (default false) `:incl-newline?` - Include terminating system newline? (default true) `:incl-keys` - Subset of signal keys to retain from those otherwise diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html index 5c056de..d89910b 100644 --- a/taoensso.telemere.utils.html +++ b/taoensso.telemere.utils.html @@ -1,6 +1,6 @@ -taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc. +taoensso.telemere.utils documentation taoensso.telemere.utils
Misc utils useful for Telemere handlers, middleware, etc.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. @@ -55,7 +55,7 @@ Returns a (fn pr [signal]) that: Options: `:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)} - `:incl-kvs?` - Include signal's user-level kvs? (default false) + `:incl-kvs?` - Include signal's app-level kvs? (default false) `:incl-nils?` - Include signal's keys with nil values? (default false) `:incl-newline?` - Include terminating system newline? (default true) `:incl-keys` - Subset of signal keys to retain from those otherwise