taoensso.telemere.utils

Misc utils useful for Telemere handlers, middleware, etc.

error-in-signal->maps

clj

cljs

(error-in-signal->maps signal)
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.

error-signal?

clj

cljs

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

format-error-fn

clj

cljs

(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

cljs

added in Encore v3.98.0 (2024-04-08)

(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:
  `:zone` (Clj only) `java.time.ZoneOffset` (defaults to UTC).
  `:formatter`
    `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".

format-nsecs-fn

clj

cljs

(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

cljs

(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.
  `:content-fn`    - (fn [signal]) => signal content  string.

See also `pr-signal-fn` for machine-readable output.

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!

minify-signal

clj

cljs

(minify-signal signal)
Experimental, subject to change.
Returns minimal signal, removing:
  - Keys with nil values, and
  - Keys with redundant values (`:kvs`, `:location`, `:file`).

Useful when serializing signals to edn/JSON/etc.

newline

clj

cljs

added in Encore v3.68.0 (2023-09-25)

Single system newline

pr-edn

clj

cljs

(pr-edn x)
Prints given arg to an edn string readable with `read-edn`.

pr-json

cljs

added in Encore v3.98.0 (2024-04-08)

(pr-json x)
Returns given Cljs argument as JSON string.

pr-signal-fn

clj

cljs

(pr-signal-fn pr-fn)(pr-signal-fn pr-fn {:keys [incl-thread? incl-kvs? incl-newline? prep-fn], :or {incl-newline? true, prep-fn (comp error-in-signal->maps minify-signal)}})
Experimental, subject to change.
Returns a (fn pr [signal]) that:
  - Takes a Telemere signal (map).
  - Returns a machine-readable (minified) signal string.

Options:
  `pr-fn`          - ∈ #{<unary-fn> :edn :json (Cljs only)}
  `:incl-thread?`  - Include signal `:thread` info?      (default false)
  `:incl-kvs?`     - Include signal `:kvs`    info?      (default false)
  `:incl-newline?` - Include terminating system newline? (default true)

Examples:
  (pr-signal-fn :edn  {<opts>})
  (pr-signal-fn :json {<opts>}) ; Cljs only

  ;; To output JSON for Clj, you must provide an appropriate `pr-fn`.
  ;; `jsonista` is a good option, Ref. <https://github.com/metosin/jsonista>:
    (require '[jsonista.core :as jsonista])
    (pr-signal-fn jsonista/write-value-as-string {<opts>})

See also `format-signal-fn` for human-readable output.

remove-kvs

clj

cljs

(remove-kvs signal)
Returns given signal without user-level kvs.

signal-content-fn

clj

cljs

(signal-content-fn)(signal-content-fn {:keys [incl-thread? incl-kvs? raw-error? 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:
  `:incl-thread?`    - Include signal `:thread` info? (default false)
  `:incl-kvs?`       - Include signal `:kvs`    info? (default false)
  `:raw-error?`      - Retain unformatted error?      (default false)
  `:format-nsecs-fn` - (fn [nanosecs]) => string.
  `:format-error-fn` - (fn [error])    => string.

signal-preamble-fn

clj

cljs

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