\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index 6ecf606..466671f 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,4 +1,4 @@
-Telemere 1.0.0-beta22
\ No newline at end of file
diff --git a/index.html b/index.html
index 8f54dac..0b6730b 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-beta22
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index 39178ae..d737f58 100644
--- a/taoensso.telemere.cljs.html
+++ b/taoensso.telemere.cljs.html
@@ -1,6 +1,6 @@
-taoensso.telemere documentation
Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
<https://www.taoensso.com/telemere>
Optional context (state) attached to all signals.
@@ -44,29 +44,28 @@ Examples:
Tips:
- Compose multiple middleware fns together with `comp-middleware`.
- Use `get-env` to set default (root) value based on environmental config.
Experimental, subject to change.
-(fn [root?]) used to generate signal `:uid` values when tracing.
-These are basically unique signal instance identifiers.
+(fn [root?]) used to generate signal `:uid` values (unique instance ids)
+when tracing.
Relevant only when `otel-tracing?` is false.
If `otel-tracing?` is true, uids are instead generated by `*otel-tracer*`.
-`root?` argument is true iff signal is a top-level trace (i.e. form
-being traced is unnested = has no parent form).
+`root?` argument is true iff signal is a top-level trace (i.e. form being
+traced is unnested = has no parent form). Root-level uids typically need
+more entropy and so are usually longer (e.g. 32 vs 16 hex chars).
-Root uids typically have ~128 bits of entropy to ensure uniqueness.
-Child uids are typically used only with respect to a parent/root,
-and so can often make do with ~64 bits of entropy or less.
+Override default by setting one of the following:
+ JVM property: `taoensso.telemere/uid-fn`
+ Env variable: `TAOENSSO_TELEMERE_UID_FN`
+ Classpath resource: `taoensso.telemere/uid-fn`
-Smaller uids are generally cheaper to generate, and use less space
-when serializing/transmitting/storing/etc.
-
-By default generates nano-style uids like
- "r76-B8LoIPs5lBG1_Uhdy" (root) and "tMEYoZH0K-" (non-root).
-
-For plain fixed-length UUIDs use: (fn [_root?] (utils/uuid))
-For plain fixed-length UUID strings use: (fn [_root?] (utils/uuid-str))
-
-See also `utils/nano-uid-fn`, `utils/hex-id-fn`, etc.
Registers given signal handler and returns
{<handler-id> {:keys [dispatch-opts handler-fn]}} for all handlers
now registered. If an old handler already existed under the same id, stop it.
@@ -89,7 +88,7 @@ NB you should always call `stop-handlers!` somewhere appropriate - usually
near the end of your `-main` or shutdown procedure, AFTER all other code has
completed that could create signals.
-See `help:handler-dispatch-options` for handler filters, etc.
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} form)
Unconditionally executes given form and-
If form succeeds: return the form's result.
If form throws:
Call `error!` with the thrown error and the given signal options [2],
@@ -118,7 +117,8 @@ Tips:
- Test using `with-signal`: (with-signal (catch->error! ...)).
- Supports the same options [2] as other signals [1].
- - Useful for recording errors in forms, futures, callbacks, etc.
+ - Useful for preventing errors from going unnoticed in futures, callbacks,
+ agent actions, etc.!: (future (catch->error ::my-future (do-something)))
See also `error!`.
@@ -127,14 +127,29 @@ See also `error!`.
[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.)
Experimental, subject to change.
+Returns a (fn clean [signal]) that:
+ - Takes a Telemere signal (map).
+ - Returns a minimal signal (map) ready for printing, etc.
+
+Signals are optimized for cheap creation and easy handling, so tend to be
+verbose and may contain things like nil values and duplicated content.
+
+This util efficiently cleans signals of such noise, helping reduce
+storage/transmission size, and making key info easier to see.
+
+Options:
+ `:incl-nils?` - Include signal's keys with nil values? (default false)
+ `:incl-kvs?` - Include signal's app-level root kvs? (default false)
+ `:incl-keys` - Subset of signal keys to retain from those otherwise
+ excluded by default: #{:location :kvs :file :host :thread}
(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 root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
+that indicates that it's an error.
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
API: [id] [id level-or-opts] => true iff signal was allowed
Default kind: `:event`
@@ -208,47 +223,47 @@ Returns a (fn format [signal]) that:
Options:
`:incl-newline?` - Include terminating system newline? (default true)
- `:preamble-fn` - (fn [signal]) => signal preamble string, see [1].
- `:content-fn` - (fn [signal]) => signal content string, see [2].
+ `:preamble-fn` - (fn [signal]) => signal preamble string, see [1]
+ `:content-fn` - (fn [signal]) => signal content string, see [2]
[1] `taoensso.telemere.utils/signal-preamble-fn`, etc.
[2] `taoensso.telemere.utils/signal-content-fn`, etc.
See also `pr-signal-fn` for an alternative to `format-signal-fn`
-that produces machine-readable output (edn, JSON, etc.).
Flexible cross-platform util for embedding an environmental config value
-during macro expansion. Used by other Taoensso libraries.
+that produces machine-readable output (edn, JSON, etc.).
Flexible cross-platform util to return an environmental config value.
-Given a const kw/string id or vector of desc-priority alternative ids,
-parse and return the first of the following that exists:
+Given an id (const keyword/string) or vector of desc-priority alternative
+ids, parse and return the first of the following that exists:
- JVM property value for id
- Environment variable value for id
- Classpath resource content for id
Ids may include optional segment in `<>` tag (e.g. `<.edn>`).
-Ids may include `<.?platform.?>` tag for auto replacement, useful
-for supporting platform-specific config.
+Ids may include `<.?platform.?>` tag for auto replacement:
+ `<.platform>` => ".clj" / ".cljs"
+ `<platform->` => "clj-" / "cljs-", etc.
Search order: desc by combined [alt-index platform(y/n) optional(y/n)].
So (get-env {:as :edn} [:my-app/alt1<.platform><.edn> :my-app/alt2])
will parse and return the first of the following that exists:
- 1. Alt1 +platform +optional (.edn suffix)
+ 1. Alt1 +platform +optional (optional .edn suffix)
1a. `my-app.alt1.clj.edn` JVM property value
1b. `MY_APP_ALT1_CLJ_EDN` environment variable value
1c. `my-app.alt1.clj.edn` classpath resource content
- 2. Alt1 +platform -optional (.edn suffix)
+ 2. Alt1 +platform -optional (optional .edn suffix)
2a. `my-app.alt1.clj` JVM property value
2b. `MY_APP_ALT1_CLJ` environment variable value
2c. `my-app.alt1.clj` classpath resource content
- 3. Alt1 -platform +optional (.edn suffix)
+ 3. Alt1 -platform +optional (optional .edn suffix)
3a. `my-app.alt1.edn` JVM property value
3b. `MY_APP_ALT1_EDN` environment variable value
3c. `my-app.alt1.edn` classpath resource content
- 4. Alt1 -platform -optional (.edn suffix)
+ 4. Alt1 -platform -optional (optional .edn suffix)
4a. `my-app.alt1` JVM property value
4b. `MY_APP_ALT1` environment variable value
4c. `my-app.alt1` classpath resource content
@@ -263,11 +278,15 @@ Options:
`:default` - Fallback to return unparsed if no value found during search (default `nil`).
`:return` - Return type ∈ #{:value :map :explain} (default `:value`).
-Resulting config value must be something that can be safely embedded in code during
-macro-expansion. Symbols in edn will be evaluated during expansion.
+For Cljs: resulting config value must be something that can be safely
+ embedded in code during macro 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.
Returns current ?{:keys [compile-time runtime]} filter config.
+Advanced: if resulting config value is a single top-level symbol, it will
+ be evaluated during macro 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.
Alpha, subject to change.
Returns ?{<handler-id> {:keys [handling-nsecs counts]}} for all registered
@@ -341,31 +360,31 @@ environment variables, or classpath resources.
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`
+ JVM property: `taoensso.telemere.rt-kind-filter`
+ Env variable: `TAOENSSO_TELEMERE_RT_KIND_FILTER`
+ Classpath resource: `taoensso.telemere.rt-kind-filter`
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`
+ JVM property: `taoensso.telemere.rt-ns-filter`
+ Env variable: `TAOENSSO_TELEMERE_RT_NS_FILTER`
+ Classpath resource: `taoensso.telemere.rt-ns-filter`
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`
+ JVM property: `taoensso.telemere.rt-id-filter`
+ Env variable: `TAOENSSO_TELEMERE_RT_ID_FILTER`
+ Classpath resource: `taoensso.telemere.rt-id-filter`
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`
+ JVM property: `taoensso.telemere.rt-min-level`
+ Env variable: `TAOENSSO_TELEMERE_RT_MIN_LEVEL`
+ Classpath resource: `taoensso.telemere.rt-min-level`
-Examples:
+Values are edn, examples:
- `taoensso.telemere.rt-min-level.edn` -> ":info"
- `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"
+ `taoensso.telemere.rt-min-level` -> ":info"
+ `TAOENSSO_TELEMERE_RT_NS_FILTER` -> "{:disallow \"taoensso.*\"}"
+ `taoensso.telemere.rt-id-filter.cljs` -> "#{:my-id1 :my-id2}"
+ `TAOENSSO_TELEMERE_RT_KIND_FILTER_CLJ` -> "nil"
For other (non-filter) environmental config, see the relevant docstrings.
@@ -379,12 +398,11 @@ Tips:
".clj.edn" / "_CLJ_EDN" or
".cljs.edn" / "_CLJS_EDN" suffixes instead.
- - ".edn" / "_EDN" suffixes are optional.
+ - Optional ".edn" / "_EDN" suffixes may be added for clarity.
- - 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`.
+ - To get the right edn 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.
@@ -492,6 +510,10 @@ All handlers support the same dispatch options, including:
Optional handler priority ∈ℤ.
Handlers will be called in descending priority order (larger ints first).
+ `:track-stats?` (default true)
+ Should handler track statistics (e.g. handling times) for
+ reporting by `get-handlers-stats`?
+
`: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:
@@ -635,6 +657,7 @@ and return values), making them more/less convenient for certain use cases:
`: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`)
+ Defaults to `:auto` for tracing signals, and nil otherwise
`: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
@@ -653,6 +676,7 @@ and return values), making them more/less convenient for certain use cases:
`:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all)
`:when` -------- Arb ?form; when present, form must return truthy to allow signal
`:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details
+`:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!)
`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created
`:trace?` ------ Should tracing be enabled for `:run` form?
@@ -663,7 +687,7 @@ and return values), making them more/less convenient for certain use cases:
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
[1] `java.time.Instant` or `js/Date`
-[2] `java.lang.Throwable` or `js/Error`
Experimental, subject to change.
Returns a (fn pr [signal]) that:
- Takes a Telemere signal (map).
- Returns a machine-readable signal string.
Options:
`:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)}
- `: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
- excluded by default: #{:location :kvs :file :host :thread}
+ `:clean-fn` - (fn [signal]) => clean signal map, see [1]
+ `:incl-newline?` - Include terminating system newline? (default true)
Examples:
@@ -732,41 +753,25 @@ Examples:
#?(:cljs :json ; Use js/JSON.stringify
:clj jsonista/write-value-as-string)})
-Motivation:
- Why use this util instead of just directly using the print function
- given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
- so may contain things like nil values and duplicated content.
-
- This util efficiently clean signals of such noise, helping reduce
- storage/transmission size, and making key info easier to see.
+[1] `taoensso.telemere.utils/clean-signal-fn`, etc.
See also `format-signal-fn` for an alternative to `pr-signal-fn`
that produces human-readable output.
Takes a spec of form
- [ [<n-max-reqs> <msecs-window>] ...] or
- {<limit-id> [<n-max-reqs> <msecs-window>]},
-and returns a basic stateful (fn a-rate-limiter [req-id] [command req-id]).
+ [ [<n-max-reqs> <msecs-window>] ...] or ; Unnamed limits
+ {<limit-id> [<n-max-reqs> <msecs-window>]} ; Named limits
+and returns stateful (fn a-rate-limiter [] [req-id] [command req-id]).
-Call the limiter fn with a request id (e.g. username) by which to count/limit.
-Will return:
- - nil when allowed (all limits pass for given req-id), or
- - [<worst-limit-id> <worst-backoff-msecs> {<limit-id> <backoff-msecs>}]
- when denied (any limits fail for given req-id).
+Call the returned limiter fn with a request id (any Clojure value!) to
+enforce limits independently for each id.
-Or call the limiter fn with an additional command argument:
- `:rl/peek` <req-id> - Check limits w/o incrementing count.
- `:rl/reset` <req-id> - Reset all limits for given req-id.
+For example, (limiter-fn <ip-address-string>) will return:
+ - Falsey when allowed (all limits pass for given IP), or
+ - Truthy when disallowed (any limits fail for given IP):
+ [<worst-limit-id> <worst-backoff-msecs> {<limit-id> <backoff-msecs>}]
-Example:
-
- (defonce my-rate-limiter
- (rate-limiter
- {"1 per sec" [1 1000]
- "10 per min" [10 60000]}))
-
- (defn send-message! [username msg-content]
- (if-let [fail (my-rate-limiter username)]
- (throw (ex-info "Sorry, rate limited!" {:fail fail}))
- <send message>))
Stops and deregisters signal handler with given id, and returns
+Or call the returned limiter fn with an extra command argument:
+ (limiter-fn :rl/peek <req-id) - Check limits WITHOUT incrementing count
+ (limiter-fn :rl/reset <req-id) - Reset all limits for given req-id
Sets signal id filter based on given `id-filter` spec.
@@ -826,7 +831,7 @@ Examples:
- A map, {:allow <spec> :disallow <spec>} with specs as above:
If present, `:allow` spec MUST match, AND
If present, `:disallow` spec MUST NOT match.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent root trace? do let data msg error run & kvs]})
Low-level generic signal creator.
+the new value. Cross-platform. See also `update-var-root!`.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]})
Low-level generic signal creator.
API: [opts] => depends on options [2]
Default kind: none (optional)
@@ -853,7 +858,17 @@ 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.)
(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 root 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.)
(signal-allowed? {:as opts, :keys [elidable? location sample-rate kind ns id level when rate-limit rate-limit-by]})
Returns true iff signal with given opts would meet filtering conditions:
+ (when (signal-allowed? {:level :warn, <...>}) (my-custom-code))
+
+Allows you to use Telemere's rich filtering system for conditionally
+executing arbitrary code. Also handy for batching multiple signals
+under a single set of conditions (incl. rate-limiting, sampling, etc.):
+
+ ;; Logs exactly 2 or 0 messages (never 1):
+ (when (signal-allowed? {:level :info, :sample-rate 0.5})
+ (log! {:allow? true} "Message 1")
+ (log! {:allow? true} "Message 2"))
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)
"Spy" signal creator, emphasizing form + level.
API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:spy`
@@ -863,6 +878,9 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
+`form` is generally expected to be synchronous and eager (not a lazy seq,
+async call, or IOT code like a core.async `go` block, etc.).
+
Examples:
(spy! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
@@ -904,7 +922,7 @@ handler's `:drain-msecs` value (see `help:handler-dispatch-options`).
NB you should always call `stop-handlers!` somewhere appropriate - usually
near the end of your `-main` or shutdown procedure, AFTER all other code has
-completed that could create signals.
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent root trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
+completed that could create signals.
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:trace`
@@ -914,6 +932,9 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
+`form` is generally expected to be synchronous and eager (not a lazy seq,
+async call, or IOT code like a core.async `go` block, etc.).
+
Examples:
(trace! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
@@ -948,7 +969,7 @@ 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.)
Updates root binding (value) of the var identified by given symbol, and returns
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index 9c2e8aa..4a30170 100644
--- a/taoensso.telemere.html
+++ b/taoensso.telemere.html
@@ -1,6 +1,6 @@
-taoensso.telemere documentation
Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
<https://www.taoensso.com/telemere>
Optional context (state) attached to all signals.
@@ -44,31 +44,30 @@ Examples:
Tips:
- Compose multiple middleware fns together with `comp-middleware`.
- Use `get-env` to set default (root) value based on environmental config.
Experimental, subject to change.
-(fn [root?]) used to generate signal `:uid` values when tracing.
-These are basically unique signal instance identifiers.
+(fn [root?]) used to generate signal `:uid` values (unique instance ids)
+when tracing.
Relevant only when `otel-tracing?` is false.
If `otel-tracing?` is true, uids are instead generated by `*otel-tracer*`.
-`root?` argument is true iff signal is a top-level trace (i.e. form
-being traced is unnested = has no parent form).
+`root?` argument is true iff signal is a top-level trace (i.e. form being
+traced is unnested = has no parent form). Root-level uids typically need
+more entropy and so are usually longer (e.g. 32 vs 16 hex chars).
-Root uids typically have ~128 bits of entropy to ensure uniqueness.
-Child uids are typically used only with respect to a parent/root,
-and so can often make do with ~64 bits of entropy or less.
+Override default by setting one of the following:
+ JVM property: `taoensso.telemere/uid-fn`
+ Env variable: `TAOENSSO_TELEMERE_UID_FN`
+ Classpath resource: `taoensso.telemere/uid-fn`
-Smaller uids are generally cheaper to generate, and use less space
-when serializing/transmitting/storing/etc.
-
-By default generates nano-style uids like
- "r76-B8LoIPs5lBG1_Uhdy" (root) and "tMEYoZH0K-" (non-root).
-
-For plain fixed-length UUIDs use: (fn [_root?] (utils/uuid))
-For plain fixed-length UUID strings use: (fn [_root?] (utils/uuid-str))
-
-See also `utils/nano-uid-fn`, `utils/hex-id-fn`, etc.
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} form)
Unconditionally executes given form and-
If form succeeds: return the form's result.
If form throws:
Call `error!` with the thrown error and the given signal options [2],
@@ -97,7 +96,8 @@ Tips:
- Test using `with-signal`: (with-signal (catch->error! ...)).
- Supports the same options [2] as other signals [1].
- - Useful for recording errors in forms, futures, callbacks, etc.
+ - Useful for preventing errors from going unnoticed in futures, callbacks,
+ agent actions, etc.!: (future (catch->error ::my-future (do-something)))
See also `error!`.
@@ -115,7 +115,22 @@ for tests/debugging, e.g.:
:slf4j {:present? true
:sending->telemere? true
:telemere-receiving? true}
- ...}
Experimental, subject to change.
+Returns a (fn clean [signal]) that:
+ - Takes a Telemere signal (map).
+ - Returns a minimal signal (map) ready for printing, etc.
+
+Signals are optimized for cheap creation and easy handling, so tend to be
+verbose and may contain things like nil values and duplicated content.
+
+This util efficiently cleans signals of such noise, helping reduce
+storage/transmission size, and making key info easier to see.
+
+Options:
+ `:incl-nils?` - Include signal's keys with nil values? (default false)
+ `:incl-kvs?` - Include signal's app-level root kvs? (default false)
+ `:incl-keys` - Subset of signal keys to retain from those otherwise
+ excluded by default: #{:location :kvs :file :host :thread}
(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:
@@ -123,7 +138,7 @@ returned composite fn immediately returns nil:
((comp-middleware inc (fn [_] nil) (fn [_] (throw (Exception. "Never thrown!")))) 1) => nil
Useful for composing Ring-style middleware fns.
(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 root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
+that indicates that it's an error.
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]})
"Event" signal creator, emphasizing id + level.
API: [id] [id level-or-opts] => true iff signal was allowed
Default kind: `:event`
@@ -197,47 +212,47 @@ Returns a (fn format [signal]) that:
Options:
`:incl-newline?` - Include terminating system newline? (default true)
- `:preamble-fn` - (fn [signal]) => signal preamble string, see [1].
- `:content-fn` - (fn [signal]) => signal content string, see [2].
+ `:preamble-fn` - (fn [signal]) => signal preamble string, see [1]
+ `:content-fn` - (fn [signal]) => signal content string, see [2]
[1] `taoensso.telemere.utils/signal-preamble-fn`, etc.
[2] `taoensso.telemere.utils/signal-content-fn`, etc.
See also `pr-signal-fn` for an alternative to `format-signal-fn`
-that produces machine-readable output (edn, JSON, etc.).
Flexible cross-platform util for embedding an environmental config value
-during macro expansion. Used by other Taoensso libraries.
+that produces machine-readable output (edn, JSON, etc.).
Flexible cross-platform util to return an environmental config value.
-Given a const kw/string id or vector of desc-priority alternative ids,
-parse and return the first of the following that exists:
+Given an id (const keyword/string) or vector of desc-priority alternative
+ids, parse and return the first of the following that exists:
- JVM property value for id
- Environment variable value for id
- Classpath resource content for id
Ids may include optional segment in `<>` tag (e.g. `<.edn>`).
-Ids may include `<.?platform.?>` tag for auto replacement, useful
-for supporting platform-specific config.
+Ids may include `<.?platform.?>` tag for auto replacement:
+ `<.platform>` => ".clj" / ".cljs"
+ `<platform->` => "clj-" / "cljs-", etc.
Search order: desc by combined [alt-index platform(y/n) optional(y/n)].
So (get-env {:as :edn} [:my-app/alt1<.platform><.edn> :my-app/alt2])
will parse and return the first of the following that exists:
- 1. Alt1 +platform +optional (.edn suffix)
+ 1. Alt1 +platform +optional (optional .edn suffix)
1a. `my-app.alt1.clj.edn` JVM property value
1b. `MY_APP_ALT1_CLJ_EDN` environment variable value
1c. `my-app.alt1.clj.edn` classpath resource content
- 2. Alt1 +platform -optional (.edn suffix)
+ 2. Alt1 +platform -optional (optional .edn suffix)
2a. `my-app.alt1.clj` JVM property value
2b. `MY_APP_ALT1_CLJ` environment variable value
2c. `my-app.alt1.clj` classpath resource content
- 3. Alt1 -platform +optional (.edn suffix)
+ 3. Alt1 -platform +optional (optional .edn suffix)
3a. `my-app.alt1.edn` JVM property value
3b. `MY_APP_ALT1_EDN` environment variable value
3c. `my-app.alt1.edn` classpath resource content
- 4. Alt1 -platform -optional (.edn suffix)
+ 4. Alt1 -platform -optional (optional .edn suffix)
4a. `my-app.alt1` JVM property value
4b. `MY_APP_ALT1` environment variable value
4c. `my-app.alt1` classpath resource content
@@ -252,11 +267,15 @@ Options:
`:default` - Fallback to return unparsed if no value found during search (default `nil`).
`:return` - Return type ∈ #{:value :map :explain} (default `:value`).
-Resulting config value must be something that can be safely embedded in code during
-macro-expansion. Symbols in edn will be evaluated during expansion.
+For Cljs: resulting config value must be something that can be safely
+ embedded in code during macro 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.
Returns current ?{:keys [compile-time runtime]} filter config.
+Advanced: if resulting config value is a single top-level symbol, it will
+ be evaluated during macro 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.
Alpha, subject to change.
Returns ?{<handler-id> {:keys [handling-nsecs counts]}} for all registered
@@ -351,31 +370,31 @@ environment variables, or classpath resources.
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`
+ JVM property: `taoensso.telemere.rt-kind-filter`
+ Env variable: `TAOENSSO_TELEMERE_RT_KIND_FILTER`
+ Classpath resource: `taoensso.telemere.rt-kind-filter`
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`
+ JVM property: `taoensso.telemere.rt-ns-filter`
+ Env variable: `TAOENSSO_TELEMERE_RT_NS_FILTER`
+ Classpath resource: `taoensso.telemere.rt-ns-filter`
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`
+ JVM property: `taoensso.telemere.rt-id-filter`
+ Env variable: `TAOENSSO_TELEMERE_RT_ID_FILTER`
+ Classpath resource: `taoensso.telemere.rt-id-filter`
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`
+ JVM property: `taoensso.telemere.rt-min-level`
+ Env variable: `TAOENSSO_TELEMERE_RT_MIN_LEVEL`
+ Classpath resource: `taoensso.telemere.rt-min-level`
-Examples:
+Values are edn, examples:
- `taoensso.telemere.rt-min-level.edn` -> ":info"
- `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"
+ `taoensso.telemere.rt-min-level` -> ":info"
+ `TAOENSSO_TELEMERE_RT_NS_FILTER` -> "{:disallow \"taoensso.*\"}"
+ `taoensso.telemere.rt-id-filter.cljs` -> "#{:my-id1 :my-id2}"
+ `TAOENSSO_TELEMERE_RT_KIND_FILTER_CLJ` -> "nil"
For other (non-filter) environmental config, see the relevant docstrings.
@@ -389,12 +408,11 @@ Tips:
".clj.edn" / "_CLJ_EDN" or
".cljs.edn" / "_CLJS_EDN" suffixes instead.
- - ".edn" / "_EDN" suffixes are optional.
+ - Optional ".edn" / "_EDN" suffixes may be added for clarity.
- - 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`.
+ - To get the right edn 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.
@@ -502,6 +520,10 @@ All handlers support the same dispatch options, including:
Optional handler priority ∈ℤ.
Handlers will be called in descending priority order (larger ints first).
+ `:track-stats?` (default true)
+ Should handler track statistics (e.g. handling times) for
+ reporting by `get-handlers-stats`?
+
`: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:
@@ -645,6 +667,7 @@ and return values), making them more/less convenient for certain use cases:
`: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`)
+ Defaults to `:auto` for tracing signals, and nil otherwise
`: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
@@ -663,6 +686,7 @@ and return values), making them more/less convenient for certain use cases:
`:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all)
`:when` -------- Arb ?form; when present, form must return truthy to allow signal
`:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details
+`:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!)
`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created
`:trace?` ------ Should tracing be enabled for `:run` form?
@@ -674,7 +698,7 @@ If anything is unclear, please ping me (@ptaoussanis) so that I can improve thes
[1] `java.time.Instant` or `js/Date`
[2] `java.lang.Throwable` or `js/Error`
(log! msg)(log! level msg)(log! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error & kvs]} msg)
"Log" signal creator, emphasizing message + level.
API: [msg] [level-or-opts msg] => true iff signal was allowed.
Default kind: `:log`
@@ -761,18 +785,15 @@ Override default by setting one of the following to "true" or "false":
See also: `otel-get-default-providers`, `*otel-tracer*`,
`taoensso.telemere.open-telemere/handler:open-telemetry`.
-[1] Ref. <https://github.com/open-telemetry/opentelemetry-java>
Experimental, subject to change.
Returns a (fn pr [signal]) that:
- Takes a Telemere signal (map).
- Returns a machine-readable signal string.
Options:
`:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)}
- `: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
- excluded by default: #{:location :kvs :file :host :thread}
+ `:clean-fn` - (fn [signal]) => clean signal map, see [1]
+ `:incl-newline?` - Include terminating system newline? (default true)
Examples:
@@ -787,41 +808,25 @@ Examples:
#?(:cljs :json ; Use js/JSON.stringify
:clj jsonista/write-value-as-string)})
-Motivation:
- Why use this util instead of just directly using the print function
- given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
- so may contain things like nil values and duplicated content.
-
- This util efficiently clean signals of such noise, helping reduce
- storage/transmission size, and making key info easier to see.
+[1] `taoensso.telemere.utils/clean-signal-fn`, etc.
See also `format-signal-fn` for an alternative to `pr-signal-fn`
that produces human-readable output.
Takes a spec of form
- [ [<n-max-reqs> <msecs-window>] ...] or
- {<limit-id> [<n-max-reqs> <msecs-window>]},
-and returns a basic stateful (fn a-rate-limiter [req-id] [command req-id]).
+ [ [<n-max-reqs> <msecs-window>] ...] or ; Unnamed limits
+ {<limit-id> [<n-max-reqs> <msecs-window>]} ; Named limits
+and returns stateful (fn a-rate-limiter [] [req-id] [command req-id]).
-Call the limiter fn with a request id (e.g. username) by which to count/limit.
-Will return:
- - nil when allowed (all limits pass for given req-id), or
- - [<worst-limit-id> <worst-backoff-msecs> {<limit-id> <backoff-msecs>}]
- when denied (any limits fail for given req-id).
+Call the returned limiter fn with a request id (any Clojure value!) to
+enforce limits independently for each id.
-Or call the limiter fn with an additional command argument:
- `:rl/peek` <req-id> - Check limits w/o incrementing count.
- `:rl/reset` <req-id> - Reset all limits for given req-id.
+For example, (limiter-fn <ip-address-string>) will return:
+ - Falsey when allowed (all limits pass for given IP), or
+ - Truthy when disallowed (any limits fail for given IP):
+ [<worst-limit-id> <worst-backoff-msecs> {<limit-id> <backoff-msecs>}]
-Example:
-
- (defonce my-rate-limiter
- (rate-limiter
- {"1 per sec" [1 1000]
- "10 per min" [10 60000]}))
-
- (defn send-message! [username msg-content]
- (if-let [fail (my-rate-limiter username)]
- (throw (ex-info "Sorry, rate limited!" {:fail fail}))
- <send message>))
Stops and deregisters signal handler with given id, and returns
+Or call the returned limiter fn with an extra command argument:
+ (limiter-fn :rl/peek <req-id) - Check limits WITHOUT incrementing count
+ (limiter-fn :rl/reset <req-id) - Reset all limits for given req-id
Sets signal id filter based on given `id-filter` spec.
@@ -881,7 +886,7 @@ Examples:
- A map, {:allow <spec> :disallow <spec>} with specs as above:
If present, `:allow` spec MUST match, AND
If present, `:disallow` spec MUST NOT match.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent root trace? do let data msg error run & kvs]})
Low-level generic signal creator.
+the new value. Cross-platform. See also `update-var-root!`.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]})
Low-level generic signal creator.
API: [opts] => depends on options [2]
Default kind: none (optional)
@@ -908,7 +913,17 @@ 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.)
(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 root 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.)
(signal-allowed? {:as opts, :keys [elidable? location sample-rate kind ns id level when rate-limit rate-limit-by]})
Returns true iff signal with given opts would meet filtering conditions:
+ (when (signal-allowed? {:level :warn, <...>}) (my-custom-code))
+
+Allows you to use Telemere's rich filtering system for conditionally
+executing arbitrary code. Also handy for batching multiple signals
+under a single set of conditions (incl. rate-limiting, sampling, etc.):
+
+ ;; Logs exactly 2 or 0 messages (never 1):
+ (when (signal-allowed? {:level :info, :sample-rate 0.5})
+ (log! {:allow? true} "Message 1")
+ (log! {:allow? true} "Message 2"))
(spy! form)(spy! level form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)
"Spy" signal creator, emphasizing form + level.
API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:spy`
@@ -918,6 +933,9 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
+`form` is generally expected to be synchronous and eager (not a lazy seq,
+async call, or IOT code like a core.async `go` block, etc.).
+
Examples:
(spy! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
@@ -972,7 +990,7 @@ and setting `System/err` won't necessarily affect Clojure's `*err*`.
See also:
`with-out->telemere`,
`with-err->telemere`,
- `with-streams->telemere`.
(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 root trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
+ `with-streams->telemere`.
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit rate-limit-by ctx parent root trace? do let data msg error run & kvs]} form)
"Trace" signal creator, emphasizing form + id.
API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
Default kind: `:trace`
@@ -982,6 +1000,9 @@ When filtering conditions are met [4], creates a Telemere signal [3] and
dispatches it to registered handlers for processing (e.g. writing to
console/file/queue/db, etc.).
+`form` is generally expected to be synchronous and eager (not a lazy seq,
+async call, or IOT code like a core.async `go` block, etc.).
+
Examples:
(trace! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
@@ -1016,7 +1037,7 @@ 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.)
\ No newline at end of file
diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html
index b410a4e..6b37dc4 100644
--- a/taoensso.telemere.timbre.html
+++ b/taoensso.telemere.timbre.html
@@ -1,6 +1,6 @@
-taoensso.telemere.timbre documentation
Interop support for tools.logging -> Telemere.
Telemere will attempt to load this ns automatically when possible.
Naming conventions:
`tools.logging` - For referring to the library.
`tools-logging` - For symbols, keywords, and this namespace.
`clojure.tools.logging` - For env config to match library's conventions.
check-interop
clj
(check-interop)
Returns interop debug info map.
-
tools-logging->telemere!
clj
(tools-logging->telemere!)
Configures `tools.logging` to use Telemere as its logging
+
tools-logging->telemere!
clj
(tools-logging->telemere!)
Configures tools.logging to use Telemere as its logging
implementation (backend).
Called automatically if one of the following is "true":
JVM property: `clojure.tools.logging.to-telemere`
Env variable: `CLOJURE_TOOLS_LOGGING_TO_TELEMERE`
- Classpath resource: `clojure.tools.logging.to-telemere`
tools-logging->telemere?
clj
(tools-logging->telemere?)
Returns true iff `tools.logging` is configured to use Telemere
+ Classpath resource: `clojure.tools.logging.to-telemere`
tools-logging->telemere?
clj
(tools-logging->telemere?)
Returns true iff tools.logging is configured to use Telemere
as its logging implementation (backend).
\ No newline at end of file
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
index e9f81a9..f8ad084 100644
--- a/taoensso.telemere.utils.cljs.html
+++ b/taoensso.telemere.utils.cljs.html
@@ -1,7 +1,22 @@
-taoensso.telemere.utils documentation
Experimental, subject to change.
+Returns a (fn clean [signal]) that:
+ - Takes a Telemere signal (map).
+ - Returns a minimal signal (map) ready for printing, etc.
+
+Signals are optimized for cheap creation and easy handling, so tend to be
+verbose and may contain things like nil values and duplicated content.
+
+This util efficiently cleans signals of such noise, helping reduce
+storage/transmission size, and making key info easier to see.
+
+Options:
+ `:incl-nils?` - Include signal's keys with nil values? (default false)
+ `:incl-kvs?` - Include signal's app-level root kvs? (default false)
+ `:incl-keys` - Subset of signal keys to retain from those otherwise
+ excluded by default: #{:location :kvs :file :host :thread}
Experimental, subject to change.
Returns a (fn format [error]) that:
@@ -30,8 +45,8 @@ Returns a (fn format [signal]) that:
Options:
`:incl-newline?` - Include terminating system newline? (default true)
- `:preamble-fn` - (fn [signal]) => signal preamble string, see [1].
- `:content-fn` - (fn [signal]) => signal content string, see [2].
+ `:preamble-fn` - (fn [signal]) => signal preamble string, see [1]
+ `:content-fn` - (fn [signal]) => signal content string, see [2]
[1] `taoensso.telemere.utils/signal-preamble-fn`, etc.
[2] `taoensso.telemere.utils/signal-content-fn`, etc.
@@ -51,18 +66,15 @@ Returns a (fn nano-uid [root?]) that returns a random nano-style uid string like
"tMEYoZH0K-" - 60 bit (10 char) non-root (child) uid
Experimental, subject to change.
Returns a (fn pr [signal]) that:
- Takes a Telemere signal (map).
- Returns a machine-readable signal string.
Options:
`:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)}
- `: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
- excluded by default: #{:location :kvs :file :host :thread}
+ `:clean-fn` - (fn [signal]) => clean signal map, see [1]
+ `:incl-newline?` - Include terminating system newline? (default true)
Examples:
@@ -77,13 +89,7 @@ Examples:
#?(:cljs :json ; Use js/JSON.stringify
:clj jsonista/write-value-as-string)})
-Motivation:
- Why use this util instead of just directly using the print function
- given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
- so may contain things like nil values and duplicated content.
-
- This util efficiently clean signals of such noise, helping reduce
- storage/transmission size, and making key info easier to see.
+[1] `taoensso.telemere.utils/clean-signal-fn`, etc.
See also `format-signal-fn` for an alternative to `pr-signal-fn`
that produces human-readable output.
Experimental, subject to change.
+Returns a (fn clean [signal]) that:
+ - Takes a Telemere signal (map).
+ - Returns a minimal signal (map) ready for printing, etc.
+
+Signals are optimized for cheap creation and easy handling, so tend to be
+verbose and may contain things like nil values and duplicated content.
+
+This util efficiently cleans signals of such noise, helping reduce
+storage/transmission size, and making key info easier to see.
+
+Options:
+ `:incl-nils?` - Include signal's keys with nil values? (default false)
+ `:incl-kvs?` - Include signal's app-level root kvs? (default false)
+ `:incl-keys` - Subset of signal keys to retain from those otherwise
+ excluded by default: #{:location :kvs :file :host :thread}
Experimental, subject to change.
Opens the specified file and returns a stateful fn of 2 arities:
@@ -41,8 +56,8 @@ Returns a (fn format [signal]) that:
Options:
`:incl-newline?` - Include terminating system newline? (default true)
- `:preamble-fn` - (fn [signal]) => signal preamble string, see [1].
- `:content-fn` - (fn [signal]) => signal content string, see [2].
+ `:preamble-fn` - (fn [signal]) => signal preamble string, see [1]
+ `:content-fn` - (fn [signal]) => signal content string, see [2]
[1] `taoensso.telemere.utils/signal-preamble-fn`, etc.
[2] `taoensso.telemere.utils/signal-content-fn`, etc.
@@ -62,18 +77,15 @@ Returns a (fn nano-uid [root?]) that returns a random nano-style uid string like
"r76-B8LoIPs5lBG1_Uhdy" - 126 bit (21 char) root uid
"tMEYoZH0K-" - 60 bit (10 char) non-root (child) uid
Experimental, subject to change.
Returns a (fn pr [signal]) that:
- Takes a Telemere signal (map).
- Returns a machine-readable signal string.
Options:
`:pr-fn` - ∈ #{<unary-fn> :edn (default) :json (Cljs only)}
- `: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
- excluded by default: #{:location :kvs :file :host :thread}
+ `:clean-fn` - (fn [signal]) => clean signal map, see [1]
+ `:incl-newline?` - Include terminating system newline? (default true)
Examples:
@@ -88,13 +100,7 @@ Examples:
#?(:cljs :json ; Use js/JSON.stringify
:clj jsonista/write-value-as-string)})
-Motivation:
- Why use this util instead of just directly using the print function
- given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
- so may contain things like nil values and duplicated content.
-
- This util efficiently clean signals of such noise, helping reduce
- storage/transmission size, and making key info easier to see.
+[1] `taoensso.telemere.utils/clean-signal-fn`, etc.
See also `format-signal-fn` for an alternative to `pr-signal-fn`
that produces human-readable output.