From 8f1035ff9737297c90736b7e71f6fdfd3a37ff5a Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Sat, 25 May 2024 10:27:46 +0200 Subject: [PATCH] [nop] Consistent `tools.logging` terminology The terminology is necessarily a bit complex because of competing constraints. --- README.md | 2 +- src/taoensso/telemere/impl.cljc | 2 +- src/taoensso/telemere/tools_logging.clj | 27 ++++++++++++++++--------- test/taoensso/telemere_tests.cljc | 2 +- wiki/1-Getting-started.md | 10 ++++----- wiki/3-Config.md | 6 +++--- 6 files changed, 28 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index bdfac44..84cc711 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ See [here][GitHub releases] for earlier releases. #### Interop -- 1st-class **out-the-box interop** with [SLF4J v2](https://www.slf4j.org/), [clojure.tools.logging](https://github.com/clojure/tools.logging), [OpenTelemetry](https://opentelemetry.io/), and [Tufte](https://www.taoensso.com/tufte). +- 1st-class **out-the-box interop** with [SLF4J v2](https://www.slf4j.org/), [tools.logging](https://github.com/clojure/tools.logging), [OpenTelemetry](https://opentelemetry.io/), and [Tufte](https://www.taoensso.com/tufte). - Included [shim](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.timbre) for easy/gradual [migration from Timbre](../../wiki/5-Migrating). - Extensive set of [handlers](../../wiki/4-Handlers#included-handlers) included out-the-box. diff --git a/src/taoensso/telemere/impl.cljc b/src/taoensso/telemere/impl.cljc index 81a3098..a9ba062 100644 --- a/src/taoensso/telemere/impl.cljc +++ b/src/taoensso/telemere/impl.cljc @@ -700,7 +700,7 @@ #?(:clj (defmacro signal-allowed? - "Used only for intake (SLF4J, `clojure.tools.logging`, etc.)." + "Used only for intake (SLF4J, `tools.logging`, etc.)." {:arglists (signal-arglists :signal!)} [opts] (let [{:keys [#_expansion-id #_location elide? allow?]} diff --git a/src/taoensso/telemere/tools_logging.clj b/src/taoensso/telemere/tools_logging.clj index 7a4bcd0..09371fc 100644 --- a/src/taoensso/telemere/tools_logging.clj +++ b/src/taoensso/telemere/tools_logging.clj @@ -1,6 +1,12 @@ (ns taoensso.telemere.tools-logging - "Intake support for `clojure.tools.logging` -> Telemere. - Telemere will attempt to load this ns automatically when possible." + "Intake support for `tools.logging` -> Telemere. + Telemere will attempt to load this ns automatically when possible. + + Naming conventions: + `tools.logging` - For referring to the library. + `tools-logging` - For symbols, keywords, and this namespace. + `clojure.tools.logging` - For env config to match library's conventions." + (:require [taoensso.encore :as enc :refer [have have?]] [taoensso.telemere.impl :as impl] @@ -12,7 +18,7 @@ clojure.tools.logging.impl/Logger (enabled? [_ level] - (when-debug (println [:tools.logger/enabled? logger-ns level])) + (when-debug (println [:tools-logging/enabled? logger-ns level])) (impl/signal-allowed? {:location nil :kind :log @@ -20,7 +26,7 @@ :level level})) (write! [_ level throwable message] - (when-debug (println [:tools.logger/write! logger-ns level])) + (when-debug (println [:tools-logging/write! logger-ns level])) (impl/signal! {:allow? true ; Pre-filtered by `enabled?` call :location nil @@ -37,7 +43,8 @@ (get-logger [_ logger-ns] (TelemereLogger. (str logger-ns)))) (defn tools-logging->telemere! - "Configures `clojure.tools.logging` to use Telemere as its logging implementation. + "Configures `tools.logging` to use Telemere as its logging + implementation (backend). Called automatically if one of the following is \"true\": JVM property: `clojure.tools.logging.to-telemere` @@ -47,15 +54,15 @@ (impl/signal! {:kind :event :level :info - :id :taoensso.telemere/clojure.tools.logging->telemere! - :msg "Enabling intake: `clojure.tools.logging` -> Telemere"}) + :id :taoensso.telemere/tools-logging->telemere! + :msg "Enabling intake: `tools.logging` -> Telemere"}) (alter-var-root #'clojure.tools.logging/*logger-factory* (fn [_] (TelemereLoggerFactory.)))) (defn tools-logging->telemere? - "Returns true iff `clojure.tools.logging` is configured to use Telemere - as its logging implementation." + "Returns true iff `tools.logging` is configured to use Telemere + as its logging implementation (backend)." [] (when-let [lf clojure.tools.logging/*logger-factory*] (instance? TelemereLoggerFactory lf))) @@ -68,7 +75,7 @@ (let [sending? (tools-logging->telemere?) receiving? (and sending? - (impl/test-intake! "`clojure.tools.logging` -> Telemere" + (impl/test-intake! "`tools.logging` -> Telemere" #(clojure.tools.logging/info %)))] {:present? true diff --git a/test/taoensso/telemere_tests.cljc b/test/taoensso/telemere_tests.cljc index a11851e..a872d58 100644 --- a/test/taoensso/telemere_tests.cljc +++ b/test/taoensso/telemere_tests.cljc @@ -580,7 +580,7 @@ #?(:clj (deftest _intake - [(testing "`clojure.tools.logging` -> Telemere" + [(testing "`tools.logging` -> Telemere" [(is (sm? (tel/check-intakes) {:tools-logging {:present? true, :sending->telemere? true, :telemere-receiving? true}})) (is (sm? (with-sig (ctl/info "Hello" "x" "y")) {:level :info, :location nil, :ns nil, :kind :log, :id :taoensso.telemere/tools-logging, :msg_ "Hello x y", :inst pinst?})) diff --git a/wiki/1-Getting-started.md b/wiki/1-Getting-started.md index 9ac553e..453438f 100644 --- a/wiki/1-Getting-started.md +++ b/wiki/1-Getting-started.md @@ -104,11 +104,11 @@ See section [3-Config](./3-Config) for customization. > Telemere can create signals from relevant **external API calls**, etc. -| Platform | Condition | Signals from | -| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| Clj | [SLF4J API](https://mvnrepository.com/artifact/org.slf4j/slf4j-api) and [Telemere SLF4J backend](https://clojars.org/com.taoensso/slf4j-telemere) present | [SLF4J](https://www.slf4j.org/) logging calls. | -| Clj | [clojure.tools.logging](https://mvnrepository.com/artifact/org.clojure/tools.logging) present and [`tools-logging->telemere!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.tools-logging#tools-logging-%3Etelemere!) called | [clojure.tools.logging](https://github.com/clojure/tools.logging) logging calls. | -| Clj | [`streams->telemere!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#streams-%3Etelemere!) called | Output to `System/out` and `System/err` streams. | +| Platform | Condition | Signals from | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | +| Clj | [SLF4J API](https://mvnrepository.com/artifact/org.slf4j/slf4j-api) and [Telemere SLF4J backend](https://clojars.org/com.taoensso/slf4j-telemere) present | [SLF4J](https://www.slf4j.org/) logging calls. | +| Clj | [tools.logging](https://mvnrepository.com/artifact/org.clojure/tools.logging) present and [`tools-logging->telemere!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.tools-logging#tools-logging-%3Etelemere!) called | [tools.logging](https://github.com/clojure/tools.logging) logging calls. | +| Clj | [`streams->telemere!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#streams-%3Etelemere!) called | Output to `System/out` and `System/err` streams. | Run [`check-intakes`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#check-intakes) to help verify/debug: diff --git a/wiki/3-Config.md b/wiki/3-Config.md index 346cd97..642aac0 100644 --- a/wiki/3-Config.md +++ b/wiki/3-Config.md @@ -22,13 +22,13 @@ See section [4-Handlers](./4-Handlers). # Interop -## clojure.tools.logging +## tools.logging -[`clojure.tools.logging`](https://github.com/clojure/tools.logging) can use Telemere as its logging implementation. +[`tools.logging`](https://github.com/clojure/tools.logging) can use Telemere as its logging implementation (backend). To do this: -1. Ensure that you have the `clojure.tools.logging` dependency, and +1. Ensure that you have the `tools.logging` dependency, and 2. Call [`tools-logging->telemere!`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.tools-logging#tools-logging-%3Etelemere!), or set the relevant environmental config as described in its docstring. Verify successful intake with [`check-intakes`](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#check-intakes):