diff --git a/resources/signal-docstrings/signal-content.txt b/resources/signal-docstrings/signal-content.txt index 07c7935..cd28bae 100644 --- a/resources/signal-docstrings/signal-content.txt +++ b/resources/signal-docstrings/signal-content.txt @@ -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 ∈ #{ :trace :debug :info :warn :error :fatal :report ...} -`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy ...} -`: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 ∈ #{ :trace :debug :info :warn :error :fatal :report ...} +`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy ...} +`: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` diff --git a/resources/signal-docstrings/signal-options.txt b/resources/signal-docstrings/signal-options.txt index 427b398..c2ed48a 100644 --- a/resources/signal-docstrings/signal-options.txt +++ b/resources/signal-docstrings/signal-options.txt @@ -1,10 +1,10 @@ Signal options (shared by `signal!`, `event!`, ...): -`:instant` - Platform instant [1] when signal was created, ∈ #{nil :auto } -`:level` - Signal level ∈ #{ :trace :debug :info :warn :error :fatal :report ...} -`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy ...} -`: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 } +`:level` - Signal level ∈ #{ :trace :debug :info :warn :error :fatal :report ...} +`:kind` - Signal ?kind ∈ #{nil :event :error :log :trace :spy ...} +`: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` diff --git a/slf4j/src/taoensso/telemere/slf4j.clj b/slf4j/src/taoensso/telemere/slf4j.clj index 926f092..211495a 100644 --- a/slf4j/src/taoensso/telemere/slf4j.clj +++ b/slf4j/src/taoensso/telemere/slf4j.clj @@ -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] diff --git a/src/taoensso/telemere/impl.cljc b/src/taoensso/telemere/impl.cljc index 56c4b2a..06e7668 100644 --- a/src/taoensso/telemere/impl.cljc +++ b/src/taoensso/telemere/impl.cljc @@ -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) diff --git a/src/taoensso/telemere/tools_logging.clj b/src/taoensso/telemere/tools_logging.clj index 92e9ae2..66dec53 100644 --- a/src/taoensso/telemere/tools_logging.clj +++ b/src/taoensso/telemere/tools_logging.clj @@ -29,7 +29,7 @@ :kind :log :id :taoensso.telemere/tools-logging :level level - :instant :auto + :inst :auto :error throwable :msg message}) nil)) diff --git a/test/taoensso/telemere_tests.cljc b/test/taoensso/telemere_tests.cljc index a689921..245320b 100644 --- a/test/taoensso/telemere_tests.cljc +++ b/test/taoensso/telemere_tests.cljc @@ -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`"