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

[mod] Rename "rate-limit" -> "limit"

Browse source 
Users caught by this change should receive a clear compile-time error.

Apologies for the nuissance!! This change is part of a final review
of names before the release of v1 final.
This commit is contained in:
Peter Taoussanis 2025-03-10 11:01:08 +01:00
parent 1f4b49a21a
commit f37f54e1da
8 changed files with 51 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
README.md
View file

@ -72,12 +72,12 @@ It enables you to write code that is **information-verbose by default**.
;; Getting fancy (all costs are conditional!) ;; Getting fancy (all costs are conditional!)
(t/log! (t/log!
{:level :debug {:level :debug
:sample 0.75 ; 75% sampling (noop 25% of the time) :sample 0.75 ; 75% sampling (noop 25% of the time)
:when (my-conditional) :when (my-conditional)
:rate-limit {"1 per sec" [1 1000] :limit {"1 per sec" [1 1000]
"5 per min" [5 60000]} "5 per min" [5 60000]} ; Rate limit
:rate-limit-by my-user-ip-address ; Optional rate-limit scope :limit-by my-user-ip-address ; Rate limit scope
:do (inc-my-metric!) :do (inc-my-metric!)
:let :let
@ -146,11 +146,11 @@ It enables you to write code that is **information-verbose by default**.
([] (println "Handler has shut down"))) ([] (println "Handler has shut down")))
{:async {:mode :dropping, :buffer-size 1024, :n-threads 1} {:async {:mode :dropping, :buffer-size 1024, :n-threads 1}
:priority 100 :priority 100
:sample 0.5 :sample 0.5
:min-level :info :min-level :info
:ns-filter {:disallow "taoensso.*"} :ns-filter {:disallow "taoensso.*"}
:rate-limit {"1 per sec" [1 1000]} :limit {"1 per sec" [1 1000]}
;; See `t/help:handler-dispatch-options` for more ;; See `t/help:handler-dispatch-options` for more
}) })
@ -205,7 +205,7 @@ It enables you to write code that is **information-verbose by default**.
- Unmatched [environmental config](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:environmental-config) support: JVM properties, environment variables, or classpath resources. Per platform, or cross-platform. - Unmatched [environmental config](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:environmental-config) support: JVM properties, environment variables, or classpath resources. Per platform, or cross-platform.
- Unmatched [filtering](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:filters) support: by namespace, id pattern, level, level by namespace pattern, etc. At runtime and compile-time. - Unmatched [filtering](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:filters) support: by namespace, id pattern, level, level by namespace pattern, etc. At runtime and compile-time.
- Fully [configurable](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options) **a/sync dispatch support**: blocking, dropping, sliding, etc. - Fully [configurable](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:handler-dispatch-options) **a/sync dispatch support**: blocking, dropping, sliding, etc.
- Turn-key **sampling**, **rate-limiting**, and **back-pressure monitoring** with sensible defaults. - Turn-key **sampling**, **rate limiting**, and **back-pressure monitoring** with sensible defaults.
## Comparisons ## Comparisons
@ -279,7 +279,7 @@ Telemere is optimized for *real-world* performance. This means **prioritizing fl
Large applications can produce absolute *heaps* of data, not all equally valuable. Quickly processing infinite streams of unmanageable junk is an anti-pattern. As scale and complexity increase, it becomes more important to **strategically plan** what data to collect, when, in what quantities, and how to manage it. Large applications can produce absolute *heaps* of data, not all equally valuable. Quickly processing infinite streams of unmanageable junk is an anti-pattern. As scale and complexity increase, it becomes more important to **strategically plan** what data to collect, when, in what quantities, and how to manage it.
Telemere is designed to help with all that. It offers [rich data](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-content) and unmatched [filtering](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:filters) support - including per-signal and per-handler **sampling** and **rate-limiting**, and zero cost compile-time filtering. Telemere is designed to help with all that. It offers [rich data](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-content) and unmatched [filtering](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:filters) support - including per-signal and per-handler **sampling** and **rate limiting**, and zero cost compile-time filtering.
Use these to ensure that you're not capturing useless/low-value/high-noise information in production! With appropriate planning, Telemere is designed to scale to systems of any size and complexity. Use these to ensure that you're not capturing useless/low-value/high-noise information in production! With appropriate planning, Telemere is designed to scale to systems of any size and complexity.

28
examples.cljc
View file

@ -28,12 +28,12 @@
;; Getting fancy (all costs are conditional!) ;; Getting fancy (all costs are conditional!)
(t/log! (t/log!
{:level :debug {:level :debug
:sample 0.75 ; 75% sampling (noop 25% of the time) :sample 0.75 ; 75% sampling (noop 25% of the time)
:when (my-conditional) :when (my-conditional)
:rate-limit {"1 per sec" [1 1000] :limit {"1 per sec" [1 1000]
"5 per min" [5 60000]} "5 per min" [5 60000]} ; Rate limit
:rate-limit-by my-user-ip-address ; Optional rate-limit scope :limit-by my-user-ip-address ; Rate limit scope
:do (inc-my-metric!) :do (inc-my-metric!)
:let :let
@ -88,11 +88,11 @@
([] (println "Handler has shut down"))) ([] (println "Handler has shut down")))
{:async {:mode :dropping, :buffer-size 1024, :n-threads 1} {:async {:mode :dropping, :buffer-size 1024, :n-threads 1}
:priority 100 :priority 100
:sample 0.5 :sample 0.5
:min-level :info :min-level :info
:ns-filter {:disallow "taoensso.*"} :ns-filter {:disallow "taoensso.*"}
:rate-limit {"1 per sec" [1 1000]} :limit {"1 per sec" [1 1000]}
;; See `t/help:handler-dispatch-options` for more ;; See `t/help:handler-dispatch-options` for more
}) })
@ -290,7 +290,7 @@
(with-meta handler-fn (with-meta handler-fn
{:dispatch-opts {:dispatch-opts
{:min-level :info {:min-level :info
:rate-limit :limit
[[1 1000] ; Max 1 signal per second [[1 1000] ; Max 1 signal per second
[10 60000] ; Max 10 signals per minute [10 60000] ; Max 10 signals per minute
]}})))) ]}}))))
@ -360,8 +360,8 @@
;; With sampling 50% and 1/sec rate limiting ;; With sampling 50% and 1/sec rate limiting
(t/log! (t/log!
{:sample 0.5 {:sample 0.5
:rate-limit {"1 per sec" [1 1000]}} :limit {"1 per sec" [1 1000]}}
"This signal will be sampled and rate limited") "This signal will be sampled and rate limited")
;; Several signal creators are available for convenience. ;; Several signal creators are available for convenience.

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

@ -27,10 +27,10 @@ All options are available for all signal creator calls:
`:elidable?` --- Should signal be subject to compile-time elision? (Default: true) `:elidable?` --- Should signal be subject to compile-time elision? (Default: true)
`:trace?` ------ Should tracing be enabled for `:run` form? `:trace?` ------ Should tracing be enabled for `:run` form?
`:sample` ------ Optional sample rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all) `:sample` ------ Sample ?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 `:limit` ------- Rate limit ?spec 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!) `:limit-by` ---- When present, rate limits will be enforced independently for each value (any Clojure value!)
`:xfn` --------- Optional transform (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-xfn` `:xfn` --------- Optional transform (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-xfn`
`:xfn+` -------- Optional extra transform (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-xfn+` `:xfn+` -------- Optional extra transform (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-xfn+`

2
main/src/taoensso/telemere.cljc
View file

@ -238,7 +238,7 @@
Allows you to use Telemere's rich filtering system for conditionally Allows you to use Telemere's rich filtering system for conditionally
executing arbitrary code. Also handy for batching multiple signals executing arbitrary code. Also handy for batching multiple signals
under a single set of conditions (incl. rate-limiting, sampling, etc.): under a single set of conditions (incl. sampling, rate limiting, etc.):
;; Logs exactly 2 or 0 messages (never 1): ;; Logs exactly 2 or 0 messages (never 1):
(when (signal-allowed? {:level :info, :sample 0.5}) (when (signal-allowed? {:level :info, :sample 0.5})

20
main/src/taoensso/telemere/impl.cljc
View file

@ -394,7 +394,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, ; Undocumented [#_elide? #_allow? #_callsite-id, ; Undocumented
elidable? coords #_inst #_uid #_xfn #_xfn+, elidable? coords #_inst #_uid #_xfn #_xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
#_ctx #_ctx+ #_parent #_root #_trace?, #_do #_let #_data #_msg #_error #_run #_& #_kvs]}]) #_ctx #_ctx+ #_parent #_root #_trace?, #_do #_let #_data #_msg #_error #_run #_& #_kvs]}])
:signal! ; opts => allowed? / run result (value or throw) :signal! ; opts => allowed? / run result (value or throw)
@ -402,7 +402,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, ; Undocumented [#_elide? #_allow? #_callsite-id, ; Undocumented
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx ctx+ parent root trace?, do let data msg error run & kvs]}]) ctx ctx+ parent root trace?, do let data msg error run & kvs]}])
:log! ; ?level + msg => nil / allowed? :log! ; ?level + msg => nil / allowed?
@ -411,7 +411,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, [#_elide? #_allow? #_callsite-id,
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx 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])
@ -422,7 +422,7 @@
{:as opts-map :keys {:as opts-map :keys
[#_elide? #_allow? #_callsite-id, [#_elide? #_allow? #_callsite-id,
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}]) ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}])
:trace! ; ?id + run => run result (value or throw) :trace! ; ?id + run => run result (value or throw)
@ -431,7 +431,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, [#_elide? #_allow? #_callsite-id,
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx ctx+ parent root trace?, do let data msg error run & kvs]} ctx ctx+ parent root trace?, do let data msg error run & kvs]}
run]) run])
@ -441,7 +441,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, [#_elide? #_allow? #_callsite-id,
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx ctx+ parent root trace?, do let data msg error run & kvs]} ctx ctx+ parent root trace?, do let data msg error run & kvs]}
run]) run])
@ -451,7 +451,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, [#_elide? #_allow? #_callsite-id,
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx 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])
@ -461,7 +461,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, catch-val, [#_elide? #_allow? #_callsite-id, catch-val,
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx ctx+ parent root trace?, do let data msg error #_run & kvs]} ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}
run]) run])
@ -471,7 +471,7 @@
[{:as opts-map :keys [{:as opts-map :keys
[#_elide? #_allow? #_callsite-id, [#_elide? #_allow? #_callsite-id,
elidable? coords inst uid xfn xfn+, elidable? coords inst uid xfn xfn+,
sample kind ns id level when rate-limit rate-limit-by, sample kind ns id level when limit limit-by,
ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}]) ctx ctx+ parent root trace?, do let data msg error #_run & kvs]}])
(truss/unexpected-arg! macro-id)))) (truss/unexpected-arg! macro-id))))
@ -627,7 +627,7 @@
(not-empty (not-empty
(dissoc opts (dissoc opts
:elidable? :coords :inst :uid :xfn :xfn+, :elidable? :coords :inst :uid :xfn :xfn+,
:sample :ns :kind :id :level :filter :when #_:rate-limit #_:rate-limit-by, :sample :ns :kind :id :level :filter :when #_:limit #_:limit-by,
:ctx :ctx+ :parent #_:trace?, :do :let :data :msg :error, :ctx :ctx+ :parent #_:trace?, :do :let :data :msg :error,
:run :run-form :run-val, :elide? :allow? #_:callsite-id :otel/context)) :run :run-form :run-val, :elide? :allow? #_:callsite-id :otel/context))

9
main/src/taoensso/telemere/postal.clj
View file

@ -15,12 +15,11 @@
(def default-dispatch-opts (def default-dispatch-opts
{:min-level :info {:min-level :info
:rate-limit :limit
[[5 (enc/msecs :mins 1)] [[5 (enc/msecs :mins 1)]
[10 (enc/msecs :mins 15)] [10 (enc/msecs :mins 15)]
[15 (enc/msecs :hours 1)] [15 (enc/msecs :hours 1)]
[30 (enc/msecs :hours 6)] [30 (enc/msecs :hours 6)]]})
]})
(defn handler:postal (defn handler:postal
"Alpha, subject to change. "Alpha, subject to change.
@ -34,8 +33,8 @@
Useful for emailing important alerts to admins, etc. Useful for emailing important alerts to admins, etc.
Default handler dispatch options (override when calling `add-handler!`): Default handler dispatch options (override when calling `add-handler!`):
`:min-level` - `:info` `:min-level` - `:info`
`:rate-limit` - `:limit` -
[[5 (enc/msecs :mins 1)] ; Max 5 emails in 1 min [[5 (enc/msecs :mins 1)] ; Max 5 emails in 1 min
[10 (enc/msecs :mins 15)] ; Max 10 emails in 15 mins [10 (enc/msecs :mins 15)] ; Max 10 emails in 15 mins
[15 (enc/msecs :hours 1)] ; Max 15 emails in 1 hour [15 (enc/msecs :hours 1)] ; Max 15 emails in 1 hour

9
main/src/taoensso/telemere/slack.clj
View file

@ -15,12 +15,11 @@
(def default-dispatch-opts (def default-dispatch-opts
{:min-level :info {:min-level :info
:rate-limit :limit
[[5 (enc/msecs :mins 1)] [[5 (enc/msecs :mins 1)]
[10 (enc/msecs :mins 15)] [10 (enc/msecs :mins 15)]
[15 (enc/msecs :hours 1)] [15 (enc/msecs :hours 1)]
[30 (enc/msecs :hours 6)] [30 (enc/msecs :hours 6)]]})
]})
(defn handler:slack (defn handler:slack
"Alpha, subject to change. "Alpha, subject to change.
@ -34,8 +33,8 @@
Can output signals as human or machine-readable (edn, JSON) strings. Can output signals as human or machine-readable (edn, JSON) strings.
Default handler dispatch options (override when calling `add-handler!`): Default handler dispatch options (override when calling `add-handler!`):
`:min-level` - `:info` `:min-level` - `:info`
`:rate-limit` - `:limit` -
[[5 (enc/msecs :mins 1)] ; Max 5 posts in 1 min [[5 (enc/msecs :mins 1)] ; Max 5 posts in 1 min
[10 (enc/msecs :mins 15)] ; Max 10 posts in 15 mins [10 (enc/msecs :mins 15)] ; Max 10 posts in 15 mins
[15 (enc/msecs :hours 1)] ; Max 15 posts in 1 hour [15 (enc/msecs :hours 1)] ; Max 15 posts in 1 hour

4
wiki/4-Handlers.md
View file

@ -234,8 +234,8 @@ If you're making a customizable handler for use by others, it's often handy to d
(with-meta handler-fn (with-meta handler-fn
{:dispatch-opts {:dispatch-opts
{:min-level :info {:min-level :info
:rate-limit :limit
[[1 1000] ; Max 1 signal per second [[1 1000] ; Max 1 signal per second
[10 60000] ; Max 10 signals per minute [10 60000] ; Max 10 signals per minute
]}})))) ]}}))))