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.

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

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

  `ns-filter`   - Namespace filter as in `set-ns-filter!`
  `kind-filter` - Kind      filter as in `set-kind-filter!` (when relevant)
  `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.

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.

TODO Docstring

TODO Docstring

Returns current ?{:keys [compile-time runtime]} filter config.

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

Returns current ?{:keys [compile-time runtime]} minimum levels.

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-ns-filter!`,     `with-ns-filter`      - for filtering calls by namespace
    `set-minimum-level!`, `with-minimum-level!` - for filtering calls by signal level
    `set-id-filter!`,     `with-id-filter`      - for filtering calls by signal id   (when relevant)
    `set-kind-filter!`,   `with-kind-filter`    - for filtering calls by signal kind (when relevant)

    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!

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!

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

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.

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.

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.

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.

Executes form with ONLY the given handler-fn registered.
Useful for tests/debugging. See also `with-handler+`.

Executes form with the given handler-fn registered.
Useful for tests/debugging. See also `with-handler`.

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

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

Executes form with given minimum signal call level in effect.
See `set-min-level!` for details.

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

Executes form without any runtime filters.