5 Migrating
While Timbre will continue to be maintained and supported (and will even receive some improvements back-ported from Telemere), most Timbre users will want to at least consider updating to Telemere.
Telemere's functionality is a superset of Timbre, and offers many improvements including:
- Significantly better performance
- A cleaner and more flexible API
- Better support for structured logging
- Much better documentation
- Better built-in handlers
- Easier configuration in many cases
- A more robust architecture, free from all historical constraints
Migrating from Timbre to Telemere should be straightforward unless you depend on specific/custom appenders that might not be available for Telemere (yet).
Where Timbre uses the term "appender", Telemere uses the more general "handler". Functionally they're the same thing.
Check which Timbre appenders you use, and whether a similar handler is currently included with Telemere or available via the community.
If not, you may need to write something yourself.
This may be easier than it sounds. Remember that signals are just plain Clojure/Script maps, and handlers just plain Clojure/Script functions that do something with those maps.
Feel free to ping me for assistance, or ask on the #telemere Slack channel.
Switch your Timbre namespace imports:
(ns my-ns
(:require [taoensso.timbre :as timbre :refer [...]]) ; Old
(:require [taoensso.telemere.timbre :as timbre :refer [...]]) ; New
)The taoensso.telemere.timbre namespace contains a shim of most of Timbre's API.
Feel free to keep using this shim API as long as you like, there's no need to rewrite any of your existing code unless you specifically want to use features that are only possible with Telemere's signal creators, etc.
You may need to update code related to filter config and/or handler management.
This is usually only a few lines of code, and should be straightforward.
See section 3-Config for more info on configuring Telemere.
While I believe that the Timbre shim above should be robust, it's of course possible that I missed something.
So please test carefully before switching to Telemere in production, and please report any issues! 🙏
In particular - note that Telemere's handler output may be completely different, so if you have any code/systems (e.g. log aggregators) that depend on the specific output format - these must also be tested.
If for any reason your tests are unsuccessful, please don't feel pressured to migrate. Again, I will continue to maintain and support Timbre. I have applications running Timbre that I plan to never migrate since they're completely stable.
This is easy, see here.
This is easy, see here.