taoensso.telemere.utils — com.taoensso/telemere 1.0.0-alpha7

Misc utils useful for Telemere handlers, middleware, etc.

clean-signal-fn clj/s

(clean-signal-fn)

(clean-signal-fn {:keys [incl-kvs? incl-nils? incl-keys] :as opts})

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}

error-signal? clj/s

(error-signal? signal)

Experimental, subject to change. Returns true iff given signal has an :error value, or a :kind or :level that indicates that it's an error.

file-writer clj

(file-writer {:keys [file append?] :or {append? true}})

Experimental, subject to change. Opens the specified file and returns a stateful fn of 2 arities: [content] => Writes given content to file, or noops if closed. [] => Closes the writer.

Useful for basic handlers that write to a file, etc.

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.

format-error-fn clj/s

(format-error-fn)

(format-error-fn {:as _opts})

Experimental, subject to change. Returns a (fn format [error]) that:

• Takes a platform error (Throwable or js/Error).
• Returns a human-readable error string.

format-inst-fn clj/s≠

clj

(format-inst-fn)

(format-inst-fn {:keys [formatter zone]
                 :or {formatter java.time.format.DateTimeFormatter/ISO_INSTANT
                      zone java.time.ZoneOffset/UTC}})

cljs

(format-inst-fn)

(format-inst-fn {:keys [formatter]})

Experimental, subject to change without notice.

Returns a (fn format [instant]) that:

• Takes a platform instant (java.time.Instant or js/Date).
• Returns a formatted human-readable instant string.

Options: :formatter Clj: java.time.format.DateTimeFormatter Cljs: goog.i18n.DateTimeFormat

Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`),
e.g.: "2011-12-03T10:15:130Z".

:zone (Clj only) java.time.ZoneOffset (defaults to UTC). Note that zone may be ignored by some DateTimeFormatters, including the default (DateTimeFormatter/ISO_INSTANT)!

format-nsecs-fn clj/s

(format-nsecs-fn)

(format-nsecs-fn {:as _opts})

Experimental, subject to change. Returns a (fn format [nanosecs]) that:

• Takes a long nanoseconds (e.g. runtime).
• Returns a human-readable string like: "1.00m", "4.20s", "340ms", "822μs", etc.

format-signal-fn clj/s

(format-signal-fn)

(format-signal-fn {:keys [incl-newline? preamble-fn content-fn]
                   :or {incl-newline? true
                        preamble-fn (signal-preamble-fn)
                        content-fn (signal-content-fn)}})

Experimental, subject to change. Returns a (fn format [signal]) that:

• 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, 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.).

hex-uid-fn clj/s

(hex-uid-fn)

(hex-uid-fn {:keys [secure? root-len child-len] :or {root-len 32 child-len 16}})

Experimental, subject to change. 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

host-info clj

(host-info)

(host-info fallback-val)

(host-info timeout-msecs fallback-val)

(host-info cache-msecs timeout-msecs fallback-val)

Returns ?{:keys [ip name]} with string vals or fallback-val (default nil). Arities 0 and 3 are cached, prefer these! Arities 1 and 2 are uncached and intended for advanced users only.

host-ip clj

(host-ip)

(host-ip fallback-val)

(host-ip timeout-msecs fallback-val)

(host-ip cache-msecs timeout-msecs fallback-val)

Returns local host IP string or fallback-val (default nil). Arities 0 and 3 are cached, prefer these! Arities 1 and 2 are uncached and intended for advanced users only.

hostname clj

(hostname)

(hostname fallback-val)

(hostname timeout-msecs fallback-val)

(hostname cache-msecs timeout-msecs fallback-val)

Returns local hostname string or fallback-val (default nil). Arities 0 and 3 are cached, prefer these! Arities 1 and 2 are uncached and intended for advanced users only.

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 constructors should check first!

nano-uid-fn clj/s

(nano-uid-fn)

(nano-uid-fn {:keys [secure? root-len child-len]
              :or {root-len 21 child-len 10}})

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

newline clj/s

Single system newline

pr-edn clj/s

(pr-edn x)

Prints given arg to an edn string readable with read-edn.

pr-json cljs

(pr-json x)

Returns given Cljs argument as JSON string.

pr-signal-fn clj/s

(pr-signal-fn)

(pr-signal-fn {:keys [pr-fn clean-fn incl-newline?]
               :as opts
               :or {pr-fn :edn clean-fn (clean-signal-fn) incl-newline? true}})

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)} :clean-fn - (fn [signal]) => clean signal map, see [1] :incl-newline? - Include terminating system newline? (default true)

Examples:

;; To print as edn: (pr-signal-fn {:pr-fn :edn})

;; To print as JSON: ;; Ref. https://github.com/metosin/jsonista (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)})

[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.

signal-content-fn clj/s

(signal-content-fn)

(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)}})

Experimental, subject to change. Returns a (fn content [signal]) that:

• Takes a Telemere signal (map).
• Returns a signal content ?string (incl. data, ctx, etc.).

Options: :raw-error? - Retain unformatted error? (default false) :incl-keys - Subset of signal keys to retain from those otherwise excluded by default: #{:kvs :host :thread} :format-nsecs-fn - (fn [nanosecs]) => string. :format-error-fn - (fn [error]) => string.

signal-preamble-fn clj/s

(signal-preamble-fn)

(signal-preamble-fn {:keys [format-inst-fn]
                     :or {format-inst-fn (format-inst-fn)}})

Experimental, subject to change. Returns a (fn preamble [signal]) that:

• Takes a Telemere signal (map).
• Returns a signal preamble ?string like: "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"

Options: :format-inst-fn - (fn format [instant]) => string.

tcp-socket-writer clj

(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}})

Experimental, subject to change. Connects to specified TCP socket and returns a stateful fn of 2 arities: [content] => Writes given content to socket, or noops 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.

thread-id clj

(thread-id)

Returns long id of current Thread.

thread-info clj

(thread-info)

Returns {:keys [group name id]} for current Thread.

thread-name clj

(thread-name)

Returns string name of current Thread.

uuid clj

(uuid)

For Clj: returns a random java.util.UUID. For Cljs: returns a random UUID string.

Uses strong randomness when possible. See also uuid-str, nanoid, rand-id-fn.

uuid-str clj/s

(uuid-str)

(uuid-str max-len)

Returns a random UUID string of given length (max 36). Uses strong randomness when possible. See also uuid, nanoid, rand-id-fn.