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

[new] Add preliminary docs for lib maintainers, etc.

Browse source
This commit is contained in:
Peter Taoussanis 2024-05-25 00:03:54 +02:00
parent 8886213a2b
commit c3ce68b512
2 changed files with 82 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
wiki/6-FAQ.md
View file

@ -97,16 +97,16 @@ Note that you can even use `format` or any other formatter/s of your choice. You
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.
# How to use Telemere from a library?
See section [9-Maintainers](./9-Maintainers).
# How does Telemere compare to Mulog?
> [Mulog](https://github.com/BrunoBonacci/mulog) is an excellent "micro-logging library" for Clojure that shares many of the same capabilities and objectives as Telemere!
TODO - will add a comparison here before Telemere's final release.
# How to use Telemere from a library?
TODO - will add advice here before Telemere's final release.
# Other questions?
Please [open a Github issue](https://github.com/taoensso/telemere/issues) or ping on Telemere's [Slack channel](https://www.taoensso.com/telemere/slack). I'll regularly update the FAQ to add common questions.

78
wiki/9-Maintainers.md Normal file
View file

@ -0,0 +1,78 @@
Are you a library maintainer that's considering **using Telemere in your library**?
See below for some considerations and advice-
# Consider a facade
Ask yourself the question: do you specifically *need/want* Telemere?
Many libraries only need very basic logging. In these cases it can be beneficial to do your logging through a facade like [tools.logging](https://github.com/clojure/tools.logging) or [SLF4J](https://www.slf4j.org/).
**Upside**: users can then easily choose and configure their **preferred backend** (including Telemere, which can easily [act as a backend](./3-Config#interop) for both tools.logging and SLF4J).
**Downside**: your logging features will necessarily be limited to the lowest-common-denominator features supported by your chosen facade (tools.logging or SLF4J, etc.). In particular, you'll be giving up support for Telemere's structured logging features and [rich filtering](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#get-filters) (including filtering or setting minimum levels by namespaces).
# Consider API stability
Telemere is still currently in **beta** as of May 2024.
While the [signal creator](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-creators) and [signal content](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#help:signal-content) APIs should already be mostly stable, I would still **recommend against** using Telemere in any public libraries until after Telemere's **stable v1 release** (current ETA >= [August 2024](https://taoensso.com/roadmap)).
# Using Telemere in your library
If you **do** need/want support for Telemere's structured logging features and/or [rich filtering](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#get-filters), then you've got a couple options-
## Telemere as a non-optional dependency
This is straight-forward: you include Telemere in your library's dependencies, and you can make use of Telemere's full API from your own library.
Telemere's [default config](./1-Getting-started#default-config) is sensible (with println-like console output), so many of library users won't need to configure or interact with Telemere at all.
The most common thing library users may want to do is **adjust the minimum level** of signals created by your library. And since your users might not be familiar with Telemere, I'd recommend including something like the following in a convenient place like your library's main API namespace:
```clojure
(defn set-min-log-level!
"Sets minimum level of Telemere signals (logs) generated by <my-library>.
Possible levels (from most to least verbose):
#{:trace :debug :info :warn :error :fatal :report}.
The default level is `:warn`."
[level]
(tel/set-min-level! nil "my-library.namespace" min-level)
(tel/set-min-level! nil "my-library.namespace.*" min-level)
nil)
(defonce ^:private __set-default-log-level (set-min-log-level! :warn))
```
This way your users can easily disable, decrease, or increase signal output from your library without even needing to touch Telemere or to be aware of its existence.
## Telemere as an optional dependency
I have a solution planned for this that I'm still testing. Will add more info prior to Telemere's [stable v1 release](https://www.taoensso.com/roadmap).
# Migrating from Timbre
Do you have a library that currently uses [Timbre](https://www.taoensso.com/timbre), and you're considering a change to Telemere?
## With a facade
First, I'd encourage you to [consider a facade](#consider-a-fascade).
Unless you specifically want features *only* available to Telemere/Timbre, using a facade would give your users the option to choose **whichever backend they prefer**.
Since both Telemere and Timbre support [tools.logging](https://github.com/clojure/tools.logging) and [SLF4J](https://www.slf4j.org/), either one of those would be a reasonable choice.
(Though note that Timbre's current SLF4J support is a little fragile. Timbre v7 [will introduce](https://github.com/taoensso/roadmap/issues/11) improved native SLF4J support, so you may want to wait for that if you are considering SLF4J).
Example migration steps:
1. Migrate your library's Timbre logging calls to equivalent [`tools.logging`](https://github.com/clojure/tools.logging) calls.
2. Remove your library's Timbre dependency.
3. Advise your users about the dropped dependency, and tell them that they'll now need to opt-in to [use Telemere](https://github.com/taoensso/telemere/wiki/3-Config#toolslogging), [use Timbre](https://taoensso.github.io/timbre/taoensso.timbre.tools.logging.html#var-use-timbre), or use some other logging backend for tools.logging that they prefer.
## Without a facade
In this case you'll need to decide if you want to use Telemere as an [optional](#telemere-as-an-optional-dependency) or [non-optional](#telemere-as-a-non-optional-dependency) dependency.
Will add more info prior to Telemere's [stable v1 release](https://www.taoensso.com/roadmap).