\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index 047e6cc..dd57323 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,4 +1,4 @@
-Telemere 1.0.0-beta3
\ No newline at end of file
diff --git a/index.html b/index.html
index f2c6a5c..1cdb3b9 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-beta3
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index 3578b37..54bdc49 100644
--- a/taoensso.telemere.cljs.html
+++ b/taoensso.telemere.cljs.html
@@ -1,6 +1,6 @@
-taoensso.telemere documentation
Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
<https://www.taoensso.com/telemere>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -53,6 +53,9 @@ Dispatch options include:
Default:
{:mode :dropping, :buffer-size 1024, :n-threads 1, :daemon-threads? true}
+ I.e. async by default, with a buffer of size 1024 that drops new entries
+ when full.
+
Options:
`mode` - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}.
`buffer-size` - Size of buffer before back-pressure mechanism is engaged.
@@ -225,14 +228,14 @@ Tips:
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
-[4] See `help:signal-flow` - (filters, handling, etc.)
Flexible cross-platform util for embedding a config value 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")
+ - JVM property value for id
+ - Environment variable value for id
+ - Classpath resource content for id
Ids may include optional segment in `<>` tag (e.g. `<.edn>`).
Ids may include `<.?platform.?>` tag for auto replacement, useful
@@ -240,25 +243,25 @@ 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])
+So (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)
+ 1. Alt1 +platform +optional (.edn suffix)
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)
+ 2. Alt1 +platform -optional (.edn suffix)
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)
+ 3. Alt1 -platform +optional (.edn suffix)
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)
+ 4. Alt1 -platform -optional (.edn suffix)
4a. `my-app.alt1` JVM property value
4b. `MY_APP_ALT1` environment variable value
4c. `my-app.alt1` classpath resource content
@@ -269,23 +272,28 @@ will parse and return the first of the following that exists:
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!
+ `:as` - Parse found value as given type ∈ #{:str :bool :edn} (default `:str`).
+ `:default` - Fallback to return unparsed if no value found during search (default `nil`).
+ `:return` - Return type ∈ #{:value :map :explain} (default `:value`).
-Result must be something that can be safely embedded in code during
-macro-expansion. Symbols in edn will be evaluated during expansion.
Returns current ?{:keys [compile-time runtime]} filter config.
+Resulting config value must be something that can be safely embedded in code during
+macro-expansion. Symbols in edn will be evaluated during expansion.
+
+TIP!: Use the {:return :explain} option in tests or at the REPL to verify/inspect
+resulting config value, config source, and specific search order of prop/env/res ids.
Experimental, subject to change. Feedback welcome!
If `js/console` exists, returns a (fn handler [signal]) that:
- Takes a Telemere signal.
- Writes a formatted signal string to JavaScript console.
+A general-purpose `println`-style handler that's well suited for outputting
+signals formatted as edn, JSON, or human-readable strings.
+
Options:
- `:format-signal-fn` - (fn [signal]) => output, see `help:signal-formatters`
Experimental, subject to change. Feedback welcome!
If `js/console` exists, returns a (fn handler [signal]) that:
- Takes a Telemere signal.
@@ -294,11 +302,13 @@ If `js/console` exists, returns a (fn handler [signal]) that:
Intended for use with browser formatting tools like `binaryage/devtools`,
Ref. <https://github.com/binaryage/cljs-devtools>.
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 with:
+Filtering can occur at compile-time, runtime, or both.
+Compile-time filtering elides (permanently removes!) code for
+disallowed signals. Most users will want only runtime filtering.
- System values (JVM properties, environment variables, or
- classpath resources) [1].
+Both compile-time and runtime config can be specified via
+environmental config (JVM properties, environment variables, or
+classpath resources) [1].
Runtime config can also be specified with:
@@ -320,21 +330,7 @@ See also:
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
-[1] These include:
-
- Compile-time:
-
- ns-filter: (get-env {:as :edn} :taoensso.telemere/ct-ns-filter<.platform><.edn>)
- id-filter: (get-env {:as :edn} :taoensso.telemere/ct-id-filter<.platform><.edn>)
- min-level: (get-env {:as :edn} :taoensso.telemere/ct-min-level<.platform><.edn>)
-
- Runtime:
-
- ns-filter: (get-env {:as :edn} :taoensso.telemere/rt-ns-filter<.platform><.edn>)
- id-filter: (get-env {:as :edn} :taoensso.telemere/rt-id-filter<.platform><.edn>)
- min-level: (get-env {:as :edn, :default :info} :taoensso.telemere/rt-min-level<.platform><.edn>)
-
- See `get-env` for details.
Manage handlers with:
`get-handlers` - Returns info on registered handlers
`shut-down-handlers!` - Shuts down registered handlers
@@ -376,7 +372,9 @@ Default signal keys:
`:file` -------- ?str filename of signal creator callsite, same as (:file location)
`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
-<kvs> ---------- Arb other user-level ?kvs given to signal creator
+<kvs> ---------- Other arb user-level ?kvs given to signal creator. Typically NOT included
+ in handler output, so a great way to provide custom data/opts for use
+ (only) by custom middleware/handlers.
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
@@ -413,6 +411,7 @@ and return values), making them more/less convenient for certain use cases:
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)
A signal will be provided to a handler iff ALL of the following are true:
+
1. Signal (creation) is allowed by compile-time filters
2. Signal (creation) is allowed by runtime filters
3. Signal (handling) is allowed by handler filters
@@ -421,18 +420,40 @@ and return values), making them more/less convenient for certain use cases:
5. Handler middleware does not suppress the signal (return nil)
For 1-3, filtering may depend on (in order):
+
Sample rate → namespace → kind → id → level → when form/fn → rate limit
-Note that sample rates are multiplicative:
- If a signal is created with 20% sampling and a handler handles 50%
- of given signals, then 10% of possible signals will be handled.
+Compile-time vs runtime filtering:
- This multiplicative rate is helpfully reflected in each signal's final
+ Compile-time filtering is an advanced feature that can be tricky to set
+ and use correctly. Most folks will want ONLY runtime filtering.
+
+ Compile-time filtering works by eliding (completely removing the code for)
+ disallowed signals. This means zero performance cost for these signals,
+ but also means that compile-time filtering is PERMANENT once applied.
+
+ So if you set `:info` as the compile-time minimum level, that'll REMOVE
+ CODE for every signal call below `:info` level. To decrease that minimum
+ level, you'll need to rebuild.
+
+ Compile-time filtering can be set ONLY with environmental config
+ (JVM properties, environment variables, or classpath resources).
+
+Signal and handler sampling is multiplicative:
+
+ Both signals and handlers can have independent sample rates, and these
+ MULTIPLY!
+
+ If a signal is created with 20% sampling and a handler handles 50%
+ of received signals, then 10% of possible signals will be handled
+ (50% of 20%).
+
+ The multiplicative rate is helpfully reflected in each signal's final
`:sample-rate` value.
-For a visual flowchart, see: Ref. <https://www.taoensso.com/telemere/flow>
-
For more info:
+
+ - Signal visual flowchart, Ref. <https://www.taoensso.com/telemere/flow>
- On signal filters, see: `help:signal-filters` docstring
- On handler filters, see: `help:signal-handlers` docstring
@@ -462,14 +483,18 @@ See relevant docstrings for details.
Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
<https://www.taoensso.com/telemere>
Dynamic context: arbitrary user-level state attached as `:ctx` to all signals.
@@ -53,6 +53,9 @@ Dispatch options include:
Default:
{:mode :dropping, :buffer-size 1024, :n-threads 1, :daemon-threads? true}
+ I.e. async by default, with a buffer of size 1024 that drops new entries
+ when full.
+
Options:
`mode` - Mode of operation, ∈ #{:sync :blocking :dropping :sliding}.
`buffer-size` - Size of buffer before back-pressure mechanism is engaged.
@@ -229,14 +232,14 @@ Tips:
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
-[4] See `help:signal-flow` - (filters, handling, etc.)
Flexible cross-platform util for embedding a config value 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")
+ - JVM property value for id
+ - Environment variable value for id
+ - Classpath resource content for id
Ids may include optional segment in `<>` tag (e.g. `<.edn>`).
Ids may include `<.?platform.?>` tag for auto replacement, useful
@@ -244,25 +247,25 @@ 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])
+So (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)
+ 1. Alt1 +platform +optional (.edn suffix)
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)
+ 2. Alt1 +platform -optional (.edn suffix)
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)
+ 3. Alt1 -platform +optional (.edn suffix)
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)
+ 4. Alt1 -platform -optional (.edn suffix)
4a. `my-app.alt1` JVM property value
4b. `MY_APP_ALT1` environment variable value
4c. `my-app.alt1` classpath resource content
@@ -273,26 +276,31 @@ will parse and return the first of the following that exists:
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!
+ `:as` - Parse found value as given type ∈ #{:str :bool :edn} (default `:str`).
+ `:default` - Fallback to return unparsed if no value found during search (default `nil`).
+ `:return` - Return type ∈ #{:value :map :explain} (default `:value`).
-Result must be something that can be safely embedded in code during
-macro-expansion. Symbols in edn will be evaluated during expansion.
Returns current ?{:keys [compile-time runtime]} filter config.
+Resulting config value must be something that can be safely embedded in code during
+macro-expansion. Symbols in edn will be evaluated during expansion.
+
+TIP!: Use the {:return :explain} option in tests or at the REPL to verify/inspect
+resulting config value, config source, and specific search order of prop/env/res ids.
Experimental, subject to change. Feedback welcome!
Returns a (fn handler [signal]) that:
- Takes a Telemere signal.
- Writes a formatted signal string to stream.
+A general-purpose `println`-style handler that's well suited for outputting
+signals formatted as edn, JSON, or human-readable strings.
+
Options:
`:format-signal-fn` - (fn [signal]) => output, see `help:signal-formatters`
`:stream` - `java.io.writer`
- Defaults to `*err*` if `utils/error-signal?` is true, and `*out*` otherwise.
Experimental, subject to change. Feedback welcome!
Returns a (fn handler [signal]) that:
- Takes a Telemere signal.
@@ -324,11 +332,13 @@ Options:
`:max-num-intervals` ∈ #{nil <pos-int>} (default 6)
Maximum number of intervals (days/weeks/months) to retain.
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 with:
+Filtering can occur at compile-time, runtime, or both.
+Compile-time filtering elides (permanently removes!) code for
+disallowed signals. Most users will want only runtime filtering.
- System values (JVM properties, environment variables, or
- classpath resources) [1].
+Both compile-time and runtime config can be specified via
+environmental config (JVM properties, environment variables, or
+classpath resources) [1].
Runtime config can also be specified with:
@@ -350,21 +360,7 @@ See also:
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
-[1] These include:
-
- Compile-time:
-
- ns-filter: (get-env {:as :edn} :taoensso.telemere/ct-ns-filter<.platform><.edn>)
- id-filter: (get-env {:as :edn} :taoensso.telemere/ct-id-filter<.platform><.edn>)
- min-level: (get-env {:as :edn} :taoensso.telemere/ct-min-level<.platform><.edn>)
-
- Runtime:
-
- ns-filter: (get-env {:as :edn} :taoensso.telemere/rt-ns-filter<.platform><.edn>)
- id-filter: (get-env {:as :edn} :taoensso.telemere/rt-id-filter<.platform><.edn>)
- min-level: (get-env {:as :edn, :default :info} :taoensso.telemere/rt-min-level<.platform><.edn>)
-
- See `get-env` for details.
Manage handlers with:
`get-handlers` - Returns info on registered handlers
`shut-down-handlers!` - Shuts down registered handlers
@@ -406,7 +402,9 @@ Default signal keys:
`:file` -------- ?str filename of signal creator callsite, same as (:file location)
`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
-<kvs> ---------- Arb other user-level ?kvs given to signal creator
+<kvs> ---------- Other arb user-level ?kvs given to signal creator. Typically NOT included
+ in handler output, so a great way to provide custom data/opts for use
+ (only) by custom middleware/handlers.
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
@@ -444,11 +442,13 @@ and return values), making them more/less convenient for certain use cases:
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-flow` - (filters, handling, etc.)
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 with:
+Filtering can occur at compile-time, runtime, or both.
+Compile-time filtering elides (permanently removes!) code for
+disallowed signals. Most users will want only runtime filtering.
- System values (JVM properties, environment variables, or
- classpath resources) [1].
+Both compile-time and runtime config can be specified via
+environmental config (JVM properties, environment variables, or
+classpath resources) [1].
Runtime config can also be specified with:
@@ -470,21 +470,8 @@ See also:
If anything is unclear, please ping me (@ptaoussanis) so that I can
improve these docs!
-[1] These include:
+[1] (impl/signal-docstring :filter-env-config)
A signal will be provided to a handler iff ALL of the following are true:
1. Signal (creation) is allowed by compile-time filters
2. Signal (creation) is allowed by runtime filters
3. Signal (handling) is allowed by handler filters
@@ -493,18 +480,40 @@ improve these docs!
5. Handler middleware does not suppress the signal (return nil)
For 1-3, filtering may depend on (in order):
+
Sample rate → namespace → kind → id → level → when form/fn → rate limit
-Note that sample rates are multiplicative:
- If a signal is created with 20% sampling and a handler handles 50%
- of given signals, then 10% of possible signals will be handled.
+Compile-time vs runtime filtering:
- This multiplicative rate is helpfully reflected in each signal's final
+ Compile-time filtering is an advanced feature that can be tricky to set
+ and use correctly. Most folks will want ONLY runtime filtering.
+
+ Compile-time filtering works by eliding (completely removing the code for)
+ disallowed signals. This means zero performance cost for these signals,
+ but also means that compile-time filtering is PERMANENT once applied.
+
+ So if you set `:info` as the compile-time minimum level, that'll REMOVE
+ CODE for every signal call below `:info` level. To decrease that minimum
+ level, you'll need to rebuild.
+
+ Compile-time filtering can be set ONLY with environmental config
+ (JVM properties, environment variables, or classpath resources).
+
+Signal and handler sampling is multiplicative:
+
+ Both signals and handlers can have independent sample rates, and these
+ MULTIPLY!
+
+ If a signal is created with 20% sampling and a handler handles 50%
+ of received signals, then 10% of possible signals will be handled
+ (50% of 20%).
+
+ The multiplicative rate is helpfully reflected in each signal's final
`:sample-rate` value.
-For a visual flowchart, see: Ref. <https://www.taoensso.com/telemere/flow>
-
For more info:
+
+ - Signal visual flowchart, Ref. <https://www.taoensso.com/telemere/flow>
- On signal filters, see: `help:signal-filters` docstring
- On handler filters, see: `help:signal-handlers` docstring
@@ -546,14 +555,18 @@ improve these docs!
Shuts down all registered signal handlers in parallel, and returns
?{<handler-id> {:keys [okay error]}}.
Future calls to handlers will no-op.
@@ -757,9 +770,9 @@ Tips:
[1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...)
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
-[4] See `help:signal-flow` - (filters, handling, etc.)
streams->reset!
clj
(streams->reset!)
Experimental, subject to change without notice!
+[4] See `help:signal-flow` - (filters, handling, etc.)
streams->reset!
clj
(streams->reset!)
Experimental, subject to change.
Resets `System/out` and `System/err` to their original value (prior to any
-`streams->telemere!` call).
Experimental, subject to change.
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.
diff --git a/taoensso.telemere.open-telemetry.html b/taoensso.telemere.open-telemetry.html
index 716588e..b6bae48 100644
--- a/taoensso.telemere.open-telemetry.html
+++ b/taoensso.telemere.open-telemetry.html
@@ -1,14 +1,23 @@
-taoensso.telemere.open-telemetry documentation
Experimental, subject to change!! Feedback very welcome!
Returns `io.opentelemetry.api.logs.LoggerProvider` via:
`AutoConfiguredOpenTelemetrySdk` when possible, or
- `GlobalOpenTelemetry` otherwise.
Experimental, subject to change. Feedback welcome!
+
+Needs `opentelemetry-java`,
+ Ref. <https://github.com/open-telemetry/opentelemetry-java>.
Returns a (fn handler [signal]) that:
- Takes a Telemere signal.
- Emits signal content to the `io.opentelemetry.api.logs.Logger`
- returned by given `io.opentelemetry.api.logs.LoggerProvider`.
IAttr+
protocol
clj
\ No newline at end of file
+ returned by given `io.opentelemetry.api.logs.LoggerProvider`.
+
+Options:
+ `:logger-provider` - `io.opentelemetry.api.logs.LoggerProvider`
+ Defaults to the LoggerProvider returned by (default-logger-provider),
+ see that docstring for details.
IAttr+
protocol
clj
\ No newline at end of file
diff --git a/taoensso.telemere.postal.html b/taoensso.telemere.postal.html
new file mode 100644
index 0000000..695bdcf
--- /dev/null
+++ b/taoensso.telemere.postal.html
@@ -0,0 +1,61 @@
+
+taoensso.telemere.postal documentation
Experimental, subject to change. Feedback welcome!
+
+Needs `postal`,
+ Ref. <https://github.com/drewr/postal>.
+
+Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Sends an email with formatted signal content to the configured recipient.
+
+Useful for emailing important alerts to admins, etc.
+
+NB can incur financial costs!!
+See tips section re: protecting against unexpected costs.
+
+Options:
+
+ `:postal/conn-opts` - Map of connection opts provided to `postal`
+ Examples:
+ {:host "mail.isp.net", :user "jsmith", :pass "a-secret"},
+ {:host "smtp.gmail.com", :user "jsmith@gmail.com", :pass "a-secret" :port 587 :tls true},
+ {:host "email-smtp.us-east-1.amazonaws.com", :port 587, :tls true
+ :user "AKIAIDTP........" :pass "AikCFhx1P......."}
+
+ `:postal/msg-opts` - Map of message options
+ Examples:
+ {:from "foo@example.com", :to "bar@example.com"},
+ {:from "Alice <foo@example.com", :to "Bob <bar@example.com>"},
+ {:from "no-reply@example.com", :to ["first-responders@example.com",
+ "devops@example.com"],
+ :cc "engineering@example.com"
+ :X-MyHeader "A custom header"}
+
+ `:format-signal-fn` - (fn [signal]) => output, see `help:signal-formatters`
+ `:format-signal->subject-fn` - (fn [signal]) => email subject string
+
+Tips:
+
+ - Sending emails can incur financial costs!
+ Use appropriate dispatch filtering options when calling `add-handler!` to prevent
+ handler from sending unnecessary emails!
+
+ At least ALWAYS set an appropriate `:rate-limit` option, e.g.:
+ (add-handler! :my-postal-handler (handler:postal {<my-handler-opts})
+ {:rate-limit {"Max 1 per min" [1 (enc/msecs :mins 1)]
+ "Max 3 per 15 mins" [3 (enc/msecs :mins 15)]
+ "Max 5 per hour" [5 (enc/msecs :hours 1)]}, ...}), etc.
+
+ - Sending emails is slow!
+ Use appropriate async dispatch options when calling `add-handler!` to prevent
+ handler from blocking signal creator calls, e.g.:
+ (add-handler! :my-postal-handler (handler:postal {<my-handler-opts>})
+ {:async {:mode :dropping, :buffer-size 128, :n-threads 4} ...}), etc.
+
+ - Ref. <https://github.com/drewr/postal> for more info on `postal` options.
\ No newline at end of file
diff --git a/taoensso.telemere.streams.html b/taoensso.telemere.streams.html
index a620364..1c78ac4 100644
--- a/taoensso.telemere.streams.html
+++ b/taoensso.telemere.streams.html
@@ -1,11 +1,11 @@
-taoensso.telemere.streams documentation
Experimental, subject to change.
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.
diff --git a/taoensso.telemere.timbre.cljs.html b/taoensso.telemere.timbre.cljs.html
index c97a896..fcb192d 100644
--- a/taoensso.telemere.timbre.cljs.html
+++ b/taoensso.telemere.timbre.cljs.html
@@ -1,6 +1,6 @@
-taoensso.telemere.timbre documentation
\ No newline at end of file
diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html
index f638cd8..d6a9d8a 100644
--- a/taoensso.telemere.timbre.html
+++ b/taoensso.telemere.timbre.html
@@ -1,6 +1,6 @@
-taoensso.telemere.timbre documentation
Configures `clojure.tools.logging` to use Telemere as its logging implementation.
-Called automatically if the following is true:
- (get-env {:as :bool} :clojure.tools.logging/to-telemere)
-
-See `get-env` for details.
tools-logging->telemere?
clj
(tools-logging->telemere?)
Returns true iff `clojure.tools.logging` is configured to use Telemere
+Called automatically if one of the following is "true":
+ JVM property: `clojure.tools.logging.to-telemere`
+ Env variable: `CLOJURE_TOOLS_LOGGING_TO_TELEMERE`
+ Classpath resource: `clojure.tools.logging.to-telemere`
tools-logging->telemere?
clj
(tools-logging->telemere?)
Returns true iff `clojure.tools.logging` is configured to use Telemere
as its logging implementation.
\ No newline at end of file
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
index 1f00fc1..b8bc53b 100644
--- a/taoensso.telemere.utils.cljs.html
+++ b/taoensso.telemere.utils.cljs.html
@@ -1,6 +1,6 @@
-taoensso.telemere.utils documentation
Experimental, subject to change.
Returns given signal with possible `:error` replaced by
[{:keys [type msg data]} ...] cause chain.
@@ -35,14 +35,14 @@ Returns a (fn format->json [signal]) that:
- Takes a Telemere signal.
- Returns JSON string of the (minified) signal.
-(Clj only): An appropriate `:pr-json-fn` MUST be provided.
Experimental, subject to change.
-Returns a (fn format->str [signal]) that:
- - Takes a Telemere signal.
- - Returns a formatted string intended for text consoles, etc.
Experimental, subject to change.
+Returns a (fn format->str [signal]) that:
+ - Takes a Telemere signal.
+ - Returns a formatted string intended for text consoles, etc.
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.
@@ -55,4 +55,5 @@ Returns minimal signal map, removing:
Useful when serializing signals to edn/JSON/etc.
\ No newline at end of file
diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html
index 6ca2377..1c227f4 100644
--- a/taoensso.telemere.utils.html
+++ b/taoensso.telemere.utils.html
@@ -1,22 +1,25 @@
-taoensso.telemere.utils documentation
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.
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 file append?)
Experimental, subject to change!!
+that indicates that it's an error.
file-writer
clj
(file-writer file append?)
Experimental, subject to change. Feedback welcome!
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.
-Thread safe. Automatically creates file and parent dirs as necessary.
-Writers MUST ALWAYS be manually closed after use!
+Useful for basic handlers that write to a file, etc.
-Useful for handlers that write to files, etc.
Experimental, subject to change.
+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.
Experimental, subject to change.
Returns a (fn format [error]) that:
- Takes a platform error (`Throwable` or `js/Error`).
- Returns a formatted human-readable string
(format-inst-fn)(format-inst-fn {:keys [formatter zone], :or {formatter java.time.format.DateTimeFormatter/ISO_INSTANT, zone java.time.ZoneOffset/UTC}})
Experimental, subject to change without notice.
@@ -44,14 +47,14 @@ Returns a (fn format->json [signal]) that:
- Takes a Telemere signal.
- Returns JSON string of the (minified) signal.
-(Clj only): An appropriate `:pr-json-fn` MUST be provided.
Experimental, subject to change.
-Returns a (fn format->str [signal]) that:
- - Takes a Telemere signal.
- - Returns a formatted string intended for text consoles, etc.
Experimental, subject to change.
Returns a (fn format [signal]) that:
- Takes a Telemere signal.
- Returns a formatted prelude string like:
- "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"
host-ip
clj
(host-ip timeout-msecs timeout-val)(host-ip)
Returns cached local host IP address string, or `timeout-val` (default "UnknownHost").
+ "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"
Experimental, subject to change.
+Returns a (fn format->str [signal]) that:
+ - Takes a Telemere signal.
+ - Returns a formatted string intended for text consoles, etc.
host-ip
clj
(host-ip timeout-msecs timeout-val)(host-ip)
Returns cached local host IP address string, or `timeout-val` (default "UnknownHost").
hostname
clj
(hostname timeout-msecs timeout-val)(hostname)
Returns cached local hostname string, or `timeout-val` (default "UnknownHost").
Experimental, subject to change.
Returns minimal signal map, removing:
@@ -60,6 +63,7 @@ Returns minimal signal map, removing:
Useful when serializing signals to edn/JSON/etc.