\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index 7ef2b15..68f4d8c 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,4 +1,4 @@
-Telemere 1.0.0-beta19
\ No newline at end of file
diff --git a/index.html b/index.html
index 2949f2a..bd57d51 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-beta19
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index fa4670c..14da6da 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>
Optional context (state) attached to all signals.
@@ -35,6 +35,9 @@ Tips:
(fn [root?]) used to generate signal `:uid` values when tracing.
These are basically unique signal instance identifiers.
+Relevant only when `otel-tracing?` is false.
+If `otel-tracing?` is true, uids are instead generated by `*otel-tracer*`.
+
`root?` argument is true iff signal is a top-level trace (i.e. form
being traced is unnested = has no parent form).
@@ -533,8 +536,8 @@ See the relevant docstrings for details.
See `help:handler-dispatch-options` for handler filters, etc.
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
Signals are maps with {:keys [inst id ns level data msg_ ...]}, though they
+can be modified by signal and/or handler middleware.
Default signal keys:
@@ -639,8 +642,6 @@ and return values), making them more/less convenient for certain use cases:
handler output, so a great way to provide custom data/opts for use
(only) by custom middleware/handlers.
-handler-specific data that can just be ignored by other handlers
-
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
[1] `java.time.Instant` or `js/Date`
@@ -698,7 +699,7 @@ Options:
`:incl-nils?` - Include signal's keys with nil values? (default false)
`:incl-newline?` - Include terminating system newline? (default true)
`:incl-keys` - Subset of signal keys to retain from those otherwise
- excluded by default: #{:location :kvs :file :thread}
+ excluded by default: #{:location :kvs :file :host :thread}
Examples:
(pr-signal-fn {:pr-fn :edn ...}) ; Outputs edn
@@ -710,6 +711,14 @@ Examples:
(require '[jsonista.core :as jsonista])
(pr-signal-fn {:pr-fn jsonista/write-value-as-string ...})
+Motivation:
+ Why use this util instead of just directly using the print function
+ given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
+ so may contain things like nil values and duplicated content.
+
+ This util efficiently clean signals of such noise, helping reduce
+ storage/transmission size, and making key info easier to see.
+
See also `format-signal-fn` for human-readable output.
Structured telemetry for Clojure/Script applications.
See the GitHub page (esp. Wiki) for info on motivation and design:
<https://www.taoensso.com/telemere>
Optional context (state) attached to all signals.
@@ -31,10 +31,13 @@ futures, agents, etc.
Tips:
- Compose multiple middleware fns together with `comp-middleware`.
- - Use `get-env` to set default (root) value based on environmental config.
Experimental, subject to change.
(fn [root?]) used to generate signal `:uid` values when tracing.
These are basically unique signal instance identifiers.
+Relevant only when `otel-tracing?` is false.
+If `otel-tracing?` is true, uids are instead generated by `*otel-tracer*`.
+
`root?` argument is true iff signal is a top-level trace (i.e. form
being traced is unnested = has no parent form).
@@ -51,30 +54,7 @@ By default generates nano-style uids like
For plain fixed-length UUIDs use: (fn [_root?] (utils/uuid))
For plain fixed-length UUID strings use: (fn [_root?] (utils/uuid-str))
-See also `utils/nano-uid-fn`, `utils/hex-id-fn`, etc.
Registers given signal handler and returns
-{<handler-id> {:keys [dispatch-opts handler-fn]}} for all handlers
-now registered.
-
-`handler-fn` should be a fn of exactly 2 arities:
-
- [signal] ; Single argument
- Called asynchronously or synchronously (depending on dispatch options)
- to do something useful with the given signal.
-
- Example actions:
- Save data to disk or 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.
-
- [] ; No arguments
- Called exactly once when stopping handler to provide an opportunity
- for handler to flush buffers, close files, etc. May just noop.
-
-NB you should always call `stop-handlers!` somewhere appropriate - usually
-near the end of your `-main` or shutdown procedure, AFTER all other code has
-completed that could create signals.
-
-See `help:handler-dispatch-options` for handler filters, etc.
call-on-shutdown!
clj
added in Encore v3.114.0 (2024-08-07)
(call-on-shutdown! f)
Registers given nullary fn as a JVM shutdown hook.
+See also `utils/nano-uid-fn`, `utils/hex-id-fn`, etc.
(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 root trace? do let data msg error & kvs]} form)
Unconditionally executes given form and-
If form succeeds: return the form's result.
@@ -114,11 +94,15 @@ See also `error!`.
[2] See `help:signal-options` - {:keys [kind level id data ...]}
[3] See `help:signal-content` - {:keys [kind level id data ...]}
[4] See `help:signal-filters` - (by ns/kind/id/level, sampling, etc.)
Experimental, subject to change.
-Runs Telemere's registered intake checks and returns
-{<source-id> {:keys [sending->telemere? telemere-receiving? ...]}}.
+
check-interop
clj
(check-interop)
Experimental, subject to change.
+Runs Telemere's registered interop checks and returns info useful
+for tests/debugging, e.g.:
-Useful for tests/debugging.
(comp-middleware fs)(comp-middleware f1 f2)(comp-middleware f1 f2 f3)(comp-middleware f1 f2 f3 & fs)
Returns a single (composite) unary fn that applies all given unary fns
sequentially (left->right!: f1, f2, ...). If any given fn returns nil, the
returned composite fn immediately returns nil:
@@ -563,8 +547,8 @@ See the relevant docstrings for details.
See `help:handler-dispatch-options` for handler filters, etc.
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
Signals are maps with {:keys [inst id ns level data msg_ ...]}, though they
+can be modified by signal and/or handler middleware.
Default signal keys:
@@ -669,8 +653,6 @@ and return values), making them more/less convenient for certain use cases:
handler output, so a great way to provide custom data/opts for use
(only) by custom middleware/handlers.
-handler-specific data that can just be ignored by other handlers
-
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
[1] `java.time.Instant` or `js/Date`
@@ -725,7 +707,44 @@ Useful for conditionally splicing in extra message content, etc.:
(log! [(when <cond> (msg-splice ["Username:" "Steve"]))])
%> {:msg_ "Username: Steve"}
Experimental, subject to change. Feedback welcome!
+
+When OpenTelemetry Java API [1] is present, returns map with keys:
+ :logger-provider - default `io.opentelemetry.api.logs.LoggerProvider`
+ :tracer-provider - default `io.opentelemetry.api.trace.TracerProvider`
+ :via - ∈ #{:sdk-extension-autoconfigure :global}
+
+Uses `AutoConfiguredOpenTelemetrySdk` when possible, or
+`GlobalOpenTelemetry` otherwise.
+
+See the relevant OpenTelemetry Java docs for details.
+
+[1] Ref. <https://github.com/open-telemetry/opentelemetry-java>
otel-tracing?
clj
Experimental, subject to change. Feedback welcome!
+
+Should Telemere's tracing signal creators (`trace!`, `spy!`, etc.)
+interop with OpenTelemetry Java [1]? This will affect relevant
+Telemere macro expansions.
+
+Defaults to `true` iff OpenTelemetry Java is present when this
+namespace is evaluated/compiled.
+
+If `false`:
+ 1. Telemere's OpenTelemetry handler will NOT emit to `SpanExporter`s.
+ 2. Telemere and OpenTelemetry will NOT recognize each other's spans.
+
+If `true`:
+ 1. Telemere's OpenTelemetry handler WILL emit to `SpanExporter`s.
+ 2. Telemere and OpenTelemetry WILL recognize each other's spans.
+
+Override default by setting one of the following to "true" or "false":
+ JVM property: `taoensso.telemere.otel-tracing`
+ Env variable: `TAOENSSO_TELEMERE_otel-tracing`
+ Classpath resource: `taoensso.telemere.otel-tracing`
+
+See also: `otel-get-default-providers`, `*otel-tracer*`,
+ `taoensso.telemere.open-telemere/handler:open-telemetry`.
+
+[1] Ref. <https://github.com/open-telemetry/opentelemetry-java>
Experimental, subject to change.
Returns a (fn pr [signal]) that:
- Takes a Telemere signal (map).
- Returns a machine-readable signal ?string.
@@ -736,7 +755,7 @@ Options:
`:incl-nils?` - Include signal's keys with nil values? (default false)
`:incl-newline?` - Include terminating system newline? (default true)
`:incl-keys` - Subset of signal keys to retain from those otherwise
- excluded by default: #{:location :kvs :file :thread}
+ excluded by default: #{:location :kvs :file :host :thread}
Examples:
(pr-signal-fn {:pr-fn :edn ...}) ; Outputs edn
@@ -748,6 +767,14 @@ Examples:
(require '[jsonista.core :as jsonista])
(pr-signal-fn {:pr-fn jsonista/write-value-as-string ...})
+Motivation:
+ Why use this util instead of just directly using the print function
+ given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
+ so may contain things like nil values and duplicated content.
+
+ This util efficiently clean signals of such noise, helping reduce
+ storage/transmission size, and making key info easier to see.
+
See also `format-signal-fn` for human-readable output.
Highly experimental, possibly buggy, and subject to change!!
Feedback and bug reports very welcome! Please ping me (Peter) at:
<https://www.taoensso.com/telemere> or
<https://www.taoensso.com/telemere/slack>
@@ -22,14 +13,10 @@ Needs `opentelemetry-java`,
Returns a signal handler that:
- Takes a Telemere signal (map).
- - Emits signal data to configured `io.opentelemetry.api.logs.Logger`
- - Emits tracing data to configured `io.opentelemetry.api.logs.Tracer`
+ - Emits signal data to configured `LogExporter`
+ - Emits tracing data to configured `SpanExporter`
+ iff `telemere/otel-tracing?` is true.
Options:
- `:logger-provider` - ∈ #{nil :default <io.opentelemetry.api.logs.LoggerProvider>} [1]
- `:tracer-provider` - ∈ #{nil :default <io.opentelemetry.api.trace.TracerProvider>} [1]
- `:max-span-msecs` - (Advanced) Longest tracing span to support in milliseconds
- (default 120 mins). If recorded spans exceed this max, emitted
- data will be inaccurate. Larger values use more memory.
-
-[1] See `get-default-providers` for more info
\ No newline at end of file
+ `:logger-provider` - nil or `io.opentelemetry.api.logs.LoggerProvider`,
+ (see `telemere/get-default-providers` for default).
\ No newline at end of file
diff --git a/taoensso.telemere.postal.html b/taoensso.telemere.postal.html
index df35711..a3abd40 100644
--- a/taoensso.telemere.postal.html
+++ b/taoensso.telemere.postal.html
@@ -1,6 +1,6 @@
-taoensso.telemere.postal documentation
\ No newline at end of file
diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html
index a2b66a6..150764d 100644
--- a/taoensso.telemere.timbre.html
+++ b/taoensso.telemere.timbre.html
@@ -1,6 +1,6 @@
-taoensso.telemere.timbre documentation
Interop support for `tools.logging` -> Telemere.
Telemere will attempt to load this ns automatically when possible.
Naming conventions:
`tools.logging` - For referring to the library.
`tools-logging` - For symbols, keywords, and this namespace.
- `clojure.tools.logging` - For env config to match library's conventions.
check-intake
clj
(check-intake)
Returns {:keys [present? sending->telemere? telemere-receiving?]}.
+ `clojure.tools.logging` - For env config to match library's conventions.
check-interop
clj
(check-interop)
Returns interop debug info map.
tools-logging->telemere!
clj
(tools-logging->telemere!)
Configures `tools.logging` to use Telemere as its logging
implementation (backend).
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
index 234cd6c..77a1296 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.
@@ -58,7 +58,7 @@ Options:
`:incl-nils?` - Include signal's keys with nil values? (default false)
`:incl-newline?` - Include terminating system newline? (default true)
`:incl-keys` - Subset of signal keys to retain from those otherwise
- excluded by default: #{:location :kvs :file :thread}
+ excluded by default: #{:location :kvs :file :host :thread}
Examples:
(pr-signal-fn {:pr-fn :edn ...}) ; Outputs edn
@@ -70,6 +70,14 @@ Examples:
(require '[jsonista.core :as jsonista])
(pr-signal-fn {:pr-fn jsonista/write-value-as-string ...})
+Motivation:
+ Why use this util instead of just directly using the print function
+ given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
+ so may contain things like nil values and duplicated content.
+
+ This util efficiently clean signals of such noise, helping reduce
+ storage/transmission size, and making key info easier to see.
+
See also `format-signal-fn` for human-readable output.
Experimental, subject to change.
@@ -69,7 +69,7 @@ Options:
`:incl-nils?` - Include signal's keys with nil values? (default false)
`:incl-newline?` - Include terminating system newline? (default true)
`:incl-keys` - Subset of signal keys to retain from those otherwise
- excluded by default: #{:location :kvs :file :thread}
+ excluded by default: #{:location :kvs :file :host :thread}
Examples:
(pr-signal-fn {:pr-fn :edn ...}) ; Outputs edn
@@ -81,6 +81,14 @@ Examples:
(require '[jsonista.core :as jsonista])
(pr-signal-fn {:pr-fn jsonista/write-value-as-string ...})
+Motivation:
+ Why use this util instead of just directly using the print function
+ given to `:pr-fn`? Signals are optimized for cheap creation and easy handling,
+ so may contain things like nil values and duplicated content.
+
+ This util efficiently clean signals of such noise, helping reduce
+ storage/transmission size, and making key info easier to see.
+
See also `format-signal-fn` for human-readable output.