\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index e1acd28..8833176 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-alpha1
\ No newline at end of file
diff --git a/index.html b/index.html
index 629f379..49f1f55 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-alpha1
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index 906690b..b564a9f 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>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -61,8 +61,8 @@ Dispatch options include:
0.0 => noop every arg
0.5 => handle random 50% of args
- `ns-filter` - Namespace filter as in `set-ns-filter!`
`kind-filter` - Kind filter as in `set-kind-filter!` (when relevant)
+ `ns-filter` - Namespace filter as in `set-ns-filter!`
`id-filter` - Id filter as in `set-id-filter!` (when relevant)
`min-level` - Minimum level as in `set-min-level!`
@@ -107,12 +107,171 @@ Flow sequence:
e. Hander fn
Note: call filters should generally be at least as permissive as handler filters,
- otherwise calls will be suppressed before reaching handlers.
(catch->error! 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 & extra-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 [1],
+ then return (:catch-val opts) if it exists, or rethrow the error.
+
+API: [form] [id-or-opts form] => form's result (value/throw) (unconditional), or (:catch-val opts)
+Default kind: `:error`
+Default level: `:error`
+
+Examples:
+
+ (catch->error! (/ 1 0)) ; %> {:kind :error, :level :error, :error <caught> ...}
+ (catch->error! ::my-id (/ 1 0)) ; %> {... :id ::my-id ...}
+ (catch->error!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}
+ :msg ["My msg:" x my-error]
+ :catch-val "Return value when form throws"
+ :catch-sym my-error ; Sym of caught error, available to `:data` and `:msg`
+ }
+
+ (/ 1 0)) ; %> {... :data {x "x"}, :msg_ "My msg: x <caught>" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (catch->error! ...)).
+ - Supports the same options as other signals [1].
+
+ - Useful for recording errors in forms, futures, callbacks, etc.
+
+See also `error!`.
+
+[1] See `help:signal-options` docstring
Experimental, subject to change.
+
+If `js/console` exists, returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes a formatted signal string to JavaScript console.
+
+Common formatting alternatives:
+ (utils/format-signal-str->fn) ; For human-readable string output (default)
+ (utils/format-signal->edn-fn) ; For edn output
+ (utils/format-signal->json-fn) ; For JSON output
+ etc.
+
+ See each format builder for options, etc.
Advanced feature. Default root (base) value of `*ctx*` var, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
-See `get-env` for details.
(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 & extra-kvs]} error)
"Error" signal call, focused on error + id.
+
+API: [error] [id-or-opts error] => given error (unconditional)
+Default kind: `:error`
+Default level: `:error`
+
+Examples:
+
+ (throw (error! (ex-info "MyEx" {}))) ; %> {:kind :error, :level :error, :error <MyEx> ...}
+ (throw (error! ::my-id (ex-info "MyEx" {}))) ; %> {... :id ::my-id ...}
+ (throw
+ (error!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}
+ :msg ["My message:" x]}
+
+ (ex-info "MyEx" {}))) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (error! ...)).
+ - Supports the same options as other signals [3].
+
+ - `error` arg is a platform error (`java.lang.Throwable` or `js/Error`).
+ - Can conveniently be wrapped by `throw`: (throw (error! ...)).
+
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]})
"Event" signal call, focused on id + level.
+
+API: [id] [id level-or-opts] => true iff signal call was allowed
+Default kind: `:event`
+Default level: `:info`
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (event! ::my-id) ; %> {:kind :event, :level :info, :id ::my-id ...}
+ (event! ::my-id :warn) ; %> {... :level :warn ...}
+ (event! ::my-id
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}
+ :msg ["My msg:" x]}) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (error! ...)).
+ - Supports the same options as other signals [3].
+
+ - A good general-purpose signal, prefer to `log!` by default, since it
+ better encourages structured data over unstructured messages.
+
+ - Has a different 2-arity arg order to all other signals!
+ Mnemonic: the arg that's typically larger is *always* in the rightmost
+ position, and for `event!` that's the `level-or-opts` arg.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
Cross-platform util for embedding flexible environmental config 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:
+ - JVM property value for id ("prop")
+ - Environment variable value for id ("env")
+ - Classpath resource content for id ("res")
+
+Ids may include optional segment in `<>` tag (e.g. `<.edn>`).
+Ids may include `<.?platform.?>` tag for auto replacement, useful
+for supporting platform-specific config.
+
+Search order: desc by combined [alt-index platform(y/n) optional(y/n)].
+
+(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 (content type)
+ 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 (content type)
+ 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 (content type)
+ 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 (content type)
+ 4a. `my-app.alt1` JVM property value
+ 4b. `MY_APP_ALT1` environment variable value
+ 4c. `my-app.alt1` classpath resource content
+
+ 5. Alt2
+ 5a. `my-app.alt2` JVM property value
+ 5b. `MY_APP_ALT2` environment variable value
+ 5c. `my-app.alt2` classpath resource content
+
+Options:
+ `:as` - Parse found value as given type ∈ #{:str :bool :edn} (default :str).
+ `:default` - Fallback to return if no value found during search (default nil).
+ `:return` - Return type ∈ #{:value :map :debug} (default :value).
+ TIP: Use `:debug` to inspect/verify search behaviour!
+
+Result must be something that can be safely embedded in code during
+macro-expansion. Symbols in edn will be evaluated during expansion.
Your filter config determines which signal calls will be allowed.
@@ -125,10 +284,10 @@ Both compile-time and runtime config can be specified via:
2. The filter API consting of the following:
- `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
- `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
- `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
`set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
+ `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
+ `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
+ `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
See the relevant docstrings for details.
@@ -151,9 +310,165 @@ improve these docs!
Signals are initially maps with {:keys [inst id ns level data msg_ ...]},
+though they can be modified by call and/or handler middleware.
+
+Default 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 <user-val> ...}
+`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
+`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
+
+`:msg` - Arb user-level message ?str given to signal call
+`:data` - Arb user-level data ?val (usu. a map) given to signal call
+`:error` - Arb user-level platform ?error [2] given to signal call
+
+`:run-form` - Unevaluated ?form given to signal call 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
+`:parent` - ?{:keys [id uid]} of parent signal, present in nested signals when tracing
+`:location` - ?{:keys [ns file line column]} signal call location
+`:ns` - ?str namespace of signal call, same as (:ns location)
+`:line` - ?int line of signal call, same as (:line location)
+`:column` - ?int column of signal call, same as (:column location)
+`:file` - ?str filename of signal call, same as (:file location)
+
+`:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
+
+<extra-kvs> - Arb user-level ?kvs given to signal call
+
+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`
A signal will be provided to a handler iff ALL of the following are true:
+
+ 1. Signal call is allowed by compile-time filters
+ 2. Signal call is allowed by runtime filters
+ 3. Handler is allowed by runtime filters
+
+ 4. Signal call middleware does not suppress the signal (return nil)
+ 5. Handler middleware does not suppress the signal (return nil)
+
+For more info:
+
+ - On call filters, see: `help:filters` docstring
+ - On handler filters, see: `help:handlers` docstring
+ - On signal flow, see: Ref. <https://tinyurl.com/telemere-signal-flowchart>
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can
+improve these docs!
Signal options (shared by `signal!`, `event!`, ...):
+
+`:inst` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
+`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
+`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
+`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
+`:uid` - ?id of signal instance (unique to each signal created by signal call, 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]
+
+`:run` - ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal
+`:do` - ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding
+`:let` - ?binding to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!)
+
+`:ctx` - Custom ?val to override auto (dynamic `*ctx*`) in signal
+`:parent` - Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal
+`:location` - Custom ?{:keys [ns line column file]} to override auto signal call location
+
+`:elidable?` - Should signal call be subject to compile-time elision? (Default: true)
+`:sample-rate` - ?rate ∈ℝ[0,1] for call 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 `telemere/rate-limiter`, see its docstring for details
+`:middleware` - ?[(fn [signal])=>modified-signal ...] call middleware
+`:trace?` - Should tracing be enabled for `:run` form?
+
+<extra-kvs> - Arb user-level ?kvs to incl. in signal
+
+If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
+
+[1] `java.time.Instant` or `js/Date`
+[2] `java.lang.Throwable` or `js/Error`
(log! msg)(log! level msg)(log! {: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 & extra-kvs]} msg)
"Log" signal call, focused on message + level.
+
+API: [msg] [level-or-opts msg] => true iff signal call was allowed.
+Default kind: `:log`
+Default level: `:info`
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (log! "My msg") ; %> {:kind :log, :level :info, :id ::my-id ...}
+ (log! :warn "My msg") ; %> {... :level :warn ...}
+ (log!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}}
+
+ ["My msg:" x]) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (log! ...)).
+ - Supports the same options as other signals [3].
+
+ - Prefer `event!` to `log!` by default, since it better encourages structured
+ data over unstructured messages.
+
+ - `msg` arg may be a string, or vector of strings to join with `\space`.
+ - See also `msg-splice`, `msg-skip` utils.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
For use within signal message vectors.
+Wraps given arguments so that they're spliced when creating message.
+Useful for conditionally splicing in extra message content, etc.:
+
+ (signal! {:msg [(when <cond> (msg-splice ["Username:" "Steve"])) <...>]}) or
+ (log! [(when <cond> (msg-splice ["Username:" "Steve"]))])
+
+ %> {:msg_ "Username: Steve"}
Takes a map spec of form {<limit-id> [<n-max-reqs> <msecs-window>]},
+and returns a basic stateful (fn rate-limiter [req-id] [command req-id]).
+
+Call fn with a single request id (e.g. username) by which to count/limit.
+Will return:
+ - nil when all limits pass for that id, or
+ - [<worst-limit-id> <worst-backoff-msecs> {<limit-id> <backoff-msecs>}]
+ when any limits fail for that id.
+
+Or call 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.
+
+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>))
Experimental, subject to change.
+
+If `js/console` exists, returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes raw signal data to JavaScript console.
+
+Intended for use with browser formatting tools like `binaryage/devtools`,
+Ref. <https://github.com/binaryage/cljs-devtools>.
Sets signal call id filter based on given `id-filter` spec.
`id-filter` may be:
- A regex pattern of id/s to allow.
@@ -165,7 +480,8 @@ still registered.
Sets minimum signal call level based on given `min-level` spec.
`min-level` may be:
- An integer.
@@ -182,11 +498,167 @@ will apply only for that signal kind.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]})
Low-level generic signal call.
+
+API: [opts] => depends on options [3]
+Default kind: none (optional)
+Default level: none (must be provided)
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+If `:run` option is provided: returns value of given run form, or throws.
+ Otherwise: returns true iff call conditions were met.
+
+Generic signals are fairly low-level and useful mostly for library authors or
+advanced users writing their own wrapper macros. Regular users will typically
+prefer one of the provided wrapper macros optimized for ease-of-use in
+common cases.
+
+These all use `signal!` underneath and offer the same options, but vary in
+their defaults and the focus of their call APIs (args and return values):
+
+ `event!` - (id + opts/level) => true iff signal call was allowed
+ `log!` - (message + opts/level) => true iff signal call was allowed
+ `error!` - (error + opts/id) => given error (unconditional)
+ `trace!` - (form + opts/id) => form's result (value/throw) (unconditional)
+ `spy!` - (form + opts/level) => form's result (value/throw) (unconditional)
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (signal! ...)).
+ - Supports the same options as other signals [3].
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]} form)
"Spy" signal call, focused on form + level.
+
+API: [form] [level-or-opts form] => form's result (value/throw) (unconditional)
+Default kind: `:spy`
+Default level: `:info`
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (spy! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
+ ; :run-val 3, :run-nsecs <int>, :parent {:keys [id uid]}
+ ; :msg "(+ 1 2) => 3" ...}
+ (spy! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
+ (spy!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}}
+
+ (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (spy! ...)).
+ - Supports the same options as other signals [3].
+
+ - Identical to `trace!`, but focused on form + level rather than form + id.
+
+ - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
+ - Execution of `form` arg may trigger additional (nested) signals.
+ Each signal's `:parent` key will indicate its immediate parent.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
(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 & extra-kvs]} form)
"Trace" signal call, focused on form + id.
+
+API: [form] [id-or-opts form] => form's result (value/throw) (unconditional)
+Default kind: `:trace`
+Default level: `:info` (intentionally NOT `:trace`!)
+
+When conditions are met [1], creates a Telemere signal [2] and dispatches it to
+registered handlers for processing (writing to console/disk/db, etc.).
+
+Examples:
+
+ (trace! (+ 1 2)) ; %> {:kind :trace, :level :info, :run-form '(+ 1 2),
+ ; :run-val 3, :run-nsecs <int>, :parent {:keys [id uid]} ...
+ ; :msg "(+ 1 2) => 3" ...}
+ (trace! ::my-id (+ 1 2)) ; %> {... :id ::my-id ...}
+ (trace!
+ {:let [x "x"] ; Available to `:data` and `:msg`
+ :data {:x x}}
+
+ (+ 1 2)) ; %> {... :data {x "x"}, :msg_ "My msg: x" ...}
+
+Tips:
+
+ - Test using `with-signals`: (with-signals (trace! ...)).
+ - Supports the same options as other signals [3].
+
+ - Identical to `spy!`, but focused on form + id rather than form + level.
+
+ - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
+ - Execution of `form` arg may trigger additional (nested) signals.
+ Each signal's `:parent` key will indicate its immediate parent.
+
+ - Default level is `:info`, not `:trace`! The name "trace" in "trace signal"
+ refers to the general action of tracing program flow rather than to the
+ common logging level of the same name.
+
+----------------------------------------
+[1] See `help:signal-handling` docstring
+[2] See `help:signal-content` docstring
+[3] See `help:signal-options` docstring
Updates root binding (value) of the var identified by given symbol, and returns
+the new value:
+ (update-var-root! my-var (fn [old-root-val] <new-root-val>)) => <new-root-val>
+
+Similar to `alter-var-root` but cross-platform and takes a symbol rather than a var.
+See also `set-var-root!`.
Evaluates given form with updated `*ctx*` value.
+
+`update-map-or-fn` may be:
+ - A map to merge with current `*ctx*` value, or
+ - A unary fn to apply to current `*ctx*` value
+
+See `*ctx*` for details.
Experimental
+Minimal version of `with-signals`.
+Executes given form and returns the last signal triggered by it.
+Useful for tests/debugging.
+
+- Always allows registered handlers to receive signals as usual.
+- Always traps form errors.
+- Never forces `:msg_` key.
+
+See also `with-signals` for more options.
Experimental.
+Executes given form and records any signals triggered by it.
+Return value depends on given options. Useful for tests/debugging.
+
+Options:
+
+ `handle?`
+ Should registered handlers receive signals triggered by form, as usual?
+ Default: true.
+
+ `trap-errors?`
+ If true: returns [[form-value form-error] signals], trapping any form error.
+ If false: returns [ form-value signals], throwing on form error.
+ Default: false.
+
+ `force-msg?`
+ Should delayed `:msg_` keys in signals be replaced with realized strings?
+ Default: false.
+
+See also `with-signal` for a simpler API.
\ No newline at end of file
diff --git a/taoensso.telemere.handlers.cljs.html b/taoensso.telemere.handlers.cljs.html
new file mode 100644
index 0000000..9803960
--- /dev/null
+++ b/taoensso.telemere.handlers.cljs.html
@@ -0,0 +1,23 @@
+
+taoensso.telemere.handlers documentation
Experimental, subject to change.
+
+If `js/console` exists, returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes a formatted signal string to JavaScript console.
+
+Common formatting alternatives:
+ (utils/format-signal-str->fn) ; For human-readable string output (default)
+ (utils/format-signal->edn-fn) ; For edn output
+ (utils/format-signal->json-fn) ; For JSON output
+ etc.
+
+ See each format builder for options, etc.
Experimental, subject to change.
+
+If `js/console` exists, returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes raw signal data to JavaScript console.
+
+Intended for use with browser formatting tools like `binaryage/devtools`,
+Ref. <https://github.com/binaryage/cljs-devtools>.
\ No newline at end of file
diff --git a/taoensso.telemere.handlers.html b/taoensso.telemere.handlers.html
new file mode 100644
index 0000000..cf1deb5
--- /dev/null
+++ b/taoensso.telemere.handlers.html
@@ -0,0 +1,19 @@
+
+taoensso.telemere.handlers documentation
Experimental, subject to change.
+
+Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes a formatted signal string to stream.
+
+Stream (`java.io.Writer`):
+ Defaults to `*err*` if `utils/error-signal?` is true, and `*out*` otherwise.
+
+Common formatting alternatives:
+ (utils/format-signal-str->fn) ; For human-readable string output (default)
+ (utils/format-signal->edn-fn) ; For edn output
+ (utils/format-signal->json-fn) ; For JSON output
+ etc.
+
+ See each format builder for options, etc.
\ No newline at end of file
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index 5368a87..c036f1b 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>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -61,8 +61,8 @@ Dispatch options include:
0.0 => noop every arg
0.5 => handle random 50% of args
- `ns-filter` - Namespace filter as in `set-ns-filter!`
`kind-filter` - Kind filter as in `set-kind-filter!` (when relevant)
+ `ns-filter` - Namespace filter as in `set-ns-filter!`
`id-filter` - Id filter as in `set-id-filter!` (when relevant)
`min-level` - Minimum level as in `set-min-level!`
@@ -107,7 +107,7 @@ Flow sequence:
e. Hander fn
Note: call filters should generally be at least as permissive as handler filters,
- otherwise calls will be suppressed before reaching handlers.
catch->error!
macro
clj
(catch->error! form)(catch->error! id form)(catch->error! {:as opts, :keys [rethrow? catch-val elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]} form)
Unconditionally executes given form and-
+ otherwise calls will be suppressed before reaching handlers.
(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 & extra-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 [1],
@@ -145,10 +145,25 @@ See also `error!`.
Runs Telemere's registered interop checks and returns
{<interop-id> {:keys [sending->telemere? telemere-receiving? ...]}}.
-Useful for tests/debugging.
Experimental, subject to change.
+
+Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes a formatted signal string to stream.
+
+Stream (`java.io.Writer`):
+ Defaults to `*err*` if `utils/error-signal?` is true, and `*out*` otherwise.
+
+Common formatting alternatives:
+ (utils/format-signal-str->fn) ; For human-readable string output (default)
+ (utils/format-signal->edn-fn) ; For edn output
+ (utils/format-signal->json-fn) ; For JSON output
+ etc.
+
+ See each format builder for options, etc.
Advanced feature. Default root (base) value of `*ctx*` var, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
-See `get-env` for details.
error!
macro
clj
(error! error)(error! id error)(error! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]} error)
"Error" signal call, focused on error + id.
+See `get-env` for details.
(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 & extra-kvs]} error)
"Error" signal call, focused on error + id.
API: [error] [id-or-opts error] => given error (unconditional)
Default kind: `:error`
@@ -176,7 +191,7 @@ Tips:
[1] See `help:signal-handling` docstring
[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
event!
macro
clj
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error & user-opts]})
"Event" signal call, focused on id + level.
+[3] See `help:signal-options` docstring
(event! id)(event! id level)(event! id {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]})
"Event" signal call, focused on id + level.
API: [id] [id level-or-opts] => true iff signal call was allowed
Default kind: `:event`
@@ -209,9 +224,7 @@ Tips:
----------------------------------------
[1] See `help:signal-handling` docstring
[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
Cross-platform util for embedding flexible environmental config during
macro expansion. Used by other Taoensso libraries.
Given a const kw/string id or vector of desc-priority alternative ids,
@@ -274,10 +287,10 @@ Both compile-time and runtime config can be specified via:
2. The filter API consting of the following:
- `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
- `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
- `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
`set-kind-filter!`, `with-kind-filter` - for filtering calls by signal kind (when relevant)
+ `set-ns-filter!`, `with-ns-filter` - for filtering calls by namespace
+ `set-id-filter!`, `with-id-filter` - for filtering calls by signal id (when relevant)
+ `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
See the relevant docstrings for details.
@@ -300,42 +313,43 @@ improve these docs!
help:signal-content
clj
Signals are initially maps with {:keys [instant id ns level data msg_ ...]},
+improve these docs!
Signals are initially maps with {:keys [inst id ns level data msg_ ...]},
though they can be modified by call and/or handler middleware.
Default keys:
-`:schema-version` - Int version of signal schema (current: 1)
+`: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 <user-val> ...}
+`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
+`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
-`:instant` - 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 <user-val> ...}
-`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
-`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
-
-`:data` - Arb user-level data ?val (usu. a map) given to signal call
`:msg` - Arb user-level message ?str given to signal call
+`:data` - Arb user-level data ?val (usu. a map) given to signal call
`:error` - Arb user-level platform ?error [2] given to signal call
-`:run-form` - Unevaluated ?form given to signal macro as `:run`
-`:run-value` - Successful return ?val of `:run` ?form
-`:end-instant` - Platform ?instant [1] when `:run` ?form completed
-`:runtime-nsecs`- ?int nanosecs runtime of `:run` ?form
+`:run-form` - Unevaluated ?form given to signal call 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
`:parent` - ?{:keys [id uid]} of parent signal, present in nested signals when tracing
`:location` - ?{:keys [ns file line column]} signal call location
`:ns` - ?str namespace of signal call, same as (:ns location)
-`:file` - ?str filename of signal call, same as (:file location)
`:line` - ?int line of signal call, same as (:line location)
`:column` - ?int column of signal call, same as (:column location)
+`:file` - ?str filename of signal call, same as (:file location)
`:sample-rate` - ?rate ∈ℝ[0,1] for combined call AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
+<extra-kvs> - Arb user-level ?kvs given to signal call
+
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
-[1] Clj: `java.time.Instant`, Cljs: `js/Date`
-[2] Clj: `java.lang.Throwable`, Cljs: `js/Error`
help:signal-handling
clj
A signal will be provided to a handler iff ALL of the following are true:
+[1] `java.time.Instant` or `js/Date`
+[2] `java.lang.Throwable` or `js/Error`
A signal will be provided to a handler iff ALL of the following are true:
1. Signal call is allowed by compile-time filters
2. Signal call is allowed by runtime filters
@@ -351,16 +365,16 @@ For more info:
- On signal flow, see: Ref. <https://tinyurl.com/telemere-signal-flowchart>
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
help:signal-options
clj
Signal options (shared by `signal!`, `event!`, ...):
+improve these docs!
Signal options (shared by `signal!`, `event!`, ...):
-`:instant` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
-`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
-`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
-`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
-`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
+`:inst` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
+`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
+`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
+`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
+`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
-`:data` - Arb user-level ?data to incl. in signal: usu. a map
`: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]
`:run` - ?form to execute UNCONDITIONALLY; will incl. `:run-value` in signal
@@ -378,14 +392,13 @@ improve these docs!
hostname
clj
(hostname)(hostname timeout-msecs timeout-val)
Returns local cached hostname string, or `timeout-val` (default "UnknownHost").
-
Sets minimum signal call level based on given `min-level` spec.
`min-level` may be:
@@ -489,8 +502,8 @@ will apply only for that signal kind.
set-var-root!
macro
clj
added in Encore v3.75.0 (2024-01-29)
(set-var-root! var-sym root-val)
Sets root binding (value) of the var identified by given symbol, and returns
-the new value. Cross-platform. See also `update-var-root!`.
signal!
macro
clj
(signal! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error run & user-opts]})
Low-level generic signal call.
+ - {:allow <spec> :deny <spec>} with specs as above.
(signal! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]})
Low-level generic signal call.
API: [opts] => depends on options [3]
Default kind: none (optional)
@@ -524,7 +537,7 @@ Tips:
----------------------------------------
[1] See `help:signal-handling` docstring
[2] See `help:signal-content` docstring
-[3] See `help:signal-options` docstring
spy!
macro
clj
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error run & user-opts]} form)
"Spy" signal call, focused on form + level.
+[3] See `help:signal-options` docstring
(spy! form)(spy! id form)(spy! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error run & extra-kvs]} form)
Configures `clojure.tools.logging` to use Telemere as its logging implementation.
-
trace!
macro
clj
(trace! form)(trace! id form)(trace! {:as opts, :keys [elidable? location instant uid middleware sample-rate ns kind id level when rate-limit ctx parent trace? do let data msg error run & user-opts]} form)
"Trace" signal call, focused on form + id.
+ `with-streams->telemere`.
tools-logging->telemere!
clj
(tools-logging->telemere!)
Configures `clojure.tools.logging` to use Telemere as its logging implementation.
+
(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 & extra-kvs]} form)
(uncaught->error!)(uncaught->error! id)(uncaught->error! {:as opts, :keys [elidable? location inst uid middleware sample-rate kind ns id level when rate-limit ctx parent trace? do let data msg error & extra-kvs]})
Uses `uncaught->handler!` so that `error!` will be called for
uncaught JVM errors.
See `uncaught->handler!` and `error!` for details.
uncaught->handler!
clj
(uncaught->handler! handler)
Sets JVM's global `DefaultUncaughtExceptionHandler` to given
(fn handler [`<java.lang.Thread>` `<java.lang.Throwable>`]).
-See also `uncaught->error!`.
update-var-root!
macro
clj
added in Encore v3.68.0 (2023-09-25)
(update-var-root! var-sym update-fn)
Updates root binding (value) of the var identified by given symbol, and returns
+See also `uncaught->error!`.
Updates root binding (value) of the var identified by given symbol, and returns
the new value:
(update-var-root! my-var (fn [old-root-val] <new-root-val>)) => <new-root-val>
Similar to `alter-var-root` but cross-platform and takes a symbol rather than a var.
-See also `set-var-root!`.
with-ctx
macro
clj
(with-ctx init-val form)
Evaluates given form with given `*ctx*` value. See `*ctx*` for details.
-
with-ctx+
macro
clj
(with-ctx+ update-map-or-fn form)
Evaluates given form with updated `*ctx*` value.
+See also `set-var-root!`.
Evaluates given form with updated `*ctx*` value.
`update-map-or-fn` may be:
- A map to merge with current `*ctx*` value, or
- A unary fn to apply to current `*ctx*` value
-See `*ctx*` for details.
Experimental
Minimal version of `with-signals`.
Executes given form and returns the last signal triggered by it.
Useful for tests/debugging.
@@ -648,7 +661,7 @@ Useful for tests/debugging.
- Always traps form errors.
- Never forces `:msg_` key.
-See also `with-signals` for more options.
Experimental.
Executes given form and records any signals triggered by it.
Return value depends on given options. Useful for tests/debugging.
@@ -667,6 +680,6 @@ Options:
Should delayed `:msg_` keys in signals be replaced with realized strings?
Default: false.
-See also `with-signal` for a simpler API.
\ No newline at end of file
diff --git a/taoensso.telemere.timbre-shim.cljs.html b/taoensso.telemere.timbre-shim.cljs.html
new file mode 100644
index 0000000..ae3f87a
--- /dev/null
+++ b/taoensso.telemere.timbre-shim.cljs.html
@@ -0,0 +1,4 @@
+
+taoensso.telemere.timbre-shim documentation
Utils to help ease migration from Timbre to Telemere.
+
\ No newline at end of file
diff --git a/taoensso.telemere.timbre-shim.html b/taoensso.telemere.timbre-shim.html
new file mode 100644
index 0000000..6df052b
--- /dev/null
+++ b/taoensso.telemere.timbre-shim.html
@@ -0,0 +1,4 @@
+
+taoensso.telemere.timbre-shim documentation
Utils to help ease migration from Timbre to Telemere.
+
\ No newline at end of file
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
new file mode 100644
index 0000000..abfb408
--- /dev/null
+++ b/taoensso.telemere.utils.cljs.html
@@ -0,0 +1,52 @@
+
+taoensso.telemere.utils documentation
Experimental, subject to change.
+Returns given signal with possible `:error` replaced by
+[{:keys [type msg data]} ...] cause chain.
+
+Useful when serializing signals to edn/JSON/etc.
Experimental, subject to change.
+Returns a (fn format [error]) that:
+ - Takes a platform error (`Throwable` or `js/Error`).
+ - Returns a formatted human-readable string
Experimental, subject to change.
+Returns a (fn format [instant]) that:
+ - Takes a platform instant (`java.time.Instant` or `js/Date`).
+ - Returns a formatted human-readable string.
+
+`:formatter` may be a `java.time.format.DateTimeFormatter` (Clj) or
+ `goog.i18n.DateTimeFormat` (Cljs).
+
+Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`),
+ e.g.: "2011-12-03T10:15:130Z".
Experimental, subject to change.
+Returns a (fn format [nanosecs]) that:
+ - Takes a long nanoseconds (e.g. runtime).
+ - Returns a formatted human-readable string like:
+ "1.00m", "4.20s", "340ms", "822μs", etc.
Experimental, subject to change.
+Returns a (fn format->edn [signal]) that:
+ - Takes a Telemere signal.
+ - Returns edn string of the (minified) signal.
Experimental, subject to change.
+Returns a (fn format->json [signal]) that:
+ - Takes a Telemere signal.
+ - Returns JSON string of the (minified) signal.
Experimental, subject to change.
+Returns a (fn format->str [signal]) that:
+ - Takes a Telemere signal.
+ - Returns a formatted string intended for text consoles, etc.
Experimental, subject to change.
+Returns a (fn format [signal]) that:
+ - Takes a Telemere signal.
+ - Returns a formatted prelude string like:
+ "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"
js-console-logger
cljs
(js-console-logger level)
Returns JavaScript console logger to match given signal level:
+ `:trace` -> `js/console.trace`,
+ `:error` -> `js/console.error`, etc.
+
+Defaults to `js.console.log` for unmatched signal levels.
+NB: assumes that `js/console` exists, handler builders should check first!
Experimental, subject to change.
+Returns minimal signal map, removing:
+ - Keys with nil values, and
+ - Keys with redundant values (`:extra-kvs`, `:location`, `:file`).
+
+Useful when serializing signals to edn/JSON/etc.
\ No newline at end of file
diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html
new file mode 100644
index 0000000..5639e74
--- /dev/null
+++ b/taoensso.telemere.utils.html
@@ -0,0 +1,58 @@
+
+taoensso.telemere.utils documentation
Experimental, subject to change.
+Returns given signal with possible `:error` replaced by
+[{:keys [type msg data]} ...] cause chain.
+
+Useful when serializing signals to edn/JSON/etc.
Experimental, subject to change.
+Returns a (fn format [error]) that:
+ - Takes a platform error (`Throwable` or `js/Error`).
+ - Returns a formatted human-readable string
Experimental, subject to change.
+Returns a (fn format [instant]) that:
+ - Takes a platform instant (`java.time.Instant` or `js/Date`).
+ - Returns a formatted human-readable string.
+
+`:formatter` may be a `java.time.format.DateTimeFormatter` (Clj) or
+ `goog.i18n.DateTimeFormat` (Cljs).
+
+Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`),
+ e.g.: "2011-12-03T10:15:130Z".
Experimental, subject to change.
+Returns a (fn format [nanosecs]) that:
+ - Takes a long nanoseconds (e.g. runtime).
+ - Returns a formatted human-readable string like:
+ "1.00m", "4.20s", "340ms", "822μs", etc.
Experimental, subject to change.
+Returns a (fn format->edn [signal]) that:
+ - Takes a Telemere signal.
+ - Returns edn string of the (minified) signal.
Experimental, subject to change.
+Returns a (fn format->json [signal]) that:
+ - Takes a Telemere signal.
+ - Returns JSON string of the (minified) signal.
Experimental, subject to change.
+Returns a (fn format->str [signal]) that:
+ - Takes a Telemere signal.
+ - Returns a formatted string intended for text consoles, etc.
Experimental, subject to change.
+Returns minimal signal map, removing:
+ - Keys with nil values, and
+ - Keys with redundant values (`:extra-kvs`, `:location`, `:file`).
+
+Useful when serializing signals to edn/JSON/etc.
Experimental, subject to change without notice.
+Returns given Clj argument as JSON string.
+Uses the first of the following, or throws if none available:
+ 1. `metosin/jsonista`, Ref. <https://github.com/metosin/jsonista>
+ 2. `cheshire`, Ref. <https://github.com/dakrone/cheshire>
+ 3. `org.clojure/clojure.data`, Ref. <https://github.com/clojure/data.json>
+
+In all cases attempts to provide sane + reasonably consistent behaviour, but
+prefer directly using a lib with opts of your choice when you have specific needs!