\ No newline at end of file
diff --git a/index.cljs.html b/index.cljs.html
index 8833176..50ed56f 100644
--- a/index.cljs.html
+++ b/index.cljs.html
@@ -1,3 +1,4 @@
-Telemere 1.0.0-alpha2
\ No newline at end of file
diff --git a/index.html b/index.html
index 49f1f55..34015de 100644
--- a/index.html
+++ b/index.html
@@ -1,3 +1,3 @@
-Telemere 1.0.0-alpha2
\ No newline at end of file
diff --git a/taoensso.telemere.cljs.html b/taoensso.telemere.cljs.html
index b564a9f..4514bd8 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.
@@ -133,7 +133,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (catch->error! ...)).
+ - Test using `with-signal`: (with-signal (catch->error! ...)).
- Supports the same options as other signals [1].
- Useful for recording errors in forms, futures, callbacks, etc.
@@ -145,19 +145,7 @@ See also `error!`.
Runs Telemere's registered interop checks and returns
{<interop-id> {:keys [sending->telemere? telemere-receiving? ...]}}.
-Useful for tests/debugging.
Experimental, subject to change.
-
-If `js/console` exists, returns a (fn handler [signal]) that:
- - Takes a Telemere signal.
- - Writes a formatted signal string to JavaScript console.
-
-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.
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.
(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.
@@ -180,7 +168,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (error! ...)).
+ - Test using `with-signal`: (with-signal (error! ...)).
- Supports the same options as other signals [3].
- `error` arg is a platform error (`java.lang.Throwable` or `js/Error`).
@@ -208,7 +196,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (error! ...)).
+ - Test using `with-signal`: (with-signal (event! ...)).
- Supports the same options as other signals [3].
- A good general-purpose signal, prefer to `log!` by default, since it
@@ -274,7 +262,21 @@ Result must be something that can be safely embedded in code during
macro-expansion. Symbols in edn will be evaluated during expansion.
Experimental, subject to change.
+
+If `js/console` exists, returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes raw signal data to JavaScript console.
+
+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 via:
@@ -346,7 +348,12 @@ Default keys:
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`
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
@@ -415,7 +422,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (log! ...)).
+ - Test using `with-signal`: (with-signal (log! ...)).
- Supports the same options as other signals [3].
- Prefer `event!` to `log!` by default, since it better encourages structured
@@ -458,14 +465,7 @@ Example:
(defn send-message! [username msg-content]
(if-let [fail (my-rate-limiter username)]
(throw (ex-info "Sorry, rate limited!" {:fail fail}))
- <send message>))
Experimental, subject to change.
-
-If `js/console` exists, returns a (fn handler [signal]) that:
- - Takes a Telemere signal.
- - Writes raw signal data to JavaScript console.
-
-Intended for use with browser formatting tools like `binaryage/devtools`,
-Ref. <https://github.com/binaryage/cljs-devtools>.
Sets signal call id filter based on given `id-filter` spec.
@@ -527,7 +527,7 @@ their defaults and the focus of their call APIs (args and return values):
Tips:
- - Test using `with-signals`: (with-signals (signal! ...)).
+ - Test using `with-signal`: (with-signal (signal! ...)).
- Supports the same options as other signals [3].
----------------------------------------
@@ -556,7 +556,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (spy! ...)).
+ - Test using `with-signal`: (with-signal (spy! ...)).
- Supports the same options as other signals [3].
- Identical to `trace!`, but focused on form + level rather than form + id.
@@ -565,6 +565,9 @@ Tips:
- Execution of `form` arg may trigger additional (nested) signals.
Each signal's `:parent` key will indicate its immediate parent.
+ - Can be useful to wrap with `catch->error!`:
+ (catch->error! ::error-id (spy! ...)).
+
----------------------------------------
[1] See `help:signal-handling` docstring
[2] See `help:signal-content` docstring
@@ -591,7 +594,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (trace! ...)).
+ - Test using `with-signal`: (with-signal (trace! ...)).
- Supports the same options as other signals [3].
- Identical to `spy!`, but focused on form + id rather than form + level.
@@ -600,6 +603,9 @@ Tips:
- Execution of `form` arg may trigger additional (nested) signals.
Each signal's `:parent` key will indicate its immediate parent.
+ - Can be useful to wrap with `catch->error!`:
+ (catch->error! ::error-id (trace! ...)).
+
- 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.
@@ -631,34 +637,21 @@ See `set-kind-filter!` for details.
Experimental.
+Executes given form, trapping errors. Returns the LAST signal triggered by form.
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.
Experimental.
-Executes given form and records any signals triggered by it.
-Return value depends on given options. Useful for tests/debugging.
-
Options:
+ `trap-signals?` (default: false)
+ Should ALL signals triggered by form be trapped to prevent normal dispatch
+ to registered handlers?
- `handle?`
- Should registered handlers receive signals triggered by form, as usual?
- Default: true.
+ `raw-msg?` (default: false)
+ Should delayed `:msg_` in returned signal be retained as-is?
+ Delay is otherwise replaced by realized string.
- `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.
\ No newline at end of file
diff --git a/taoensso.telemere.html b/taoensso.telemere.html
index c036f1b..358b36c 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.
@@ -133,7 +133,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (catch->error! ...)).
+ - Test using `with-signal`: (with-signal (catch->error! ...)).
- Supports the same options as other signals [1].
- Useful for recording errors in forms, futures, callbacks, etc.
@@ -145,22 +145,7 @@ See also `error!`.
Runs Telemere's registered interop checks and returns
{<interop-id> {:keys [sending->telemere? telemere-receiving? ...]}}.
-Useful for tests/debugging.
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.
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.
(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.
@@ -183,7 +168,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (error! ...)).
+ - Test using `with-signal`: (with-signal (error! ...)).
- Supports the same options as other signals [3].
- `error` arg is a platform error (`java.lang.Throwable` or `js/Error`).
@@ -211,7 +196,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (error! ...)).
+ - Test using `with-signal`: (with-signal (event! ...)).
- Supports the same options as other signals [3].
- A good general-purpose signal, prefer to `log!` by default, since it
@@ -277,7 +262,47 @@ Result must be something that can be safely embedded in code during
macro-expansion. Symbols in edn will be evaluated during expansion.
Experimental, subject to change.
+
+Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes a formatted signal string to stream.
+
+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.
+
+ Returns a (fn handler [signal]) that:
+ - Takes a Telemere signal.
+ - Writes a formatted signal string to file.
+
+Signals will be appended to file specified by `path`.
+Depending on options, archives may be maintained:
+ - `logs/app.log.n.gz` (for nil `:interval`, non-nil `:max-file-size`)
+ - `logs/app.log-YYYY-MM-DDd.n.gz` (for non-nil `:interval`) ; d=daily/w=weekly/m=monthly
+
+Example files with default options:
+ `/logs/telemere.log` ; Current file
+ `/logs/telemere.log-2020-01-01m.1.gz` ; Archive for Jan 2020, part 1 (newest entries)
+ ...
+ `/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`).
+ When non-nil, causes interval-based archives to be maintained.
+
+ `:max-file-size` ∈ #{nil <pos-int>} (default 4MB)
+ When `path` file size > ~this many bytes, rotates old content to numbered archives.
+
+ `:max-num-parts` ∈ #{nil <pos-int>} (default 8)
+ Maximum number of numbered archives to retain for any particular interval.
+
+ `: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 via:
@@ -349,7 +374,12 @@ Default keys:
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`
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
@@ -419,7 +449,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (log! ...)).
+ - Test using `with-signal`: (with-signal (log! ...)).
- Supports the same options as other signals [3].
- Prefer `event!` to `log!` by default, since it better encourages structured
@@ -531,7 +561,7 @@ their defaults and the focus of their call APIs (args and return values):
Tips:
- - Test using `with-signals`: (with-signals (signal! ...)).
+ - Test using `with-signal`: (with-signal (signal! ...)).
- Supports the same options as other signals [3].
----------------------------------------
@@ -560,7 +590,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (spy! ...)).
+ - Test using `with-signal`: (with-signal (spy! ...)).
- Supports the same options as other signals [3].
- Identical to `trace!`, but focused on form + level rather than form + id.
@@ -569,6 +599,9 @@ Tips:
- Execution of `form` arg may trigger additional (nested) signals.
Each signal's `:parent` key will indicate its immediate parent.
+ - Can be useful to wrap with `catch->error!`:
+ (catch->error! ::error-id (spy! ...)).
+
----------------------------------------
[1] See `help:signal-handling` docstring
[2] See `help:signal-content` docstring
@@ -609,7 +642,7 @@ Examples:
Tips:
- - Test using `with-signals`: (with-signals (trace! ...)).
+ - Test using `with-signal`: (with-signal (trace! ...)).
- Supports the same options as other signals [3].
- Identical to `spy!`, but focused on form + id rather than form + level.
@@ -618,6 +651,9 @@ Tips:
- Execution of `form` arg may trigger additional (nested) signals.
Each signal's `:parent` key will indicate its immediate parent.
+ - Can be useful to wrap with `catch->error!`:
+ (catch->error! ::error-id (trace! ...)).
+
- 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.
@@ -652,34 +688,21 @@ See `set-kind-filter!` for details.
Experimental.
+Executes given form, trapping errors. Returns the LAST signal triggered by form.
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.
Experimental.
-Executes given form and records any signals triggered by it.
-Return value depends on given options. Useful for tests/debugging.
-
Options:
+ `trap-signals?` (default: false)
+ Should ALL signals triggered by form be trapped to prevent normal dispatch
+ to registered handlers?
- `handle?`
- Should registered handlers receive signals triggered by form, as usual?
- Default: true.
+ `raw-msg?` (default: false)
+ Should delayed `:msg_` in returned signal be retained as-is?
+ Delay is otherwise replaced by realized string.
- `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.
\ No newline at end of file
diff --git a/taoensso.telemere.timbre-shim.cljs.html b/taoensso.telemere.timbre-shim.cljs.html
index ae3f87a..3e25a5f 100644
--- a/taoensso.telemere.timbre-shim.cljs.html
+++ b/taoensso.telemere.timbre-shim.cljs.html
@@ -1,4 +1,4 @@
-taoensso.telemere.timbre-shim documentation
Main Timbre macros, reimplemented on top of Telemere.
+Intended to help ease migration from Timbre to Telemere.
\ No newline at end of file
diff --git a/taoensso.telemere.timbre-shim.html b/taoensso.telemere.timbre-shim.html
index 6df052b..7c2bf3c 100644
--- a/taoensso.telemere.timbre-shim.html
+++ b/taoensso.telemere.timbre-shim.html
@@ -1,4 +1,28 @@
-taoensso.telemere.timbre-shim documentation
\ No newline at end of file
diff --git a/taoensso.telemere.utils.cljs.html b/taoensso.telemere.utils.cljs.html
index abfb408..619eb14 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.
@@ -10,16 +10,20 @@ Returns true iff given signal has an `:error` value, or a `:kind` or `:level`
that indicates that it's an error.
Experimental, subject to change.
Returns a (fn format [error]) that:
- Takes a platform error (`Throwable` or `js/Error`).
- - Returns a formatted human-readable string
Experimental, subject to change without notice.
+
Returns a (fn format [instant]) that:
- Takes a platform instant (`java.time.Instant` or `js/Date`).
- Returns a formatted human-readable string.
-`:formatter` may be a `java.time.format.DateTimeFormatter` (Clj) or
- `goog.i18n.DateTimeFormat` (Cljs).
+Options:
+ `:zone` (Clj only) - `java.time.ZoneOffset` (defaults to UTC).
+ `:formatter`
+ `java.time.format.DateTimeFormatter` (Clj) or
+ `goog.i18n.DateTimeFormat` (Cljs),
-Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`),
- e.g.: "2011-12-03T10:15:130Z".
Experimental, subject to change.
Returns a (fn format [nanosecs]) that:
- Takes a long nanoseconds (e.g. runtime).
- Returns a formatted human-readable string like:
@@ -29,7 +33,9 @@ Returns a (fn format->edn [signal]) that:
- 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.
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.
@@ -41,12 +47,12 @@ Returns a (fn format [signal]) that:
`:error` -> `js/console.error`, etc.
Defaults to `js.console.log` for unmatched signal levels.
-NB: assumes that `js/console` exists, handler builders should check first!
Experimental, subject to change.
Returns minimal signal map, removing:
- Keys with nil values, and
- Keys with redundant values (`:extra-kvs`, `:location`, `:file`).
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 5639e74..12faf75 100644
--- a/taoensso.telemere.utils.html
+++ b/taoensso.telemere.utils.html
@@ -1,35 +1,50 @@
-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.
+that indicates that it's an error.
file-writer
clj
(file-writer file append?)
Experimental, subject to change!!
+
+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 handlers that write to files, etc.
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.
+
Returns a (fn format [instant]) that:
- Takes a platform instant (`java.time.Instant` or `js/Date`).
- Returns a formatted human-readable string.
-`:formatter` may be a `java.time.format.DateTimeFormatter` (Clj) or
- `goog.i18n.DateTimeFormat` (Cljs).
+Options:
+ `:zone` (Clj only) - `java.time.ZoneOffset` (defaults to UTC).
+ `:formatter`
+ `java.time.format.DateTimeFormatter` (Clj) or
+ `goog.i18n.DateTimeFormat` (Cljs),
-Defaults to `ISO8601` formatter (`YYYY-MM-DDTHH:mm:ss.sssZ`),
- e.g.: "2011-12-03T10:15:130Z".
Experimental, subject to change.
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->json [signal]) that:
- Takes a Telemere signal.
- - Returns JSON string of the (minified) signal.
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 without notice.
-Returns given Clj argument as JSON string.
-Uses the first of the following, or throws if none available:
- 1. `metosin/jsonista`, Ref. <https://github.com/metosin/jsonista>
- 2. `cheshire`, Ref. <https://github.com/dakrone/cheshire>
- 3. `org.clojure/clojure.data`, Ref. <https://github.com/clojure/data.json>
-
-In all cases attempts to provide sane + reasonably consistent behaviour, but
-prefer directly using a lib with opts of your choice when you have specific needs!