diff --git a/README.md b/README.md index 3b8f6d6..a3b9194 100644 --- a/README.md +++ b/README.md @@ -235,13 +235,13 @@ See relevant docstrings (links below) for usage info- | Name | Kind | Args | Returns | | :---------------------------------------------------------------------------------------------------------- | :--------- | :--------------- | :--------------------------- | -| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `:generic` | `opts` | Depends on opts | -| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` + `?level` | Signal allowed? | -| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `?level` + `msg` | Signal allowed? | +| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `?level` + `msg` | nil | +| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` + `?level` | nil | | [`trace!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#trace!) | `:trace` | `?id` + `run` | Form result | | [`spy!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#spy!) | `:spy` | `?level` + `run` | Form result | | [`error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#error!) | `:error` | `?id` + `error` | Given error | | [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#catch-%3Eerror!) | `:error` | `?id` | Form value or given fallback | +| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `:generic` | `opts` | Depends on opts | ### Internal help diff --git a/main/resources/signal-docstrings/catch-to-error!.txt b/main/resources/signal-docstrings/catch-to-error!.txt index 4aaf731..fd3d75a 100644 --- a/main/resources/signal-docstrings/catch-to-error!.txt +++ b/main/resources/signal-docstrings/catch-to-error!.txt @@ -1,11 +1,12 @@ ALWAYS (unconditionally) executes given `run` form and: - If `run` form succeeds: returns the form's result. - If `run` form throws ANYTHING: - Calls `error!` with the thrown error and given signal options [2], then - either returns given (:catch-val opts), or rethrows. Default kind: `:error` Default level: `:error` +Returns: + - If given `run` form succeeds: returns the form's result. + - If given `run` form throws ANYTHING: + Calls `error!` with the thrown error and given signal options [2], then + either returns given (:catch-val opts), or rethrows. Just a convenience util. For more flexibility use your own `try/catch`. See `taoensso.encore/try*` for easily catching cross-platform errors. diff --git a/main/resources/signal-docstrings/error!.txt b/main/resources/signal-docstrings/error!.txt index f0eb958..6434230 100644 --- a/main/resources/signal-docstrings/error!.txt +++ b/main/resources/signal-docstrings/error!.txt @@ -1,9 +1,10 @@ "Error" signal creator, emphasizing (optional id) + error (Exception, etc.). -ALWAYS (unconditionally) returns the given error, so can conveniently be wrapped -by `throw`: (throw (error! (ex-info ...)), etc. Default kind: `:error` Default level: `:error` +Returns: + ALWAYS (unconditionally) returns the given error, so can conveniently be + wrapped by `throw`: (throw (error! (ex-info ...)), etc. Examples: diff --git a/main/resources/signal-docstrings/event!.txt b/main/resources/signal-docstrings/event!.txt index 36069d6..5e596b6 100644 --- a/main/resources/signal-docstrings/event!.txt +++ b/main/resources/signal-docstrings/event!.txt @@ -1,8 +1,10 @@ "Event" signal creator, emphasizing id + (optional level). -Returns true iff signal was created (allowed by filtering). Default kind: `:event` Default level: `:info` +Returns: + - For `event!` variant: nil, unconditionally. + - For `event!?` variant: true iff signal was created (allowed by filtering). When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to diff --git a/main/resources/signal-docstrings/log!.txt b/main/resources/signal-docstrings/log!.txt index 10bb15c..2980641 100644 --- a/main/resources/signal-docstrings/log!.txt +++ b/main/resources/signal-docstrings/log!.txt @@ -1,8 +1,10 @@ "Log" signal creator, emphasizing (optional level) + message. -Returns true iff signal was created (allowed by filtering). Default kind: `:log` Default level: `:info` +Returns: + - For `log!` variant: nil, unconditionally. + - For `log!?` variant: true iff signal was created (allowed by filtering). When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to diff --git a/main/resources/signal-docstrings/signal!.txt b/main/resources/signal-docstrings/signal!.txt index 1075706..e70b354 100644 --- a/main/resources/signal-docstrings/signal!.txt +++ b/main/resources/signal-docstrings/signal!.txt @@ -1,12 +1,11 @@ Low-level "generic" signal creator for creating signals of any "kind". Takes a single map of options [2] with compile-time keys. -Return value depends on options: - - If given `:run` form: unconditionally returns run value, or rethrows run error. - - Otherwise: returns true iff signal was created (allowed by filtering). - Default kind: `:generic` (feel free to change!) Default level: `:info` +Returns: + - If given `:run` form: unconditionally returns run value, or rethrows run error. + - Otherwise: returns true iff signal was created (allowed by filtering). When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to diff --git a/main/resources/signal-docstrings/signal-creators.txt b/main/resources/signal-docstrings/signal-creators.txt index b9b3367..99ed5c5 100644 --- a/main/resources/signal-docstrings/signal-creators.txt +++ b/main/resources/signal-docstrings/signal-creators.txt @@ -14,13 +14,14 @@ various keys: Creators vary only in in their default options and call APIs (expected args and return values), making them more/less convenient for certain use cases: - `signal!` ------- opts => allowed? / unconditional run result (value or throw) - `event!` -------- id + ?level => allowed? - `log!` ---------- ?level + msg => allowed? - `trace!` -------- ?id + run => unconditional run result (value or throw) - `spy!` ---------- ?level + run => unconditional run result (value or throw) - `error!` -------- ?id + error => unconditional given error - `catch->error!` - ?id + run => unconditional run value or ?catch-val + `log!` ------------- ?level + msg => nil + `event!` ----------- id + ?level => nil + `trace!` ----------- ?id + run => run result (value or throw) + `spy!` ------------- ?level + run => run result (value or throw) + `error!` ----------- ?id + error => given error + `catch->error!` ---- ?id + run => run value or ?catch-val + `uncaught->error!` - ?id => nil + `signal!` ---------- opts => allowed? / run result (value or throw) - `log!` and `event!` are both good default/general-purpose signal creators. - `log!` emphasizes messages, while `event!` emphasizes ids. diff --git a/main/resources/signal-docstrings/spy!.txt b/main/resources/signal-docstrings/spy!.txt index 4330950..5a09701 100644 --- a/main/resources/signal-docstrings/spy!.txt +++ b/main/resources/signal-docstrings/spy!.txt @@ -1,8 +1,8 @@ "Spy" signal creator, emphasizing (optional level) + form to run. -ALWAYS (unconditionally) returns run value, or rethrows run error. Default kind: `:spy` Default level: `:info` +Returns: ALWAYS (unconditionally) returns run value, or rethrows run error. When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to diff --git a/main/resources/signal-docstrings/trace!.txt b/main/resources/signal-docstrings/trace!.txt index 74c202e..c1250fe 100644 --- a/main/resources/signal-docstrings/trace!.txt +++ b/main/resources/signal-docstrings/trace!.txt @@ -1,8 +1,8 @@ "Trace" signal creator, emphasizing (optional id) + form to run. -ALWAYS (unconditionally) returns run value, or rethrows run error. Default kind: `:trace` Default level: `:info` (intentionally NOT `:trace`!) +Returns: ALWAYS (unconditionally) returns run value, or rethrows run error. When filtering conditions are met [4], creates a Telemere signal [3] and dispatches it to registered handlers for processing (e.g. writing to diff --git a/main/src/taoensso/telemere.cljc b/main/src/taoensso/telemere.cljc index 2969cd6..6f85d2d 100644 --- a/main/src/taoensso/telemere.cljc +++ b/main/src/taoensso/telemere.cljc @@ -197,14 +197,14 @@ (comment (enc/qb 1e6 (force *otel-tracer*))) ; 51.23 ;;;; Signal creators -;; - signal! ---------- opts => allowed? / unconditional run result (value or throw) -;; - event! ----------- id + ?level => allowed? -;; - log! ------------- ?level + msg => allowed? -;; - trace! ----------- ?id + run => unconditional run result (value or throw) -;; - spy! ------------- ?level + run => unconditional run result (value or throw) -;; - error! ----------- ?id + error => unconditional given error -;; - catch->error! ---- ?id + run => unconditional run value or ?catch-val +;; - log! ------------- ?level + msg => nil +;; - event! ----------- id + ?level => nil +;; - trace! ----------- ?id + run => run result (value or throw) +;; - spy! ------------- ?level + run => run result (value or throw) +;; - error! ----------- ?id + error => given error +;; - catch->error! ---- ?id + run => run value or ?catch-val ;; - uncaught->error! - ?id => nil +;; - signal! ---------- opts => allowed? / run result (value or throw) #?(:clj (defn- args->opts [args] @@ -251,28 +251,46 @@ (merge m v) (assoc m k v))))) -#?(:clj - (let [base-opts {:kind :event, :level :info}] - (defmacro event! - "id + ?level => allowed? Note unique arg order: [x opts] rather than [opts x]!" - {:doc (impl/signal-docstring :event!) - :arglists (impl/signal-arglists :event!)} - ([ opts-or-id] `(impl/signal! ~(merge-or-assoc-opts base-opts &form :id opts-or-id))) - ([id opts-or-level] `(impl/signal! ~(assoc (merge-or-assoc-opts base-opts &form :level opts-or-level) :id id)))))) - -(comment (:coords (with-signal (event! ::my-id :info)))) - #?(:clj (let [base-opts {:kind :log, :level :info}] - (defmacro log! + (defmacro log!? "?level + msg => allowed?" {:doc (impl/signal-docstring :log!) :arglists (impl/signal-arglists :log!)} ([opts-or-msg ] `(impl/signal! ~(merge-or-assoc-opts base-opts &form :msg opts-or-msg))) ([opts-or-level msg] `(impl/signal! ~(assoc (merge-or-assoc-opts base-opts &form :level opts-or-level) :msg msg)))))) +(comment (:coords (with-signal (log!? :info "My msg")))) + +#?(:clj + (defmacro log! + "Like `log!?` but always returns nil." + {:doc (impl/signal-docstring :log!) + :arglists (impl/signal-arglists :log!)} + [& args] `(do ~(truss/keep-callsite `(log!? ~@args)) nil))) + (comment (:coords (with-signal (log! :info "My msg")))) +#?(:clj + (let [base-opts {:kind :event, :level :info}] + (defmacro event!? + "id + ?level => allowed? Note unique arg order: [x opts] rather than [opts x]!" + {:doc (impl/signal-docstring :event!) + :arglists (impl/signal-arglists :event!)} + ([ opts-or-id] `(impl/signal! ~(merge-or-assoc-opts base-opts &form :id opts-or-id))) + ([id opts-or-level] `(impl/signal! ~(assoc (merge-or-assoc-opts base-opts &form :level opts-or-level) :id id)))))) + +(comment (:coords (with-signal (event!? ::my-id :info)))) + +#?(:clj + (defmacro event! + "Like `event!?` but always returns nil." + {:doc (impl/signal-docstring :event!) + :arglists (impl/signal-arglists :event!)} + [& args] `(do ~(truss/keep-callsite `(event!? ~@args)) nil))) + +(comment (:coords (with-signal (event! ::my-id :info)))) + #?(:clj (let [base-opts {:kind :trace, :level :info, :msg `impl/default-trace-msg}] (defmacro trace! diff --git a/main/src/taoensso/telemere/impl.cljc b/main/src/taoensso/telemere/impl.cljc index 138c3dc..0c1b87f 100644 --- a/main/src/taoensso/telemere/impl.cljc +++ b/main/src/taoensso/telemere/impl.cljc @@ -405,16 +405,6 @@ sample-rate kind ns id level when rate-limit rate-limit-by, ctx ctx+ parent root trace?, do let data msg error run & kvs]}]) - :event! ; id + ?level => allowed? - '([opts-or-id] - [id level] - [id - {:as opts-map :keys - [#_elide? #_allow? #_callsite-id, - elidable? coords inst uid middleware middleware+, - sample-rate kind ns id level when rate-limit rate-limit-by, - ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}]) - :log! ; ?level + msg => allowed? '([opts-or-msg] [level msg] @@ -425,6 +415,16 @@ ctx ctx+ parent root trace?, do let data msg error #_run & kvs]} msg]) + :event! ; id + ?level => allowed? + '([opts-or-id] + [id level] + [id + {:as opts-map :keys + [#_elide? #_allow? #_callsite-id, + elidable? coords inst uid middleware middleware+, + sample-rate kind ns id level when rate-limit rate-limit-by, + ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}]) + :trace! ; ?id + run => unconditional run result (value or throw) '([opts-or-run] [id run] @@ -532,7 +532,7 @@ #?(:clj (defmacro signal! "Generic low-level signal creator. Wrapped for public API." - ([ opts] (truss/keep-callsite `(signal!? nil ~opts))) + ([ opts] (truss/keep-callsite `(signal! nil ~opts))) ([base-opts opts] (valid-opts! (or base-opts {})) (valid-opts! (or opts {})) diff --git a/main/test/taoensso/telemere_tests.cljc b/main/test/taoensso/telemere_tests.cljc index f2583b3..3f5352a 100644 --- a/main/test/taoensso/telemere_tests.cljc +++ b/main/test/taoensso/telemere_tests.cljc @@ -574,19 +574,19 @@ ;;;; (deftest _common-signals - [(testing "event!" ; id + ?level => allowed? - [(let [{rv :value, [sv] :signals} (with-sigs (tel/event! :id1 ))] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :info, :id :id1}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/event! :id1 :warn)) ] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :warn, :id :id1}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/event! :id1 {:level :warn}))] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :warn, :id :id1}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/event! {:id :id1, :level :warn}))] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :warn, :id :id1}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/event! :id1 {:allow? false})) ] [(is (= rv nil)) (is (nil? sv))])]) + [(testing "event!?" ; id + ?level => allowed? + [(let [{rv :value, [sv] :signals} (with-sigs (tel/event!? :id1 ))] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :info, :id :id1}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/event!? :id1 :warn)) ] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :warn, :id :id1}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/event!? :id1 {:level :warn}))] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :warn, :id :id1}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/event!? {:id :id1, :level :warn}))] [(is (= rv true)) (is (sm? sv {:kind :event, :coords coords?, :level :warn, :id :id1}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/event!? :id1 {:allow? false})) ] [(is (= rv nil)) (is (nil? sv))])]) - (testing "log!" ; ?level + msg => allowed? - [(let [{rv :value, [sv] :signals} (with-sigs (tel/log! "msg")) ] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :info}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/log! :warn "msg")) ] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :warn}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/log! {:level :warn} "msg")) ] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :warn}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/log! {:level :warn, :msg "msg"}))] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :warn}))]) - (let [{rv :value, [sv] :signals} (with-sigs (tel/log! {:allow? false} "msg")) ] [(is (= rv nil)) (is (nil? sv))])]) + (testing "log!?" ; ?level + msg => allowed? + [(let [{rv :value, [sv] :signals} (with-sigs (tel/log!? "msg")) ] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :info}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/log!? :warn "msg")) ] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :warn}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/log!? {:level :warn} "msg")) ] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :warn}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/log!? {:level :warn, :msg "msg"}))] [(is (= rv true)) (is (sm? sv {:kind :log, :coords coords?, :msg_ "msg", :level :warn}))]) + (let [{rv :value, [sv] :signals} (with-sigs (tel/log!? {:allow? false} "msg")) ] [(is (= rv nil)) (is (nil? sv))])]) (testing "trace!" ; ?id + run => unconditional run result (value or throw) [(let [{rv :value, [sv] :signals} (with-sigs (tel/trace! (+ 1 2))) ] [(is (= rv 3)) (is (sm? sv {:kind :trace, :coords coords?, :level :info, :id nil, :msg_ "(+ 1 2) => 3"}))]) diff --git a/wiki/1-Getting-started.md b/wiki/1-Getting-started.md index 9f95a9e..e152a4e 100644 --- a/wiki/1-Getting-started.md +++ b/wiki/1-Getting-started.md @@ -131,13 +131,13 @@ Use whichever signal creator is most convenient for your needs: | Name | Kind | Args | Returns | | :---------------------------------------------------------------------------------------------------------- | :--------- | :--------------- | :--------------------------- | -| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `:generic` | `opts` | Depends on opts | -| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` + `?level` | Signal allowed? | -| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `?level` + `msg` | Signal allowed? | +| [`log!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#log!) | `:log` | `?level` + `msg` | nil | +| [`event!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#event!) | `:event` | `id` + `?level` | nil | | [`trace!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#trace!) | `:trace` | `?id` + `run` | Form result | | [`spy!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#spy!) | `:spy` | `?level` + `run` | Form result | | [`error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#error!) | `:error` | `?id` + `error` | Given error | | [`catch->error!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#catch-%3Eerror!) | `:error` | `?id` | Form value or given fallback | +| [`signal!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#signal!) | `:generic` | `opts` | Depends on opts | - See relevant docstrings (links above) for usage info. - See [`help:signal-creators`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-creators) for more about signal creators.