Liking cljdoc? Tell your friends :D
Mostly clj/s.
Exceptions indicated.

taoensso.telemere

Structured telemetry for Clojure/Script applications.

See the GitHub page (esp. Wiki) for info on motivation and design:
  <https://www.taoensso.com/telemere>

*ctx*clj/s

Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
Value may be any type, but is usually nil or a map.

Re/bind dynamic     value using `with-ctx`, `with-ctx+`, or `binding`.
Modify  root (base) value using `set-ctx!`.
Default root (base) value is    `default-ctx`.

Note that as with all dynamic Clojure vars, "binding conveyance" applies
when using futures, agents, etc.

Tips:
  - Value may be (or may contain) an atom if you want mutable semantics
  - Value may be of form {<scope-id> <data>} for custom scoping, etc.
source

*middleware*clj/s

Optional vector of unary middleware fns to apply (sequentially/left-to-right)
to each signal before passing it to handlers. If any middleware fn returns nil,
aborts immediately without calling handlers.

Useful for transforming each signal before handling.

Re/bind dynamic     value using `with-middleware`, `binding`.
Modify  root (base) value using `set-middleware!`.
source

add-handler!clj/s

(add-handler! handler-id handler-fn)
(add-handler! handler-id handler-fn dispatch-opts)
Registers given signal handler and returns
{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers
now registered.

`handler-fn` should be a fn of 1-2 arities:

  ([handler-arg]) => Handle the given argument (e.g. write to disk/db, etc.)
  ([]) => Optional arity, called exactly once on system shutdown.
          Provides an opportunity for handler to close/release
          any resources that it may have opened/acquired.

See the relevant docstring/s for `handler-arg` details.

Handler ideas:

  Save to a db, `tap>`, log, `put!` to an appropriate `core.async`
  channel, filter, aggregate, use for a realtime analytics dashboard,
  examine for outliers or unexpected data, etc.

Dispatch options include:

  `async` (Clj only)
     Options for running handler asynchronously via `taoensso.encore/runner`,
     {:keys [mode buffer-size n-threads daemon-threads? ...]}

     Supports `:blocking`, `:dropping`, and `:sliding` back pressure modes.
     NB handling order may be non-sequential when `n-threads` > 1.

  `priority`
    Optional handler priority ∈ℤ (default 100). Handlers will be called in
    descending priority order.

  `sample-rate`
    Optional sample rate ∈ℝ[0,1], or (fn dyamic-sample-rate []) => ℝ[0,1].
    When present, handle only this (random) proportion of args:
      1.0 => handle every arg (same as `nil` rate, default)
      0.0 => noop   every arg
      0.5 => handle random 50% of args

  `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!`

  `when-fn`
    Optional nullary (fn allow? []) that must return truthy for handler to be
    called. When present, called *after* sampling and other filters, but before
    rate limiting.

  `rate-limit`
    Optional rate limit spec as provided to `taoensso.encore/rate-limiter`,
    {<limit-id> [<n-max-calls> <msecs-window>]}.

    Examples:
      {"1/sec"  [1   1000]} => Max 1  call  per 1000 msecs
      {"1/sec"  [1   1000]
       "10/min" [10 60000]} => Max 1  call  per 1000 msecs,
                               and 10 calls per 60   secs

  `middleware`
    Optional vector of unary middleware fns to apply (left-to-right/sequentially)
    to `handler-arg` before passing to `handler-fn`. If any middleware fn returns
    nil, aborts immediately without calling `handler-fn`.

    Useful for transforming `handler-arg` before handling.

  `error-fn` - (fn [{:keys [handler-id handler-arg error]}]) to call on handler error.
  `backp-fn` - (fn [{:keys [handler-id                  ]}]) to call on handler back pressure.

Flow sequence:

  1. Per call (n=1)
    a. Sampling
    b. Filtering (kind, namespace, id, level, when-form)
    c. Rate limiting
    d. Middleware

  2. Per handler (n>=0)
    a. Sampling
    b. Filtering (kind, namespace, id, level, when-fn)
    c. Rate limiting
    d. Middleware
    e. Hander fn

  Note: call filters should generally be at least as permissive as handler filters,
  otherwise calls will be suppressed before reaching handlers.
source

catch->error!clj/smacro

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

chanceclj/s≠

clj
(chance prob)
Returns true with given probability ∈ ℝ[0,1].
cljs
source

check-interopclj/s≠

clj
(check-interop)
Experimental, subject to change.
Runs Telemere's registered interop checks and returns
{<interop-id> {:keys [sending->telemere? telemere-receiving? ...]}}.

Useful for tests/debugging.
cljs
source

console-handler-fnclj/s≠

clj
(console-handler-fn)
(console-handler-fn {:keys [format-signal-fn stream]
                     :or {format-signal-fn (utils/format-signal->str-fn)}})
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.
cljs
source

default-ctxclj/s

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

error!clj/smacro

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

event!clj/smacro

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

get-envclj/smacro

(get-env {:keys [as default return spec] :or {as :str return :value}})
(get-env {:keys [as default return]} spec)
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.
source

get-filtersclj/s

(get-filters)
Returns current ?{:keys [compile-time runtime]} filter config.
source

get-handlersclj/s

(get-handlers)
Returns ?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all
registered signal handlers.
source

get-min-levelclj/s

(get-min-level)
(get-min-level kind)
(get-min-level kind ns)
Returns current ?{:keys [compile-time runtime]} minimum levels.
source

help:filtersclj/s

Your filter config determines which signal calls will be allowed.

Filtering can occur at compile-time (=> elision), or runtime.
Both compile-time and runtime config can be specified via:

  1. System values (JVM properties, environment variables, or
     classpath resources). See library docs for details.

  2. The filter API consting of the following:

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

Additional filtering can also be applied on a per-handler basis, see
`add-handler!` for details.

See also:

  `get-filters`     - to see current filter config
  `get-min-level`   - to see current minimum level
  `without-filters` - to disable all runtime filtering

If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
source

help:handlersclj/s

The handler API consists of the following:

  `get-handlers`    - Returns info on currently registered handlers
  `add-handler!`    - Used to   register handlers
  `remove-handler!` - Used to unregister handlers

See the relevant docstrings for details.

If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
source

help:signal-contentclj/s

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`
source

help:signal-handlingclj/s

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!
source

help:signal-optionsclj/s

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`
source

level-aliasesclj/s≠

clj
Map of {<level-keyword> <level-integer>} aliases.
source

log!clj/smacro

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

msg-skipclj/s≠

clj
For use within signal message vectors.
Special value that will be ignored (no-op) when creating message.
Useful for conditionally skipping parts of message content, etc.:

  (signal! {:msg ["Hello" (if <cond> <then> msg-skip) "world"] <...>}) or
  (log!          ["Hello" (if <cond> <then> msg-skip) "world"]), etc.

    %> {:msg_ "Hello world" <...>}
source

msg-spliceclj/s≠

clj
(msg-splice args)
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"}
cljs
source

newlineclj/s≠

clj
Single system newline
source

rate-limiterclj/s≠

clj
(rate-limiter spec)
(rate-limiter opts spec)
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>))
cljs
source

raw-console-handler-fncljs

source

remove-handler!clj/s

(remove-handler! handler-id)
Deregisters signal handler with given id, and returns
?{<handler-id> {:keys [dispatch-opts handler-fn]}} for all signal handlers
still registered.
source

set-ctx!clj/smacro

(set-ctx! root-val)
Set `*ctx*` var's root (base) value. See `*ctx*` for details.
source

set-id-filter!clj/s

(set-id-filter! id-filter)
Sets signal call id filter based on given `id-filter` spec.
`id-filter` may be:

  - A regex pattern of id/s to allow.
  - A str/kw/sym, in which "*"s act as wildcards.
  - A vector or set of regex patterns or strs/kws/syms.
  - {:allow <spec> :deny <spec>} with specs as above.
source

set-kind-filter!clj/s

(set-kind-filter! kind-filter)
Sets signal call kind filter based on given `kind-filter` spec.
`kind-filter` may be:

  - A regex pattern of kind/s to allow.
  - A str/kw/sym, in which "*"s act as wildcards.
  - A vector or set of regex patterns or strs/kws/syms.
  - {:allow <spec> :deny <spec>} with specs as above.
source

set-middleware!clj/smacro

(set-middleware! root-val)
Set `*middleware*` var's root (base) value. See `*middleware*` for details.
source

set-min-level!clj/s

(set-min-level! min-level)
(set-min-level! kind min-level)
(set-min-level! kind ns-filter min-level)
Sets minimum signal call level based on given `min-level` spec.
`min-level` may be:

  - An integer.
  - A level keyword (see `level-aliases` var for details).

If `ns-filter` is provided, then the given minimum level
will apply only for namespaces that match `ns-filter`.
See `set-ns-filter!` for details.

If non-nil `kind` is provided, then the given minimum level
will apply only for that signal kind.
source

set-ns-filter!clj/s

(set-ns-filter! ns-filter)
Sets signal call namespace filter based on given `ns-filter` spec.
`ns-filter` may be:

  - A regex pattern of namespace/s to allow.
  - A str/kw/sym, in which "*"s act as wildcards.
  - A vector or set of regex patterns or strs/kws/syms.
  - {:allow <spec> :deny <spec>} with specs as above.
source

set-var-root!clj/smacro

(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!`.
source

signal!clj/smacro

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

spy!clj/smacro

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

streams->reset!clj

(streams->reset!)
Experimental, subject to change without notice!
Resets `System/out` and `System/err` to their original value (prior to any
`streams->telemere!` call).
source

streams->telemere!clj

(streams->telemere!)
(streams->telemere! {:keys [out err]
                     :or {out default-out-opts err default-err-opts}})
Experimental, subject to change without notice!

When given `out`, sets JVM's `System/out` to flush to Telemere signals with those opts.
When given `err`, sets JVM's `System/err` to flush to Telemere signals with those opts.

Note that setting `System/out` won't necessarily affect Clojure's `*out*`,
and       setting `System/err` won't necessarily affect Clojure's `*err*`.

See also:
  `with-out->telemere`,
  `with-err->telemere`,
  `with-streams->telemere`.
source

tools-logging->telemere!clj

(tools-logging->telemere!)
Configures `clojure.tools.logging` to use Telemere as its logging implementation.
source

trace!clj/smacro

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

uncaught->error!clj/smacro

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

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!`.
source

update-var-root!clj/smacro

(update-var-root! var-sym update-fn)
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!`.
source

with-ctxclj/smacro

(with-ctx init-val form)
Evaluates given form with given `*ctx*` value. See `*ctx*` for details.
source

with-ctx+clj/smacro

(with-ctx+ update-map-or-fn form)
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.
source

with-err->telemereclj/smacro

(with-err->telemere form)
(with-err->telemere opts form)
Executes form with `*err*` bound to flush to Telemere signals with given opts.
source

with-handlerclj/smacro

(with-handler handler-id handler-fn dispatch-opts form)
Executes form with ONLY the given handler-fn registered.
Useful for tests/debugging. See also `with-handler+`.
source

with-handler+clj/smacro

(with-handler+ handler-id handler-fn dispatch-opts form)
Executes form with the given handler-fn registered.
Useful for tests/debugging. See also `with-handler`.
source

with-id-filterclj/smacro

(with-id-filter id-filter form)
Executes form with given signal call id filter in effect.
See `set-id-filter!` for details.
source

with-kind-filterclj/smacro

(with-kind-filter kind-filter form)
Executes form with given signal call kind filter in effect.
See `set-kind-filter!` for details.
source

with-middlewareclj/smacro

(with-middleware init-val form)
Evaluates given form with given `*middleware*` value.
See `*middleware*` for details.
source

with-min-levelclj/smacro

(with-min-level min-level form)
(with-min-level kind min-level form)
(with-min-level kind ns-filter min-level form)
Executes form with given minimum signal call level in effect.
See `set-min-level!` for details.
source

with-ns-filterclj/smacro

(with-ns-filter ns-filter form)
Executes form with given signal call namespace filter in effect.
See `set-ns-filter!` for details.
source

with-out->telemereclj/smacro

(with-out->telemere form)
(with-out->telemere opts form)
Executes form with `*out*` bound to flush to Telemere signals with given opts.
source

with-signalclj/smacro

(with-signal form)
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.
source

with-signalsclj/smacro

(with-signals form)
(with-signals {:keys [handle? trap-errors? force-msg?] :or {handle? true}} form)
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.
source

with-streams->telemereclj/smacro

(with-streams->telemere form)
(with-streams->telemere {:keys [out err]
                         :or {out default-out-opts err default-err-opts}}
                        form)
Executes form with `*out*` and/or `*err*` bound to flush to Telemere signals
with given opts.
source

without-filtersclj/smacro

(without-filters form)
Executes form without any runtime filters.
source

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcutsReport a problemcljdoc on GitHub
× close