From 5484f1348145474f8fdd089482252075fd32dab3 Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Thu, 18 Apr 2024 12:14:35 +0200 Subject: [PATCH] [doc] Documentation work --- README.md | 9 +++------ examples.cljc | 33 +++++++++++++++++++++++++++++++++ wiki/6-FAQ.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ wiki/7-Tips.md | 13 +++++++++++++ 4 files changed, 96 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1dabb6e..edefa16 100644 --- a/README.md +++ b/README.md @@ -53,12 +53,9 @@ See [here][GitHub releases] for earlier releases. See for intro and usage: -**TODO**: coming soon - - + + Telemere demo video + ## Quick examples diff --git a/examples.cljc b/examples.cljc index 033b766..d18f888 100644 --- a/examples.cljc +++ b/examples.cljc @@ -184,3 +184,36 @@ ([signal] ;; TODO Do something with given signal ))))) + +;;; Message building + +;; A fixed message (string arg) +(t/log! "A fixed message") ; %> {:msg "A fixed message"} + +;; A joined message (vector arg) +(let [user-arg "Bob"] + (t/log! ["User" (str "`" user-arg "`") "just logged in!"])) +;; %> {:msg_ "User `Bob` just logged in!` ...} + +;; With arg prep +(let [user-arg "Bob" + usd-balance-str "22.4821"] + + (t/log! + {:let + [username (clojure.string/upper-case user-arg) + usd-balance (parse-double usd-balance-str)] + + :data + {:username username + :usd-balance usd-balance}} + + ["User" username "has balance:" (str "$" (Math/round usd-balance))])) + +;; %> {:msg "User BOB has balance: $22" ...} + +(t/log! (str "This message " "was built " "by `str`")) +;; %> {:msg "This message was built by `str`"} + +(t/log! (format "This message was built by `%s`" "format")) +;; %> {:msg "This message was built by `format`"} diff --git a/wiki/6-FAQ.md b/wiki/6-FAQ.md index 5eac616..d058405 100644 --- a/wiki/6-FAQ.md +++ b/wiki/6-FAQ.md @@ -50,6 +50,53 @@ They're focused on complementary things. When both are in use: - Tufte can be used for detailed performance measurement, and - Telemere can be used for conveying (aggregate) performance information as part of your system's general observability signals. +# Why no format-style messages? + +Telemere's message API can do everything that traditional print *or* format style message builders can do but **much more flexibly** - and with pure Clojure/Script (so no arcane pattern syntax). + +To coerce/format/prepare args, just use the relevant Clojure/Script utils. + + **Signal messages are always lazy** (as are a signal's `:let` and `:data` [options](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-options)), so you only pay the cost of arg prep and message building *if/when a signal is actually created* (i.e. after filtering, sampling, rate limiting, etc.). + +Examples: + +```clojure +;; A fixed message (string arg) +(t/log! "A fixed message") ; %> {:msg "A fixed message"} + +;; A joined message (vector arg) +(let [user-arg "Bob"] + (t/log! ["User" (str "`" user-arg "`") "just logged in!"])) +;; %> {:msg_ "User `Bob` just logged in!` ...} + +;; With arg prep +(let [user-arg "Bob" + usd-balance-str "22.4821"] + + (t/log! + {:let + [username (clojure.string/upper-case user-arg) + usd-balance (parse-double usd-balance-str)] + + :data + {:username username + :usd-balance usd-balance}} + + ["User" username "has balance:" (str "$" (Math/round usd-balance))])) + +;; %> {:msg "User BOB has balance: $22" ...} + +(t/log! (str "This message " "was built " "by `str`")) +;; %> {:msg "This message was built by `str`"} + +(t/log! (format "This message was built by `%s`" "format")) +;; %> {:msg "This message was built by `format`"} +``` + +Note that you can even use `format` or any other formatter/s of your choice. Your signal message is the result of executing code, so build it however you want. + +See also [`msg-skip`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#msg-skip) and [`msg-splice`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#msg-splice) for some handy utils. + # Other questions? Please [open a Github issue](https://github.com/taoensso/telemere/issues). I'll regularly update the FAQ to add common questions. \ No newline at end of file diff --git a/wiki/7-Tips.md b/wiki/7-Tips.md index 00bea8c..d6134b6 100644 --- a/wiki/7-Tips.md +++ b/wiki/7-Tips.md @@ -102,6 +102,19 @@ Consider the [differences](https://www.youtube.com/watch?v=oyLBGkS5ICk) between Telemere doesn't couple the presence of an error value to signal level. This can be handy, but means that you need to be clear on what constitutes an "error signal" for your use case. See also the [`error-signal?`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#error-signal) util. +- Signals may contain arbitrary user-level keys. + + Any non-standard [options](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-options) you give to a signal creator call will be added to the signal it creates: + + ```clojure + (t/with-signal (t/log! {:my-key "foo"} "My message"))) + ;; => {:my-key "foo", :kvs {:my-key "foo", ...}, ...} + ``` + + Note that all user kvs will *also* be available *together* under the signal's `:kvs` key. + + User kvs are a great way of controlling the per-signal behaviour of custom/advanced handlers. + - Signal `kind` can be useful in advanced cases. Every signal has a `kind` key set by default by each signal creator- `log!` calls produce signals with a `:log` kind, etc.