luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2026-01-15 04:19:49 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

[mod] Rename signal fields: :instant -> :inst, etc.

Browse source
This commit is contained in:
Peter Taoussanis 2024-03-28 13:18:00 +01:00
parent 45f924a1f3
commit 0f0e049993
6 changed files with 67 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
resources/signal-docstrings/signal-content.txt
View file

@ -1,23 +1,23 @@
Signals are initially maps with {:keys [instant id ns level data msg_ ...]},
Signals are initially maps with {:keys [inst id ns level data msg_ ...]},
though they can be modified by call and/or handler middleware.
Default keys:
`:schema` - Int version of signal schema (current: 1)
`:instant` - Platform instant [1] when signal was created
`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
`:schema` - Int version of signal schema (current: 1)
`:inst` - Platform instant [1] when signal was created
`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
`:msg` - Arb user-level message ?str given to signal call
`:data` - Arb user-level data ?val (usu. a map) given to signal call
`:error` - Arb user-level platform ?error [2] given to signal call
`:run-form` - Unevaluated ?form given to signal call as `:run`
`:run-val` - Successful return ?val of `:run` ?form
`:run-nsecs` - ?int nanosecs runtime of `:run` ?form
`:end-instant` - Platform ?instant [1] when `:run` ?form completed
`:run-form` - Unevaluated ?form given to signal call as `:run`
`:run-val` - Successful return ?val of `:run` ?form
`:run-nsecs`- ?int nanosecs runtime of `:run` ?form
`:end-inst` - Platform ?instant [1] when `:run` ?form completed
`:ctx` - ?val of `*ctx*` (arb user-level state) when signal was created
`:parent` - ?{:keys [id uid]} of parent signal, present in nested signals when tracing
@ -33,5 +33,5 @@ Default keys:
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
[1] Clj: `java.time.Instant`, Cljs: `js/Date`
[2] Clj: `java.lang.Throwable`, Cljs: `js/Error`
[1] `java.time.Instant` or `js/Date`
[2] `java.lang.Throwable` or `js/Error`

14
resources/signal-docstrings/signal-options.txt
View file

@ -1,10 +1,10 @@
Signal options (shared by `signal!`, `event!`, ...):
`:instant` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
`:inst` - Platform instant [1] when signal was created, ∈ #{nil :auto <user-val>}
`:level` - Signal level ∈ #{<int> :trace :debug :info :warn :error :fatal :report ...}
`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy <user-val> ...}
`:id` - ?id of signal call (common to all signals created by signal call, contrast with `:uid`)
`:uid` - ?id of signal instance (unique to each signal created by signal call, contrast with `:id`)
`:msg` - Arb user-level ?message to incl. in signal: str or vec of strs to join (with `\space`)
`:data` - Arb user-level ?data to incl. in signal: usu. a map
@ -29,5 +29,5 @@ Signal options (shared by `signal!`, `event!`, ...):
If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
[1] Clj: `java.time.Instant`, Cljs: `js/Date`
[2] Clj: `java.lang.Throwable`, Cljs: `js/Error`
[1] `java.time.Instant` or `js/Date`
[2] `java.lang.Throwable` or `js/Error`

8
slf4j/src/taoensso/telemere/slf4j.clj
View file

@ -108,7 +108,7 @@
:level (sig-level level)}))
(defn- normalized-log!
[instant level error msg-pattern args marker-names kvs]
[inst level error msg-pattern args marker-names kvs]
(when-debug (println [:slf4j/normalized-log! (sig-level level)]))
(impl/signal!
{:allow? true ; Pre-filtered by `allowed?` call
@ -117,7 +117,7 @@
:kind :log
:id :taoensso.telemere/slf4j
:level (sig-level level)
:instant instant
:inst inst
:error error
:ctx
@ -142,7 +142,7 @@
;; Modern "fluent" API calls
([^org.slf4j.event.LoggingEvent event]
(let [instant (when-let [ts (.getTimeStamp event)] (when-not (zero? ts) (java.time.Instant/ofEpochMilli ts)))
(let [inst (when-let [ts (.getTimeStamp event)] (when-not (zero? ts) (java.time.Instant/ofEpochMilli ts)))
level (.getLevel event)
error (.getThrowable event)
msg-pattern (.getMessage event)
@ -155,7 +155,7 @@
nil kvps))]
(when-debug (println [:slf4j/fluent-log-call (sig-level level)]))
(normalized-log! instant level error msg-pattern args markers kvs)))
(normalized-log! inst level error msg-pattern args markers kvs)))
;; Legacy API calls
([^org.slf4j.event.Level level error msg-pattern args marker]

60
src/taoensso/telemere/impl.cljc
View file

@ -193,11 +193,11 @@
(defrecord Signal
;; Telemere's main public data type, we avoid nesting and duplication
[^long schema instant uid,
[^long schema inst uid,
location ns line column file,
sample-rate, kind id level, ctx parent,
data msg_ error run-form run-val,
end-instant run-nsecs extra-kvs]
end-inst run-nsecs extra-kvs]
Object (toString [sig] (str "#" `Signal (into {} sig))))
@ -340,7 +340,7 @@
"Returns a new `Signal` with given opts."
^Signal
;; Note all dynamic vals passed as explicit args for better control
[instant uid,
[inst uid,
location ns line column file,
sample-rate, kind id level, ctx parent,
extra-kvs data msg_,
@ -349,9 +349,9 @@
(let [signal
(if-let [^RunResult run-result run-result]
(let [run-nsecs (.-run-nsecs run-result)
end-instant
#?(:clj (.plusNanos ^java.time.Instant instant run-nsecs)
:cljs (js/Date. (+ (.getTime instant) (/ run-nsecs 1e6))))
end-inst
#?(:clj (.plusNanos ^java.time.Instant inst run-nsecs)
:cljs (js/Date. (+ (.getTime inst) (/ run-nsecs 1e6))))
run-err (.-error run-result)
run-val (.-value run-result)
@ -360,14 +360,14 @@
(delay (str run-form " => " (or run-err run-val)))
msg_)]
(Signal. 1 instant uid,
(Signal. 1 inst uid,
location ns line column file,
sample-rate, kind id level, ctx parent,
data msg_,
run-err run-form run-val,
end-instant run-nsecs extra-kvs))
end-inst run-nsecs extra-kvs))
(Signal. 1 instant uid,
(Signal. 1 inst uid,
location ns line column file,
sample-rate, kind id level, ctx parent,
data msg_, error nil nil nil nil extra-kvs))]
@ -394,7 +394,7 @@
:signal! ; [opts] => allowed? / run result (value or throw)
'([{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, ; Undocumented
elidable? location instant uid middleware,
elidable? location inst uid middleware,
sample-rate kind ns id level when rate-limit,
ctx parent trace?, do let data msg error run & extra-kvs]}])
@ -404,7 +404,7 @@
[id
{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id,
elidable? location instant uid middleware,
elidable? location inst uid middleware,
sample-rate kind ns id level when rate-limit,
ctx parent trace?, do let data msg error #_run & extra-kvs]}])
@ -413,7 +413,7 @@
[level msg]
[{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id,
elidable? location instant uid middleware,
elidable? location inst uid middleware,
sample-rate kind ns id level when rate-limit,
ctx parent trace?, do let data msg error #_run & extra-kvs]}
msg])
@ -423,7 +423,7 @@
[id error]
[{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id,
elidable? location instant uid middleware,
elidable? location inst uid middleware,
sample-rate kind ns id level when rate-limit,
ctx parent trace?, do let data msg error #_run & extra-kvs]}
error])
@ -433,7 +433,7 @@
[id form]
[{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id,
elidable? location instant uid middleware,
elidable? location inst uid middleware,
sample-rate kind ns id level when rate-limit,
ctx parent trace?, do let data msg error run & extra-kvs]}
form])
@ -443,7 +443,7 @@
[id form]
[{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id, rethrow? catch-val,
elidable? location instant uid middleware,
elidable? location inst uid middleware,
sample-rate kind ns id level when rate-limit,
ctx parent trace?, do let data msg error #_run & extra-kvs]}
form])
@ -453,7 +453,7 @@
[id]
[{:as opts :keys
[#_defaults #_elide? #_allow? #_expansion-id,
elidable? location instant uid middleware,
elidable? location inst uid middleware,
sample-rate kind ns id level when rate-limit,
ctx parent trace?, do let data msg error #_run & extra-kvs]}])
@ -512,18 +512,18 @@
(if elide?
run-form
(let [{:keys [ns line column file]} location
{instant-form :instant
kind-form :kind
id-form :id
level-form :level} opts
{inst-form :inst
kind-form :kind
id-form :id
level-form :level} opts
trace? (get opts :trace? (boolean run-form))
uid-form (get opts :uid (when trace? :auto/uuid))
ctx-form (get opts :ctx `taoensso.telemere/*ctx*)
parent-form (get opts :parent (when trace? `taoensso.telemere.impl/*trace-parent*))
instant-form (get opts :instant :auto)
instant-form (if (= instant-form :auto) `(enc/now-inst*) instant-form)
uid-form (parse-uid-form uid-form)
trace? (get opts :trace? (boolean run-form))
uid-form (get opts :uid (when trace? :auto/uuid))
ctx-form (get opts :ctx `taoensso.telemere/*ctx*)
parent-form (get opts :parent (when trace? `taoensso.telemere.impl/*trace-parent*))
inst-form (get opts :inst :auto)
inst-form (if (= inst-form :auto) `(enc/now-inst*) inst-form)
uid-form (parse-uid-form uid-form)
;; run-fn-form (when run-form `(fn [] ~run-form))
run-result-form
(when run-form
@ -548,7 +548,7 @@
extra-kvs-form
(not-empty
(dissoc opts
:elidable? :location :instant :uid :middleware,
:elidable? :location :inst :uid :middleware,
:sample-rate :ns :kind :id :level :filter :when #_:rate-limit,
:ctx :parent #_:trace?, :do :let :data :msg :error :run
:elide? :allow? #_:expansion-id))]
@ -557,7 +557,7 @@
`(do
~do-form
(let ~let-form ; Allow to throw during `signal-value_` deref
(new-signal ~'__instant ~'__uid
(new-signal ~'__inst ~'__uid
~location ~ns ~line ~column ~file,
~sample-rate-form, ~kind-form ~'__id ~level-form, ~ctx-form ~parent-form,
~extra-kvs-form ~data-form ~msg-form,
@ -571,7 +571,7 @@
`(enc/if-not ~allow? ; Allow to throw at call
~run-form
(let [~'__instant ~instant-form ; Allow to throw at call
(let [~'__inst ~inst-form ; Allow to throw at call
~'__id ~id-form ; ''
~'__uid ~uid-form ; ''
~'__run-result ~run-result-form ; Non-throwing (traps)

2
src/taoensso/telemere/tools_logging.clj
View file

@ -29,7 +29,7 @@
:kind :log
:id :taoensso.telemere/tools-logging
:level level
:instant :auto
:inst :auto
:error throwable
:msg message})
nil))

24
test/taoensso/telemere_tests.cljc
View file

@ -80,20 +80,20 @@
(let [[_ [sv1]] (ws (sig! {:level :info }))
[_ [sv2]] (ws (sig! {:level :info, :run (reduce + (range 1e6))}))
[_ [sv3]] (ws (sig! {:level :info, :run (reduce + (range 1e6))
:instant ; Allow custom instant
:inst ; Allow custom instant
#?(:clj java.time.Instant/EPOCH
:cljs (js/Date. 0))}))]
[(let [{start :instant, end :end-instant} sv1]
[(let [{start :inst, end :end-inst} sv1]
[(is (enc/inst? start))
(is (nil? end))])
(let [{start :instant, end :end-instant} sv2]
(let [{start :inst, end :end-inst} sv2]
[(is (enc/inst? start))
(is (enc/inst? end))
(is (> (inst-ms end) (inst-ms start)))])
(let [{start :instant, end :end-instant} sv3]
(let [{start :inst, end :end-inst} sv3]
[(is (enc/inst? start))
(is (enc/inst? end))
(is (= (inst-ms start) 0) "Respect custom instant")
@ -221,8 +221,8 @@
(let [sv1 (tel/with-signal (tel/signal! {:level :info, :run (+ 1 2), :my-k1 :my-v1}))
sv1 ; Ensure instants are printable
(-> sv1
(update :instant enc/inst->udt)
(update :end-instant enc/inst->udt))]
(update :inst enc/inst->udt)
(update :end-inst enc/inst->udt))]
[(is (= sv1 (read-string (pr-str sv1))))])))])
@ -295,12 +295,12 @@
{:async nil, :error-fn (fn [x] (reset! error_ x)), :rl-error nil,
:middleware [(fn [sv] (if *throwing-handler-middleware?* (ex1!) sv))]}
[(is (->> (sig! {:level :info, :when (ex1!)}) (throws? :ex-info "TestEx")) "`~filterable-expansion/allow` throws at call")
(is (->> (sig! {:level :info, :instant (ex1!)}) (throws? :ex-info "TestEx")) "`~instant-form` throws at call")
(is (->> (sig! {:level :info, :id (ex1!)}) (throws? :ex-info "TestEx")) "`~id-form` throws at call")
(is (->> (sig! {:level :info, :uid (ex1!)}) (throws? :ex-info "TestEx")) "`~uid-form` throws at call")
(is (->> (sig! {:level :info, :run (ex1!)}) (throws? :ex-info "TestEx")) "`~run-form` rethrows at call")
(is (sm? @sv_ {:level :info, :error ex1-pred}) "`~run-form` rethrows at call *after* dispatch")
[(is (->> (sig! {:level :info, :when (ex1!)}) (throws? :ex-info "Ex1")) "`~filterable-expansion/allow` throws at call")
(is (->> (sig! {:level :info, :inst (ex1!)}) (throws? :ex-info "Ex1")) "`~inst-form` throws at call")
(is (->> (sig! {:level :info, :id (ex1!)}) (throws? :ex-info "Ex1")) "`~id-form` throws at call")
(is (->> (sig! {:level :info, :uid (ex1!)}) (throws? :ex-info "Ex1")) "`~uid-form` throws at call")
(is (->> (sig! {:level :info, :run (ex1!)}) (throws? :ex-info "Ex1")) "`~run-form` rethrows at call")
(is (sm? @sv_ {:level :info, :error ex1-pred}) "`~run-form` rethrows at call *after* dispatch")
(testing "`@signal-value_`: trap with wrapped handler"
[(testing "Throwing `~let-form`"