From c5c8a188c125593a3fd73cb246bf9333135538fe Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Thu, 3 Oct 2024 06:47:38 +0200 Subject: [PATCH] [doc] [#25] Add extra info re: async tracing --- projects/main/resources/signal-docstrings/spy!.txt | 13 ++++++++++++- .../main/resources/signal-docstrings/trace!.txt | 13 ++++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/projects/main/resources/signal-docstrings/spy!.txt b/projects/main/resources/signal-docstrings/spy!.txt index 044d61e..948310c 100644 --- a/projects/main/resources/signal-docstrings/spy!.txt +++ b/projects/main/resources/signal-docstrings/spy!.txt @@ -8,7 +8,7 @@ When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to console/file/queue/db, etc.). -`form` is generally expected to be synchronous and eager (not a lazy seq, +`form` arg is generally expected to be synchronous and eager (not a lazy seq, async call, or IOT code like a core.async `go` block, etc.). Examples: @@ -37,6 +37,17 @@ Tips: - Can be useful to wrap with `catch->error!`: (catch->error! ::error-id (spy! ...)). + - Runtime of async or lazy code in `form` will intentionally NOT be included + in resulting signal's `:run-nsecs` value. If you want to measure such + runtimes, make sure that your form wraps where the relevant costs are + actually realized. Compare: + (spy! (delay (my-slow-code))) ; Doesn't measure slow code + (spy! @(delay (my-slow-code))) ; Does measure slow code + + - See also Tufte (https://www.taoensso.com/tufte) for a complementary/partner + Clj/s library that offers more advanced performance measurment and shares + the same signal engine (filtering and handler API) as Telemere. + ---------------------------------------------------------------------- [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]} diff --git a/projects/main/resources/signal-docstrings/trace!.txt b/projects/main/resources/signal-docstrings/trace!.txt index c858c28..ab7527a 100644 --- a/projects/main/resources/signal-docstrings/trace!.txt +++ b/projects/main/resources/signal-docstrings/trace!.txt @@ -8,7 +8,7 @@ When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to console/file/queue/db, etc.). -`form` is generally expected to be synchronous and eager (not a lazy seq, +`form` arg is generally expected to be synchronous and eager (not a lazy seq, async call, or IOT code like a core.async `go` block, etc.). Examples: @@ -41,6 +41,17 @@ Tips: refers to the general action of tracing program flow rather than to the common logging level of the same name. + - Runtime of async or lazy code in `form` will intentionally NOT be included + in resulting signal's `:run-nsecs` value. If you want to measure such + runtimes, make sure that your form wraps where the relevant costs are + actually realized. Compare: + (trace! (delay (my-slow-code))) ; Doesn't measure slow code + (trace! @(delay (my-slow-code))) ; Does measure slow code + + - See also Tufte (https://www.taoensso.com/tufte) for a complementary/partner + Clj/s library that offers more advanced performance measurment and shares + the same signal engine (filtering and handler API) as Telemere. + ---------------------------------------------------------------------- [1] See `help:signal-creators` - (`signal!`, `log!`, `event!`, ...) [2] See `help:signal-options` - {:keys [kind level id data ...]}