\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index a22f482..f98fc72 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,4 +1,4 @@
-Telemere 1.0.0-beta5
\ No newline at end of file
diff --git a/index.html b/index.html
index cfbbdb6..275bd0d 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-beta5
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index c95dec1..71ae315 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.
@@ -15,11 +15,10 @@ 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.
+ - Value may be of form {<scope-id> <data>} for custom scoping, etc.
Optional (fn [signal]) => ?modified-signal to apply (once) when
+signal is created. When middleware returns nil, skips all handlers.
-Useful for transforming each signal before handling.
+Compose multiple middleware fns together with `comp-middleware.
Re/bind dynamic value using `with-middleware`, `binding`.
Modify root (base) value using `set-middleware!`.
Registers given signal handler and returns
@@ -94,11 +93,10 @@ Dispatch options include:
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`.
+ Optional (fn [handler-arg]) => ?modified-handler-arg to apply before
+ handling. When middleware returns nil, skips handler.
- Useful for transforming `handler-arg` before handling.
+ Compose multiple middleware fns together with `comp-middleware`.
`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.
@@ -157,7 +155,14 @@ 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-flow` - (filters, handling, etc.)
Default root (base) value of `*ctx*` var.
Defaults to `nil`, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
@@ -228,7 +233,12 @@ 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.)
Experimental, subject to change.
+Returns a (fn format [signal]) that:
+ - Takes a Telemere signal.
+ - Returns human-readable formatted string.
+
+See also `pr-signal-fn` for machine-readable output.
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,
@@ -283,17 +293,17 @@ TIP!: Use the {:return :explain} option in tests or at the REPL to verify/inspec
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.
+ - Writes 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.
@@ -421,6 +431,7 @@ Default signal keys:
`:line` -------- ?int line of signal creator callsite, same as (:line location)
`:column` ------ ?int column of signal creator callsite, same as (:column location)
`:file` -------- ?str filename of signal creator callsite, same as (:file location)
+`:thread` ------ (Clj only) {:keys [group name id]} thread info for thread that called signal creator
`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
<kvs> ---------- Other arb user-level ?kvs given to signal creator. Typically NOT included
@@ -509,12 +520,7 @@ For more info:
- On handler filters, see: `help:signal-handlers` docstring
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
Signal options (shared by all signal creators):
`:inst` -------- Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
`:level` ------- Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
@@ -538,7 +544,7 @@ See relevant docstrings for details.
Experimental, subject to change.
+Returns a (fn pr-signal [signal]) that:
+ - Takes a Telemere signal.
+ - Returns machine-readable serialized string of the (minified) signal.
+
+Options include:
+ `pr-fn` ∈ #{<unary-fn> :edn :json (Cljs only)}
+ See arglists for more.
+
+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.
Sets minimum signal call level based on given `min-level` spec.
`min-level` may be:
@@ -793,7 +817,7 @@ 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!`.
Executes form with `*out*` bound to flush to Telemere signals with given opts.
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index 5ab0757..a9717fe 100644
--- a/taoensso.telemere.html
+++ b/taoensso.telemere.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.
@@ -15,11 +15,10 @@ 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.
+ - Value may be of form {<scope-id> <data>} for custom scoping, etc.
Optional (fn [signal]) => ?modified-signal to apply (once) when
+signal is created. When middleware returns nil, skips all handlers.
-Useful for transforming each signal before handling.
+Compose multiple middleware fns together with `comp-middleware.
Re/bind dynamic value using `with-middleware`, `binding`.
Modify root (base) value using `set-middleware!`.
Registers given signal handler and returns
@@ -94,11 +93,10 @@ Dispatch options include:
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`.
+ Optional (fn [handler-arg]) => ?modified-handler-arg to apply before
+ handling. When middleware returns nil, skips handler.
- Useful for transforming `handler-arg` before handling.
+ Compose multiple middleware fns together with `comp-middleware`.
`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.
@@ -161,7 +159,14 @@ See also `error!`.
Runs Telemere's registered intake checks and returns
{<source-id> {:keys [sending->telemere? telemere-receiving? ...]}}.
-Useful for tests/debugging.
Default root (base) value of `*ctx*` var.
Defaults to `nil`, controlled by:
(get-env {:as :edn} :taoensso.telemere/default-ctx<.platform><.edn>)
@@ -232,7 +237,12 @@ 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.)
Experimental, subject to change.
+Returns a (fn format [signal]) that:
+ - Takes a Telemere signal.
+ - Returns human-readable formatted string.
+
+See also `pr-signal-fn` for machine-readable output.
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,
@@ -287,24 +297,23 @@ TIP!: Use the {:return :explain} option in tests or at the REPL to verify/inspec
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.
+ - Writes 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!
+ `:output-fn` - (fn [signal]) => output string, see `format-signal-fn` or `pr-signal-fn`
+ `: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.
- - Writes a formatted signal string to file.
+ - Writes formatted signal string to file.
Signals will be appended to file specified by `path`.
Depending on options, archives may be maintained:
@@ -318,9 +327,10 @@ Example files with default options:
`/logs/telemere.log-2020-01-01m.8.gz` ; Archive for Jan 2020, part 8 (oldest entries)
Options:
- `:format-signal-fn`- (fn [signal]) => output, see `help:signal-formatters`.
- `:path` - Path string of the target output file (default `logs/telemere.log`).
- `:interval` - ∈ #{nil :daily :weekly :monthly} (default `:monthly`).
+ `:output-fn`- (fn [signal]) => output string, see `format-signal-fn` or `pr-signal-fn`
+ `:path` - Path string of the target output file (default `logs/telemere.log`)
+
+ `:interval` - ∈ #{nil :daily :weekly :monthly} (default `:monthly`)
When non-nil, causes interval-based archives to be maintained.
`:max-file-size` ∈ #{nil <pos-int>} (default 4MB)
@@ -451,6 +461,7 @@ Default signal keys:
`:line` -------- ?int line of signal creator callsite, same as (:line location)
`:column` ------ ?int column of signal creator callsite, same as (:column location)
`:file` -------- ?str filename of signal creator callsite, same as (:file location)
+`:thread` ------ (Clj only) {:keys [group name id]} thread info for thread that called signal creator
`:sample-rate` - ?rate ∈ℝ[0,1] for combined signal AND handler sampling (0.75 => allow 75% of signals, nil => allow all)
<kvs> ---------- Other arb user-level ?kvs given to signal creator. Typically NOT included
@@ -620,12 +631,7 @@ For more info:
- On handler filters, see: `help:signal-handlers` docstring
If anything is unclear, please ping me (@ptaoussanis) so that I can
-improve these docs!
Experimental, subject to change.
+Returns a (fn pr-signal [signal]) that:
+ - Takes a Telemere signal.
+ - Returns machine-readable serialized string of the (minified) signal.
+
+Options include:
+ `pr-fn` ∈ #{<unary-fn> :edn :json (Cljs only)}
+ See arglists for more.
+
+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.
Sets minimum signal call level based on given `min-level` spec.
`min-level` may be:
@@ -801,7 +825,7 @@ Examples:
- {:allow <spec> :deny <spec>} with specs as above.
If present, `:allow` spec MUST match, AND
If present, `:deny` spec MUST NOT match.
Shuts down all registered signal handlers in parallel, and returns
?{<handler-id> {:keys [okay error]}}.
Future calls to handlers will no-op.
@@ -940,7 +964,7 @@ 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!`.
Executes form with `*out*` bound to flush to Telemere signals with given opts.
diff --git a/taoensso.telemere.open-telemetry.html b/taoensso.telemere.open-telemetry.html
index c1759a7..2150a11 100644
--- a/taoensso.telemere.open-telemetry.html
+++ b/taoensso.telemere.open-telemetry.html
@@ -1,6 +1,6 @@
-taoensso.telemere.open-telemetry documentation
Experimental, subject to change.
+Returns a (fn format [signal]) that:
+ - Takes a Telemere signal.
+ - Returns a formatted email subject like:
+ "INFO EVENT :taoensso.telemere.postal/ev-id1 - msg"
\ No newline at end of file
diff --git a/taoensso.telemere.sockets.html b/taoensso.telemere.sockets.html
new file mode 100644
index 0000000..d439924
--- /dev/null
+++ b/taoensso.telemere.sockets.html
@@ -0,0 +1,41 @@
+
+taoensso.telemere.sockets documentation
Experimental, subject to change. Feedback welcome!
+
+Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Sends formatted signal string to specified TCP socket.
+
+Options:
+ `host` - Destination TCP socket hostname string
+ `port` - Destination TCP socket port int
+
+ `:socket-opts` - {:keys [ssl? connect-timeout-msecs]}
+ `:output-fn` - (fn [signal]) => output string, see `format-signal-fn` or `pr-signal-fn`
+
+Limitations:
+ - Failed writes will be retried only once.
+ - Writes lock on a single underlying socket, so IO won't benefit from adding
+ extra handler threads. Let me know if there's demand for socket pooling.
Experimental, subject to change. Feedback welcome!
+
+Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Sends formatted signal string to specified UDP socket.
+
+Options:
+ `host` - Destination UDP socket hostname string
+ `port` - Destination UDP socket port int
+
+ `:output-fn` - (fn [signal]) => output string, see `format-signal-fn` or `pr-signal-fn`
+ `:max-packet-bytes` - Max packet size (in bytes) before truncating output (default 512)
+ `:truncation-warning-fn` - Optional (fn [{:keys [max actual signal]}]) to call whenever
+ output is truncated. Should be appropriately rate-limited!
+
+Limitations:
+ - Due to UDP limitations, truncates output to `max-packet-bytes`!
+ - Failed writes will be retried only once.
+ - Writes lock on a single underlying socket, so IO won't benefit from adding
+ extra handler threads. Let me know if there's demand for socket pooling.
+ - No DTLS (Datagram Transport Layer Security) support,
+ please let me know if there's demand.
\ No newline at end of file
diff --git a/taoensso.telemere.streams.html b/taoensso.telemere.streams.html
index 733faae..6fbd7a2 100644
--- a/taoensso.telemere.streams.html
+++ b/taoensso.telemere.streams.html
@@ -1,6 +1,6 @@
-taoensso.telemere.streams documentation
\ No newline at end of file
diff --git a/taoensso.telemere.timbre.html b/taoensso.telemere.timbre.html
index 2e07e3e..271d6cd 100644
--- a/taoensso.telemere.timbre.html
+++ b/taoensso.telemere.timbre.html
@@ -1,6 +1,6 @@
-taoensso.telemere.timbre documentation
Experimental, subject to change.
Returns given signal with possible `:error` replaced by
[{:keys [type msg data]} ...] cause chain.
@@ -27,22 +27,12 @@ Options:
Returns a (fn format [nanosecs]) that:
- Takes a long nanoseconds (e.g. runtime).
- Returns a formatted human-readable string like:
- "1.00m", "4.20s", "340ms", "822μs", etc.
Experimental, subject to change.
-Returns a (fn format->edn [signal]) that:
- - Takes a Telemere signal.
- - Returns edn string of the (minified) signal.
Experimental, subject to change.
-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.
js-console-logger
cljs
(js-console-logger level)
Returns JavaScript console logger to match given signal level:
+ - Returns human-readable formatted 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.
@@ -55,5 +45,34 @@ Returns minimal signal map, removing:
Useful when serializing signals to edn/JSON/etc.
Experimental, subject to change.
+Returns a (fn pr-signal [signal]) that:
+ - Takes a Telemere signal.
+ - Returns machine-readable serialized string of the (minified) signal.
+
+Options include:
+ `pr-fn` ∈ #{<unary-fn> :edn :json (Cljs only)}
+ See arglists for more.
+
+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.
Experimental, subject to change.
+Returns a (fn preamble [signal]) that:
+ - Takes a Telemere signal.
+ - Returns a signal preamble ?string like:
+ "2024-03-26T11:14:51.806Z INFO EVENT Hostname taoensso.telemere(2,21) ::ev-id - msg"
+
+See arglists for options.
\ No newline at end of file
diff --git a/taoensso.telemere.utils.html b/taoensso.telemere.utils.html
index 102078c..a90d704 100644
--- a/taoensso.telemere.utils.html
+++ b/taoensso.telemere.utils.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.
@@ -39,22 +39,12 @@ Options:
Returns a (fn format [nanosecs]) that:
- Takes a long nanoseconds (e.g. runtime).
- Returns a formatted human-readable string like:
- "1.00m", "4.20s", "340ms", "822μs", etc.
Experimental, subject to change.
-Returns a (fn format->edn [signal]) that:
- - Takes a Telemere signal.
- - Returns edn string of the (minified) signal.
Experimental, subject to change.
-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.
host-ip
clj
(host-ip timeout-msecs timeout-val)(host-ip)
Returns cached local host IP address string, or `timeout-val` (default "UnknownHost").
+ - Returns human-readable formatted string.
+
+See also `pr-signal-fn` for machine-readable output.
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:
@@ -63,7 +53,57 @@ Returns minimal signal map, removing:
Useful when serializing signals to edn/JSON/etc.
Experimental, subject to change.
+Returns a (fn pr-signal [signal]) that:
+ - Takes a Telemere signal.
+ - Returns machine-readable serialized string of the (minified) signal.
+
+Options include:
+ `pr-fn` ∈ #{<unary-fn> :edn :json (Cljs only)}
+ See arglists for more.
+
+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.
Experimental, subject to change. Feedback welcome!
+
+Connects to specified TCP socket and returns a stateful fn of 2 arities:
+ [content] => Writes given content to socket, or no-ops if closed.
+ [] => Closes the writer.
+
+Useful for basic handlers that write to a TCP socket, etc.
+
+Options:
+ `:ssl?` - Use SSL/TLS?
+ `:connect-timeout-msecs` - Connection timeout (default 3000 msecs)
+ `:socket-fn` - (fn [host port timeout]) => `java.net.Socket`
+ `:ssl-socket-fn` - (fn [socket host port]) => `java.net.Socket`
+
+Notes:
+ - Writer should be manually closed after use (with zero-arity call).
+ - Flushes after every write.
+ - Will retry failed writes once, then drop.
+ - Thread safe, locks on single socket stream.
+ - Advanced users may want a custom implementation using a connection
+ pool and/or more sophisticated retry semantics, etc.
thread-id
clj
(thread-id)
Returns long id of current thread.
+
thread-info
clj
(thread-info)
Returns {:keys [group name id]} for current thread.