2024-03-28 15:32:21 +00:00
< !DOCTYPE html PUBLIC ""
"">
2024-05-10 13:50:11 +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-beta11< / span > < / span > < / a > < / h1 > < div id = "langs" > < div class = "lang current" > clj< / div > < div class = "lang" > < a href = "index.cljs.html" > cljs< / a > < / 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.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.open-telemetry.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > open-telemetry< / span > < / div > < / a > < / li > < li class = "depth-3 branch" > < a href = "taoensso.telemere.postal.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > postal< / span > < / div > < / a > < / li > < li class = "depth-3 branch" > < a href = "taoensso.telemere.slack.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > slack< / span > < / div > < / a > < / li > < li class = "depth-3 branch" > < a href = "taoensso.telemere.sockets.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > sockets< / span > < / div > < / a > < / li > < li class = "depth-3 branch" > < a href = "taoensso.telemere.streams.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > streams< / span > < / div > < / a > < / li > < li class = "depth-3 branch" > < a href = "taoensso.telemere.timbre.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 branch" > < a href = "taoensso.telemere.tools-logging.html" > < div class = "inner" > < span class = "tree" > < span class = "top" > < / span > < span class = "bottom" > < / span > < / span > < span > tools-logging< / span > < / div > < / a > < / li > < li class = "depth-3 current" > < a href = "taoensso.telemere.utils.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.html#var-error-signal.3F" > < div class = "inner" > < span > error-signal?< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.html#var-file-writer" > < div class = "inner" > < span > file-writer< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.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.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.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.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.html#var-host-ip" > < div class = "inner" > < span > host-ip< / span > < / div > < / a > < / li > < li class = "depth-1" > < a href = "taoensso.telemere.utils.html#var-hostname" > < div class = "inner" >
< / pre > < / div > < div class = "public anchor" id = "var-error-signal.3F" > < h3 > error-signal?< / h3 > < h4 class = "lang current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-error-signal.3F" > cljs< / a > < / 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`
2024-05-06 14:10:30 +00:00
that indicates that it's an error.< / pre > < / div > < / div > < div class = "public anchor" id = "var-file-writer" > < h3 > file-writer< / h3 > < h4 class = "lang current" > clj< / h4 > < div class = "usage" > < code > (file-writer {:keys [file append?], :or {append? true}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-04-05 16:27:05 +00:00
Opens the specified file and returns a stateful fn of 2 arities:
[content] => Writes given content to file, or no-ops if closed.
[] => Closes the writer.
2024-04-29 07:21:13 +00:00
Useful for basic handlers that write to a file, etc.
2024-04-05 16:27:05 +00:00
2024-04-29 07:21:13 +00:00
Notes:
- Automatically creates file and parent dirs as necessary.
- Writer should be manually closed after use (with zero-arity call).
- Flushes after every write.
- Thread safe, locks on single file stream.< / pre > < / div > < / div > < div class = "public anchor" id = "var-format-error-fn" > < h3 > format-error-fn< / h3 > < h4 class = "lang current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-format-error-fn" > cljs< / a > < / 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.
2024-03-28 15:32:21 +00:00
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 current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-format-inst-fn" > cljs< / a > < / 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 zone], :or {formatter java.time.format.DateTimeFormatter/ISO_INSTANT, zone java.time.ZoneOffset/UTC}})< / 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 current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-format-nsecs-fn" > cljs< / a > < / 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 current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-format-signal-fn" > cljs< / a > < / 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)
`:preamble-fn` - (fn [signal]) => signal preamble string.
`:content-fn` - (fn [signal]) => signal content string.
2024-05-05 11:13:03 +00:00
See also `pr-signal-fn` for machine-readable output.< / pre > < / div > < / div > < div class = "public anchor" id = "var-host-ip" > < h3 > host-ip< / h3 > < h4 class = "lang current" > clj< / h4 > < div class = "usage" > < code > (host-ip timeout-msecs timeout-val)< / code > < code > (host-ip)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns cached local host IP address string, or `timeout-val` (default "UnknownHost").
2024-03-28 15:32:21 +00:00
< / pre > < / div > < / div > < div class = "public anchor" id = "var-hostname" > < h3 > hostname< / h3 > < h4 class = "lang current" > clj< / h4 > < div class = "usage" > < code > (hostname timeout-msecs timeout-val)< / code > < code > (hostname)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns cached local hostname string, or `timeout-val` (default "UnknownHost").
2024-05-10 13:50:11 +00:00
< / pre > < / div > < / div > < div class = "public anchor" id = "var-newline" > < h3 > newline< / h3 > < h4 class = "lang current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-newline" > cljs< / a > < / 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 current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-pr-edn" > cljs< / a > < / 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-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 current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-pr-signal-fn" > cljs< / a > < / 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-05-10 13:50:11 +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-05-10 13:50:11 +00:00
`:incl-kvs?` - Include signal's user-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 :thread}
2024-05-05 11:13:03 +00:00
Examples:
2024-05-08 07:27:07 +00:00
(pr-signal-fn {:pr-fn :edn ...}) ; Outputs edn
(pr-signal-fn {:pr-fn :json ...}) ; Outputs JSON (Cljs only)
To output JSON for Clj, you must provide an appropriate `:pr-fn`.
2024-05-10 13:50:11 +00:00
`jsonista` offers one good option, Ref. < < a href = "https://github.com/metosin/jsonista" > https://github.com/metosin/jsonista< / a > > :
2024-05-05 11:13:03 +00:00
(require '[jsonista.core :as jsonista])
2024-05-08 07:27:07 +00:00
(pr-signal-fn {:pr-fn jsonista/write-value-as-string ...})
2024-05-05 11:13:03 +00:00
2024-05-10 13:50:11 +00:00
See also `format-signal-fn` for human-readable output.< / pre > < / div > < / div > < div class = "public anchor" id = "var-signal-content-fn" > < h3 > signal-content-fn< / h3 > < h4 class = "lang current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-signal-content-fn" > cljs< / a > < / 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
otherwise excluded by default: #{:kvs :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 current" > clj< / h4 > < h4 class = "lang" > < a href = "taoensso.telemere.utils.cljs.html#var-signal-preamble-fn" > cljs< / a > < / 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:
`:format-inst-fn` - (fn format [instant]) => string.< / pre > < / div > < / div > < div class = "public anchor" id = "var-tcp-socket-writer" > < h3 > tcp-socket-writer< / h3 > < h4 class = "lang current" > clj< / h4 > < div class = "usage" > < code > (tcp-socket-writer {:keys [host port ssl? connect-timeout-msecs socket-fn ssl-socket-fn], :as opts, :or {connect-timeout-msecs 3000, socket-fn default-socket-fn, ssl-socket-fn default-ssl-socket-fn}})< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Experimental, subject to change.
2024-05-05 11:13:03 +00:00
Connects to specified TCP socket and returns a stateful fn of 2 arities:
[content] => Writes given content to socket, or no-ops if closed.
[] => Closes the writer.
Useful for basic handlers that write to a TCP socket, etc.
Options:
`:ssl?` - Use SSL/TLS?
`:connect-timeout-msecs` - Connection timeout (default 3000 msecs)
`:socket-fn` - (fn [host port timeout]) => `java.net.Socket`
`:ssl-socket-fn` - (fn [socket host port]) => `java.net.Socket`
Notes:
- Writer should be manually closed after use (with zero-arity call).
- Flushes after every write.
- Will retry failed writes once, then drop.
- Thread safe, locks on single socket stream.
- Advanced users may want a custom implementation using a connection
pool and/or more sophisticated retry semantics, etc.< / pre > < / div > < / div > < div class = "public anchor" id = "var-thread-id" > < h3 > thread-id< / h3 > < h4 class = "lang current" > clj< / h4 > < div class = "usage" > < code > (thread-id)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns long id of current thread.
< / pre > < / div > < / div > < div class = "public anchor" id = "var-thread-info" > < h3 > thread-info< / h3 > < h4 class = "lang current" > clj< / h4 > < div class = "usage" > < code > (thread-info)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns {:keys [group name id]} for current thread.
2024-03-28 15:32:21 +00:00
< / pre > < / div > < / div > < div class = "public anchor" id = "var-thread-name" > < h3 > thread-name< / h3 > < h4 class = "lang current" > clj< / h4 > < div class = "usage" > < code > (thread-name)< / code > < / div > < div class = "doc" > < pre class = "plaintext" > Returns string name of current thread.
< / pre > < / div > < / div > < / div > < / body > < / html >
