2024-03-28 15:32:21 +00:00
< !DOCTYPE html PUBLIC ""
"">
2024-08-28 16:36:50 +00:00
< html > < head > < meta charset = "UTF-8" / > < title > taoensso.telemere.utils documentation< / title > < link rel = "stylesheet" type = "text/css" href = "css/default.css" / > < link rel = "stylesheet" type = "text/css" href = "css/highlight.css" / > < script type = "text/javascript" src = "js/highlight.min.js" > < / script > < script type = "text/javascript" src = "js/jquery.min.js" > < / script > < script type = "text/javascript" src = "js/page_effects.js" > < / script > < script > hljs . initHighlightingOnLoad ( ) ; < / script > < / head > < body > < div id = "header" > < h2 > Generated by < a href = "https://github.com/weavejester/codox" > Codox< / a > < / h2 > < h1 > < a href = "index.html" > < span class = "project-title" > < span class = "project-name" > Telemere< / span > < span class = "project-version" > 1.0.0-beta22< / span > < / span > < / a > < / h1 > < div id = "langs" > < div class = "lang" > < a href = "index.clj.html" > clj< / a > < / div > < div class = "lang current" > cljs< / div > < / div > < / div > < div class = "sidebar primary" > < h3 class = "no-link" > < span class = "inner" > Namespaces< / span > < / h3 > < ul > < li class = "depth-1" > < div class = "no-link" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > taoensso< / span > < / div > < / div > < / li > < li class = "depth-2" > < a href = "taoensso.telemere.cljs.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > telemere< / span > < / div > < / a > < / li > < li class = "depth-3 branch" > < a href = "taoensso.telemere.timbre.cljs.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > timbre< / span > < / div > < / a > < / li > < li class = "depth-3 current" > < a href = "taoensso.telemere.utils.cljs.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > utils< / span > < / div > < / a > < / li > < / ul > < / div > < div class = "sidebar secondary" > < h3 > < a href = "#top" > < span class = "inner" > Public Vars< / span > < / a > < / h3 > < ul > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-error-signal.3F" > < div class = "inner" > < span > error-signal?< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-format-error-fn" > < div class = "inner" > < span > format-error-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-format-inst-fn" > < div class = "inner" > < span > format-inst-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-format-nsecs-fn" > < div class = "inner" > < span > format-nsecs-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-format-signal-fn" > < div class = "inner" > < span > format-signal-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-hex-uid-fn" > < div class = "inner" > < span > hex-uid-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-js-console-logger" > < div class = "inner" > < span > js-console-logger< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-nano-uid-fn" > < div class = "inner" > < span > nano-uid-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-newline" > < div class = "inner" > < span > newline< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-pr-edn" > < div class = "inner" > < span > pr-edn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-pr-json" > < div class = "inner" > < span > pr-json< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-pr-signal-fn" > < div class = "inner" > < span > pr-signal-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-signal-content-fn" > < div class = "inner" > < span > signal-content-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-signal-preamble-fn" > < div class = "inner" > < span > signal-preamble-fn< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.cljs.html#var-uuid-str" > < div class = "inner" > < span > uuid-str< / span > < / div > < / a > < / li > < / ul > < / div > < div class = "namespace-docs" id = "content" > < h1 class = "anchor" id = "top" > taoensso.telemere.utils< / h1 > < div class = "doc" > < pre class = "plaintext" > Mi
2024-05-10 13:50:11 +00:00
< / pre > < / div > < div class = "public anchor" id = "var-error-signal.3F" > < h3 > error-signal?< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-error-signal.3F" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (error-signal? signal)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-03-28 15:32:21 +00:00
Returns true iff given signal has an `:error` value, or a `:kind` or `:level`
that indicates that it's an error.< / pre > < / div > < / div > < div class = "public anchor" id = "var-format-error-fn" > < h3 > format-error-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-format-error-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (format-error-fn)< / code > < code > (format-error-fn {:as _opts})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
Returns a (fn format [error]) that:
- Takes a platform error (`Throwable` or `js/Error`).
2024-05-06 14:10:30 +00:00
- Returns a human-readable error string.< / pre > < / div > < / div > < div class = "public anchor" id = "var-format-inst-fn" > < h3 > format-inst-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-format-inst-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < h4 class = "added" > added in Encore v3.98.0 (2024-04-08)< / h4 > < div class = "usage" > < code > (format-inst-fn)< / code > < code > (format-inst-fn {:keys [formatter]})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change without notice.
2024-04-05 16:27:05 +00:00
2024-03-28 15:32:21 +00:00
Returns a (fn format [instant]) that:
- Takes a platform instant (`java.time.Instant` or `js/Date`).
2024-05-06 14:10:30 +00:00
- Returns a formatted human-readable instant string.
2024-03-28 15:32:21 +00:00
2024-04-05 16:27:05 +00:00
Options:
2024-04-10 16:41:24 +00:00
`:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC).
2024-04-05 16:27:05 +00:00
`:formatter`
`java.time.format.DateTimeFormatter` (Clj) or
`goog.i18n.DateTimeFormat` (Cljs),
2024-03-28 15:32:21 +00:00
2024-04-05 16:27:05 +00:00
Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`),
e.g.: "2011-12-03T10:15:130Z".< / pre > < / div > < / div > < div class = "public anchor" id = "var-format-nsecs-fn" > < h3 > format-nsecs-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-format-nsecs-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (format-nsecs-fn)< / code > < code > (format-nsecs-fn {:as _opts})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-03-28 15:32:21 +00:00
Returns a (fn format [nanosecs]) that:
- Takes a long nanoseconds (e.g. runtime).
2024-05-06 14:10:30 +00:00
- Returns a human-readable string like:
2024-05-05 11:13:03 +00:00
"1.00m", "4.20s", "340ms", "822μs", etc.< / pre > < / div > < / div > < div class = "public anchor" id = "var-format-signal-fn" > < h3 > format-signal-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-format-signal-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (format-signal-fn)< / code > < code > (format-signal-fn {:keys [incl-newline? preamble-fn content-fn], :or {incl-newline? true, preamble-fn (signal-preamble-fn), content-fn (signal-content-fn)}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-03-28 15:32:21 +00:00
Returns a (fn format [signal]) that:
2024-05-06 14:10:30 +00:00
- Takes a Telemere signal (map).
- Returns a human-readable signal string.
Options:
`:incl-newline?` - Include terminating system newline? (default true)
2024-08-26 11:00:59 +00:00
`:preamble-fn` - (fn [signal]) => signal preamble string, see [1].
`:content-fn` - (fn [signal]) => signal content string, see [2].
2024-05-05 11:13:03 +00:00
2024-08-26 11:00:59 +00:00
[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.).< / pre > < / div > < / div > < div class = "public anchor" id = "var-hex-uid-fn" > < h3 > hex-uid-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-hex-uid-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (hex-uid-fn)< / code > < code > (hex-uid-fn {:keys [secure? root-len child-len], :or {root-len 32, child-len 16}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-08-19 14:09:46 +00:00
Returns a (fn hex-uid [root?]) that returns a random hex-style uid string like:
"05039666eb9dc3206475f44ab9f3d843" - 128 bit (32 char) root uid
"721fcef639a51513" - 64 bit (16 char) non-root (child) uid< / pre > < / div > < / div > < div class = "public anchor" id = "var-js-console-logger" > < h3 > js-console-logger< / h3 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (js-console-logger level)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns JavaScript console logger to match given signal level:
2024-03-28 15:32:21 +00:00
`:trace` -> `js/console.trace`,
`:error` -> `js/console.error`, etc.
Defaults to `js.console.log` for unmatched signal levels.
2024-08-19 14:09:46 +00:00
NB: assumes that `js/console` exists, handler constructors should check first!< / pre > < / div > < / div > < div class = "public anchor" id = "var-nano-uid-fn" > < h3 > nano-uid-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-nano-uid-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (nano-uid-fn)< / code > < code > (nano-uid-fn {:keys [secure? root-len child-len], :or {root-len 21, child-len 10}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
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< / pre > < / div > < / div > < div class = "public anchor" id = "var-newline" > < h3 > newline< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-newline" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < h4 class = "added" > added in Encore v3.68.0 (2023-09-25)< / h4 > < div class = "usage" > < / div > < div class = "doc" > < pre class = "plaintext" > Single system newline
2024-03-28 15:32:21 +00:00
< / pre > < / div > < / div > < div class = "public anchor" id = "var-pr-edn" > < h3 > pr-edn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-pr-edn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (pr-edn x)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Prints given arg to an edn string readable with `read-edn`.
2024-04-10 16:41:24 +00:00
< / pre > < / div > < / div > < div class = "public anchor" id = "var-pr-json" > < h3 > pr-json< / h3 > < h4 class = "lang current" > cljs< / h4 > < h4 class = "added" > added in Encore v3.98.0 (2024-04-08)< / h4 > < div class = "usage" > < code > (pr-json x)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns given Cljs argument as JSON string.
2024-05-10 13:50:11 +00:00
< / pre > < / div > < / div > < div class = "public anchor" id = "var-pr-signal-fn" > < h3 > pr-signal-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-pr-signal-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (pr-signal-fn)< / code > < code > (pr-signal-fn {:keys [pr-fn incl-kvs? incl-nils? incl-newline? incl-keys], :as opts, :or {pr-fn :edn, incl-newline? true}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-05-06 14:10:30 +00:00
Returns a (fn pr [signal]) that:
- Takes a Telemere signal (map).
2024-08-26 11:00:59 +00:00
- Returns a machine-readable signal string.
2024-05-05 11:13:03 +00:00
2024-05-06 14:10:30 +00:00
Options:
2024-05-08 07:27:07 +00:00
`:pr-fn` - ∈ #{< unary-fn> :edn (default) :json (Cljs only)}
2024-08-07 09:48:04 +00:00
`:incl-kvs?` - Include signal's app-level kvs? (default false)
2024-05-10 13:50:11 +00:00
`: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
2024-08-23 12:09:04 +00:00
excluded by default: #{:location :kvs :file :host :thread}
2024-05-05 11:13:03 +00:00
Examples:
2024-05-08 07:27:07 +00:00
2024-08-26 11:00:59 +00:00
;; To print as edn:
(pr-signal-fn {:pr-fn :edn})
2024-05-05 11:13:03 +00:00
2024-08-26 11:00:59 +00:00
;; To print as JSON:
;; Ref. < < a href = "https://github.com/metosin/jsonista" > https://github.com/metosin/jsonista< / a > > (or any alt JSON lib)
#?(:clj (require '[jsonista.core :as jsonista]))
(pr-signal-fn
{:pr-fn
#?(:cljs :json ; Use js/JSON.stringify
:clj jsonista/write-value-as-string)})
2024-05-05 11:13:03 +00:00
2024-08-23 12:09:04 +00:00
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.
2024-08-26 11:00:59 +00:00
See also `format-signal-fn` for an alternative to `pr-signal-fn`
that produces human-readable output.< / pre > < / div > < / div > < div class = "public anchor" id = "var-signal-content-fn" > < h3 > signal-content-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-signal-content-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (signal-content-fn)< / code > < code > (signal-content-fn {:keys [raw-error? incl-keys format-nsecs-fn format-error-fn], :or {format-nsecs-fn (format-nsecs-fn), format-error-fn (format-error-fn)}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-05-05 11:13:03 +00:00
Returns a (fn content [signal]) that:
2024-05-06 14:10:30 +00:00
- Takes a Telemere signal (map).
- Returns a signal content ?string (incl. data, ctx, etc.).
2024-05-05 11:13:03 +00:00
2024-05-06 14:10:30 +00:00
Options:
2024-05-10 13:50:11 +00:00
`:raw-error?` - Retain unformatted error? (default false)
`:incl-keys` - Subset of signal keys to retain from those
2024-08-23 12:09:04 +00:00
otherwise excluded by default: #{:kvs :host :thread}
2024-05-06 14:10:30 +00:00
`:format-nsecs-fn` - (fn [nanosecs]) => string.
`:format-error-fn` - (fn [error]) => string.< / pre > < / div > < / div > < div class = "public anchor" id = "var-signal-preamble-fn" > < h3 > signal-preamble-fn< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-signal-preamble-fn" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (signal-preamble-fn)< / code > < code > (signal-preamble-fn {:keys [format-inst-fn], :or {format-inst-fn (format-inst-fn)}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-05-05 11:13:03 +00:00
Returns a (fn preamble [signal]) that:
2024-05-06 14:10:30 +00:00
- Takes a Telemere signal (map).
2024-05-05 11:13:03 +00:00
- Returns a signal preamble ?string like:
"2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"
2024-05-06 14:10:30 +00:00
Options:
2024-08-19 14:09:46 +00:00
`:format-inst-fn` - (fn format [instant]) => string.< / pre > < / div > < / div > < div class = "public anchor" id = "var-uuid-str" > < h3 > uuid-str< / h3 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.html#var-uuid-str" > clj< / a > < / h4 > < h4 class = "lang current" > cljs< / h4 > < div class = "usage" > < code > (uuid-str max-len)< / code > < code > (uuid-str)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns a random UUID string of given length (max 36).
Uses strong randomness when possible. See also `uuid`, `nanoid`, `rand-id-fn`.< / pre > < / div > < / div > < / div > < / body > < / html >
