diff --git a/README.md b/README.md index c9b6c67..579658d 100644 --- a/README.md +++ b/README.md @@ -72,12 +72,12 @@ It enables you to write code that is **information-verbose by default**. ;; Getting fancy (all costs are conditional!) (t/log! - {:level :debug - :sample 0.75 ; 75% sampling (noop 25% of the time) - :when (my-conditional) - :rate-limit {"1 per sec" [1 1000] - "5 per min" [5 60000]} - :rate-limit-by my-user-ip-address ; Optional rate-limit scope + {:level :debug + :sample 0.75 ; 75% sampling (noop 25% of the time) + :when (my-conditional) + :limit {"1 per sec" [1 1000] + "5 per min" [5 60000]} ; Rate limit + :limit-by my-user-ip-address ; Rate limit scope :do (inc-my-metric!) :let @@ -146,11 +146,11 @@ It enables you to write code that is **information-verbose by default**. ([] (println "Handler has shut down"))) {:async {:mode :dropping, :buffer-size 1024, :n-threads 1} - :priority 100 - :sample 0.5 - :min-level :info - :ns-filter {:disallow "taoensso.*"} - :rate-limit {"1 per sec" [1 1000]} + :priority 100 + :sample 0.5 + :min-level :info + :ns-filter {:disallow "taoensso.*"} + :limit {"1 per sec" [1 1000]} ;; 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 [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. -- 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 @@ -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. -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. diff --git a/examples.cljc b/examples.cljc index 2f1c6ad..5f152f8 100644 --- a/examples.cljc +++ b/examples.cljc @@ -28,12 +28,12 @@ ;; Getting fancy (all costs are conditional!) (t/log! - {:level :debug - :sample 0.75 ; 75% sampling (noop 25% of the time) - :when (my-conditional) - :rate-limit {"1 per sec" [1 1000] - "5 per min" [5 60000]} - :rate-limit-by my-user-ip-address ; Optional rate-limit scope + {:level :debug + :sample 0.75 ; 75% sampling (noop 25% of the time) + :when (my-conditional) + :limit {"1 per sec" [1 1000] + "5 per min" [5 60000]} ; Rate limit + :limit-by my-user-ip-address ; Rate limit scope :do (inc-my-metric!) :let @@ -88,11 +88,11 @@ ([] (println "Handler has shut down"))) {:async {:mode :dropping, :buffer-size 1024, :n-threads 1} - :priority 100 - :sample 0.5 - :min-level :info - :ns-filter {:disallow "taoensso.*"} - :rate-limit {"1 per sec" [1 1000]} + :priority 100 + :sample 0.5 + :min-level :info + :ns-filter {:disallow "taoensso.*"} + :limit {"1 per sec" [1 1000]} ;; See `t/help:handler-dispatch-options` for more }) @@ -290,7 +290,7 @@ (with-meta handler-fn {:dispatch-opts {:min-level :info - :rate-limit + :limit [[1 1000] ; Max 1 signal per second [10 60000] ; Max 10 signals per minute ]}})))) @@ -360,8 +360,8 @@ ;; With sampling 50% and 1/sec rate limiting (t/log! - {:sample 0.5 - :rate-limit {"1 per sec" [1 1000]}} + {:sample 0.5 + :limit {"1 per sec" [1 1000]}} "This signal will be sampled and rate limited") ;; Several signal creators are available for convenience. diff --git a/main/resources/signal-docstrings/signal-options.txt b/main/resources/signal-docstrings/signal-options.txt index 0f64698..e54c208 100644 --- a/main/resources/signal-docstrings/signal-options.txt +++ b/main/resources/signal-docstrings/signal-options.txt @@ -27,10 +27,10 @@ All options are available for all signal creator calls: `:elidable?` --- Should signal be subject to compile-time elision? (Default: true) `: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 -`: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!) +`:limit` ------- Rate limit ?spec given to `taoensso.telemere/rate-limiter`, see its docstring for details +`: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 extra transform (fn [signal]) => ?modified-signal to apply when signal is created, as per `with-xfn+` diff --git a/main/src/taoensso/telemere.cljc b/main/src/taoensso/telemere.cljc index 1e375d9..66c11f3 100644 --- a/main/src/taoensso/telemere.cljc +++ b/main/src/taoensso/telemere.cljc @@ -238,7 +238,7 @@ Allows you to use Telemere's rich filtering system for conditionally 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): (when (signal-allowed? {:level :info, :sample 0.5}) diff --git a/main/src/taoensso/telemere/impl.cljc b/main/src/taoensso/telemere/impl.cljc index f41ba59..6d309af 100644 --- a/main/src/taoensso/telemere/impl.cljc +++ b/main/src/taoensso/telemere/impl.cljc @@ -394,7 +394,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, ; Undocumented 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]}]) :signal! ; opts => allowed? / run result (value or throw) @@ -402,7 +402,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, ; Undocumented 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]}]) :log! ; ?level + msg => nil / allowed? @@ -411,7 +411,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, 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]} msg]) @@ -422,7 +422,7 @@ {:as opts-map :keys [#_elide? #_allow? #_callsite-id, 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]}]) :trace! ; ?id + run => run result (value or throw) @@ -431,7 +431,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, 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]} run]) @@ -441,7 +441,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, 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]} run]) @@ -451,7 +451,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, 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]} error]) @@ -461,7 +461,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, catch-val, 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]} run]) @@ -471,7 +471,7 @@ [{:as opts-map :keys [#_elide? #_allow? #_callsite-id, 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]}]) (truss/unexpected-arg! macro-id)))) @@ -627,7 +627,7 @@ (not-empty (dissoc opts :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, :run :run-form :run-val, :elide? :allow? #_:callsite-id :otel/context)) diff --git a/main/src/taoensso/telemere/postal.clj b/main/src/taoensso/telemere/postal.clj index ccc2c2b..eed41ea 100644 --- a/main/src/taoensso/telemere/postal.clj +++ b/main/src/taoensso/telemere/postal.clj @@ -15,12 +15,11 @@ (def default-dispatch-opts {:min-level :info - :rate-limit + :limit [[5 (enc/msecs :mins 1)] [10 (enc/msecs :mins 15)] [15 (enc/msecs :hours 1)] - [30 (enc/msecs :hours 6)] - ]}) + [30 (enc/msecs :hours 6)]]}) (defn handler:postal "Alpha, subject to change. @@ -34,8 +33,8 @@ Useful for emailing important alerts to admins, etc. Default handler dispatch options (override when calling `add-handler!`): - `:min-level` - `:info` - `:rate-limit` - + `:min-level` - `:info` + `:limit` - [[5 (enc/msecs :mins 1)] ; Max 5 emails in 1 min [10 (enc/msecs :mins 15)] ; Max 10 emails in 15 mins [15 (enc/msecs :hours 1)] ; Max 15 emails in 1 hour diff --git a/main/src/taoensso/telemere/slack.clj b/main/src/taoensso/telemere/slack.clj index 6551085..4dc62e7 100644 --- a/main/src/taoensso/telemere/slack.clj +++ b/main/src/taoensso/telemere/slack.clj @@ -15,12 +15,11 @@ (def default-dispatch-opts {:min-level :info - :rate-limit + :limit [[5 (enc/msecs :mins 1)] [10 (enc/msecs :mins 15)] [15 (enc/msecs :hours 1)] - [30 (enc/msecs :hours 6)] - ]}) + [30 (enc/msecs :hours 6)]]}) (defn handler:slack "Alpha, subject to change. @@ -34,8 +33,8 @@ Can output signals as human or machine-readable (edn, JSON) strings. Default handler dispatch options (override when calling `add-handler!`): - `:min-level` - `:info` - `:rate-limit` - + `:min-level` - `:info` + `:limit` - [[5 (enc/msecs :mins 1)] ; Max 5 posts in 1 min [10 (enc/msecs :mins 15)] ; Max 10 posts in 15 mins [15 (enc/msecs :hours 1)] ; Max 15 posts in 1 hour diff --git a/wiki/4-Handlers.md b/wiki/4-Handlers.md index d596ad1..9c09cab 100644 --- a/wiki/4-Handlers.md +++ b/wiki/4-Handlers.md @@ -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 {:dispatch-opts - {:min-level :info - :rate-limit + {:min-level :info + :limit [[1 1000] ; Max 1 signal per second [10 60000] ; Max 10 signals per minute ]}}))))