luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2025-12-18 18:11:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

[new] Add :ctx+, :middleware+ signal options

Browse source
This commit is contained in:
Peter Taoussanis 2024-10-11 10:51:16 +02:00
parent c1e1c1e4cc
commit 5a8c407528
4 changed files with 77 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
projects/main/resources/signal-docstrings/signal-options.txt
View file

@ -15,17 +15,19 @@ Signal options (shared by all signal creators):
`:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding `:do` ---------- ?form to execute conditionally (iff signal allowed), before establishing `:let` ?binding
`:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!) `:let` --------- ?bindings to establish conditionally (iff signal allowed), BEFORE evaluating `:data` and `:msg` (useful!)
`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal
`:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal tracing info `:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal tracing info
`:root` -------- Custom ?{:keys [id uid]} to override auto (dynamic) root signal tracing info `:root` -------- Custom ?{:keys [id uid]} to override auto (dynamic) root signal tracing info
`:location` ---- Custom ?{:keys [ns line column file]} to override auto signal creator callsite location `:location` ---- Custom ?{:keys [ns line column file]} to override auto signal creator callsite location
`:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal, as per `with-ctx`
`:ctx+` -------- Custom ?val to update auto (dynamic `*ctx*`) in signal, as per `with-ctx+`
`:elidable?` --- Should signal be subject to compile-time elision? (Default: true) `:elidable?` --- Should signal be subject to compile-time elision? (Default: true)
`:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all) `:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all)
`:when` -------- Arb ?form; when present, form must return truthy to allow signal `:when` -------- Arb ?form; when present, form must return truthy to allow signal
`:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details `:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details
`:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!) `:rate-limit-by` When present, rate limits will be enforced independently for each id (any Clojure value!)
`:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created `:middleware` -- Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware`
`:middleware+` - Optional (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-middleware+`
`:trace?` ------ Should tracing be enabled for `:run` form? `:trace?` ------ Should tracing be enabled for `:run` form?
<kvs> ---------- Other arb app-level ?kvs to incl. in signal. Typically NOT included in <kvs> ---------- Other arb app-level ?kvs to incl. in signal. Typically NOT included in

51
projects/main/src/taoensso/telemere/impl.cljc
View file

@ -385,16 +385,16 @@
:signal! ; [opts] => allowed? / run result (value or throw) :signal! ; [opts] => allowed? / run result (value or throw)
'([{:as opts :keys '([{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented [#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error run & kvs]}]) ctx ctx+ parent root trace?, do let data msg error run & kvs]}])
:signal-allowed? :signal-allowed?
'([{:as opts :keys '([{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented [#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented
elidable? location #_location* #_inst #_uid #_middleware, elidable? location #_location* #_inst #_uid #_middleware #_middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
#_ctx #_parent #_root #_trace?, #_do #_let #_data #_msg #_error #_run #_& #_kvs]}]) #_ctx #_ctx+ #_parent #_root #_trace?, #_do #_let #_data #_msg #_error #_run #_& #_kvs]}])
:event! ; [id] [id level-or-opts] => allowed? :event! ; [id] [id level-or-opts] => allowed?
'([id ] '([id ]
@ -402,18 +402,18 @@
[id [id
{:as opts :keys {:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, [#_defaults #_elide? #_allow? #_expansion-id,
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error #_run & kvs]}]) ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}])
:log! ; [msg] [level-or-opts msg] => allowed? :log! ; [msg] [level-or-opts msg] => allowed?
'([ msg] '([ msg]
[level msg] [level msg]
[{:as opts :keys [{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, [#_defaults #_elide? #_allow? #_expansion-id,
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error #_run & kvs]} ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}
msg]) msg])
:error! ; [error] [id-or-opts error] => given error :error! ; [error] [id-or-opts error] => given error
@ -421,9 +421,9 @@
[id error] [id error]
[{:as opts :keys [{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, [#_defaults #_elide? #_allow? #_expansion-id,
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error #_run & kvs]} ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}
error]) error])
:trace! ; [form] [id-or-opts form] => run result (value or throw) :trace! ; [form] [id-or-opts form] => run result (value or throw)
@ -431,9 +431,9 @@
[id form] [id form]
[{:as opts :keys [{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, [#_defaults #_elide? #_allow? #_expansion-id,
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error run & kvs]} ctx ctx+ parent root trace?, do let data msg error run & kvs]}
form]) form])
:spy! ; [form] [level-or-opts form] => run result (value or throw) :spy! ; [form] [level-or-opts form] => run result (value or throw)
@ -441,9 +441,9 @@
[level form] [level form]
[{:as opts :keys [{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, [#_defaults #_elide? #_allow? #_expansion-id,
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error run & kvs]} ctx ctx+ parent root trace?, do let data msg error run & kvs]}
form]) form])
:catch->error! ; [form] [id-or-opts form] => run result (value or throw) :catch->error! ; [form] [id-or-opts form] => run result (value or throw)
@ -451,9 +451,9 @@
[id form] [id form]
[{:as opts :keys [{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, rethrow? catch-val, [#_defaults #_elide? #_allow? #_expansion-id, rethrow? catch-val,
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error #_run & kvs]} ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}
form]) form])
:uncaught->error! ; [] [id-or-opts] => nil :uncaught->error! ; [] [id-or-opts] => nil
@ -461,9 +461,9 @@
[id] [id]
[{:as opts :keys [{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, [#_defaults #_elide? #_allow? #_expansion-id,
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error #_run & kvs]}]) ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}])
(enc/unexpected-arg! macro-id)))) (enc/unexpected-arg! macro-id))))
@ -637,15 +637,22 @@
let-form (or let-form '[]) let-form (or let-form '[])
msg-form (parse-msg-form msg-form) msg-form (parse-msg-form msg-form)
ctx-form (get opts :ctx `taoensso.telemere/*ctx*) ctx-form
middleware-form (get opts :middleware `taoensso.telemere/*middleware*) (if-let [ctx+ (get opts :ctx+)]
`(taoensso.encore.signals/update-ctx taoensso.telemere/*ctx* ~ctx+)
(get opts :ctx `taoensso.telemere/*ctx*))
middleware-form
(if-let [middleware+ (get opts :middleware+)]
`(taoensso.telemere/comp-middleware taoensso.telemere/*middleware* ~middleware+)
(get opts :middleware `taoensso.telemere/*middleware*))
kvs-form kvs-form
(not-empty (not-empty
(dissoc opts (dissoc opts
:elidable? :location :location* :inst :uid :middleware, :elidable? :location :location* :inst :uid :middleware :middleware+,
:sample-rate :ns :kind :id :level :filter :when #_:rate-limit #_:rate-limit-by, :sample-rate :ns :kind :id :level :filter :when #_:rate-limit #_:rate-limit-by,
:ctx :parent #_:trace?, :do :let :data :msg :error :run, :ctx :ctx+ :parent #_:trace?, :do :let :data :msg :error :run,
:elide? :allow? #_:expansion-id :otel/context)) :elide? :allow? #_:expansion-id :otel/context))
_ ; Compile-time validation _ ; Compile-time validation

28
projects/main/test/taoensso/telemere_tests.cljc
View file

@ -232,17 +232,23 @@
(is (= @c 16) "6x run + 6x let (0x suppressed) + 4x data (2x suppressed)")])))) (is (= @c 16) "6x run + 6x let (0x suppressed) + 4x data (2x suppressed)")]))))
(testing "Dynamic bindings, etc." (testing "Dynamic bindings, etc."
[(binding[#?@(:clj [impl/*sig-spy-off-thread?* true]) [(let [sv
*dynamic-var* "foo" (binding[#?@(:clj [impl/*sig-spy-off-thread?* true])
tel/*ctx* "bar"] *dynamic-var* "dynamic-val"
(let [sv (with-sig (sig! {:level :info, :data {:*dynamic-var* *dynamic-var*, :*ctx* tel/*ctx*}}))] tel/*ctx* "ctx-val"]
(is (sm? sv {:data {:*dynamic-var* "foo", :*ctx* "bar"}}) (with-sig (sig! {:level :info, :data {:*dynamic-var* *dynamic-var*, :*ctx* tel/*ctx*}})))]
"Retain dynamic bindings in place at time of signal call"))) (is (sm? sv {:data {:*dynamic-var* "dynamic-val", :*ctx* "ctx-val"}})
"Retain dynamic bindings in place at time of signal call"))
(let [sv (with-sig (sig! {:level :info, :ctx "my-ctx"}))] (let [sv (with-sig (sig! {:level :info, :ctx "my-ctx"}))]
(is (sm? sv {:ctx "my-ctx"}) "`*ctx*` can be overridden via call opt"))]) (is (sm? sv {:ctx "my-ctx"}) "`*ctx*` can be overridden via call opt"))
(testing "Dynamic middleware (`*middleware*`)" (let [sv (binding [tel/*ctx* {:foo :bar}]
(with-sig (sig! {:level :info, :ctx+ {:baz :qux}})))]
(is (sm? sv {:ctx {:foo :bar, :baz :qux}}) "`*ctx*` can be updated via call opt"))])
(testing "Middleware"
[(testing "Dynamic middleware (`*middleware*`)"
[(is (sm? (tel/with-middleware nil (with-sig (sig! {:level :info }))) {:level :info }) "nil middleware ~ identity") [(is (sm? (tel/with-middleware nil (with-sig (sig! {:level :info }))) {:level :info }) "nil middleware ~ identity")
(is (sm? (tel/with-middleware identity (with-sig (sig! {:level :info }))) {:level :info }) "nil middleware ~ identity") (is (sm? (tel/with-middleware identity (with-sig (sig! {:level :info }))) {:level :info }) "nil middleware ~ identity")
(is (sm? (tel/with-middleware #(assoc % :foo 1) (with-sig (sig! {:level :info }))) {:level :info, :foo 1 })) (is (sm? (tel/with-middleware #(assoc % :foo 1) (with-sig (sig! {:level :info }))) {:level :info, :foo 1 }))
@ -266,6 +272,12 @@
(is (= rv5 true)) (is (nil? sv5)) (is (= rv5 true)) (is (nil? sv5))
(is (= @c 7) "3x run + 4x middleware")])) (is (= @c 7) "3x run + 4x middleware")]))
(testing "Mixed middleware"
[(let [sv
(binding [tel/*middleware* #(assoc % :foo true)]
(with-sig (sig! {:level :info, :middleware+ #(assoc % :bar true)})))]
(is (sm? sv {:foo true, :bar true})))])])
#?(:clj #?(:clj
(testing "Printing" (testing "Printing"
(let [sv1 (dissoc (with-sig (sig! {:level :info, :run (+ 1 2), :my-k1 :my-v1})) :_otel-context) (let [sv1 (dissoc (with-sig (sig! {:level :info, :run (+ 1 2), :my-k1 :my-v1})) :_otel-context)

8
projects/shell/src/taoensso/telemere/shell.cljc
View file

@ -132,9 +132,9 @@
:keys :keys
[fallback, ; Unique to shell [fallback, ; Unique to shell
#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented #_defaults #_elide? #_allow? #_expansion-id, ; Undocumented
elidable? location #_location* inst uid middleware, elidable? location #_location* inst uid middleware middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
ctx parent root trace?, do let data msg error run & kvs]}])} ctx ctx+ parent root trace?, do let data msg error run & kvs]}])}
[opts] [opts]
(if telemere-present? (if telemere-present?
@ -171,9 +171,9 @@
'([{:as opts :keys '([{:as opts :keys
[#_fallback, ; Unique to shell [#_fallback, ; Unique to shell
#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented #_defaults #_elide? #_allow? #_expansion-id, ; Undocumented
elidable? location #_location* #_inst #_uid #_middleware, elidable? location #_location* #_inst #_uid #_middleware #_middleware+,
sample-rate kind ns id level when rate-limit rate-limit-by, sample-rate kind ns id level when rate-limit rate-limit-by,
#_ctx #_parent #_root #_trace?, #_do #_let #_data #_msg #_error #_run #_& #_kvs]}])} #_ctx #_ctx+ #_parent #_root #_trace?, #_do #_let #_data #_msg #_error #_run #_& #_kvs]}])}
[opts] [opts]
(if telemere-present? (if telemere-present?