Skip to content

Commit 5eb6002

Browse files
ptaoussanisptaoussanis
committed
[nop] Finish initial README
1 parent 0937a80 commit 5eb6002

File tree

2 files changed

+57
-33
lines changed

2 files changed

+57
-33
lines changed

‎README.md‎

Lines changed: 55 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
<a href="https://www.taoensso.com/clojure" title="More stuff by @ptaoussanis at www.taoensso.com"><img src="https://www.taoensso.com/open-source.png" alt="Taoensso open source" width="340"/></a>
2-
[**API**][cljdoc] | [**Wiki**][GitHub wiki] | [Latest releases](#latest-releases) | [Slack channel][]
2+
[**API**][cljdoc] | [Slack channel][] | Latest release: [v1.0.0-SNAPSHOT](https://clojars.org/com.taoensso/trove/versions/1.0.0-SNAPSHOT) (2025-06-19) 🚧
33

4-
# Trove
4+
[![Clj tests][Clj tests SVG]][Clj tests URL]
5+
[![Cljs tests][Cljs tests SVG]][Cljs tests URL]
6+
[![Graal tests][Graal tests SVG]][Graal tests URL]
57

6-
🚧 **Under construction**: this library isn't ready for use yet! 🚧
8+
# Trove
79

810
### Modern logging facade for Clojure/Script
911

@@ -13,53 +15,73 @@ Trove is a minimal, modern alternative to [tools.logging](https://github.com/clo
1315
- Both Clojure **and ClojureScript**
1416
- **Richer filtering** capabilities (by namespace, id, level, data, etc.)
1517

16-
It's TINY (1 fn, 0 deps, ~100 loc), fast, and highly flexible.
18+
It's TINY (1 macro, 0 deps, ~100 loc), fast, and highly flexible.
1719

18-
It supports ANY backend including: [Telemere](https://www.taoensso.com/telemere), [Timbre](https://www.taoensso.com/timbre), [μ/log](https://github.com/BrunoBonacci/mulog), [tools.logging](https://github.com/clojure/tools.logging), [SLF4J](https://www.slf4j.org/), a custom fn, etc.
20+
It supports any backend including: [Telemere](https://www.taoensso.com/telemere), [Timbre](https://www.taoensso.com/timbre), [μ/log](https://github.com/BrunoBonacci/mulog), [tools.logging](https://github.com/clojure/tools.logging), [SLF4J](https://www.slf4j.org/), a custom fn, etc.
1921

20-
And it works great for **library authors** that want to emit rich logging _without_ forcing their users to adopt any particular backend:
22+
It works great for **library authors** that want to emit rich logging _without_ forcing their users to adopt any particular backend.
2123

22-
- Library authors include the tiny [dep][Clojars URL] in their lib, then make their logging calls with the [Trove API](TODO).
23-
- Library users can then [easily choose](TODO) their preferred backend.
24+
## To log
2425

25-
### Quick example
26+
1. Include the (tiny) [dependency](#latest-releases) in your project or library.
27+
2. Use `trove/log!` to make your logging calls (see [docstring](https://cljdoc.org/d/com.taoensso/trove/CURRENT/api/taoensso.trove#log!) for API):
2628

2729
```clojure
28-
(require '[taoensso.trove :as trove :refer [log!]])
30+
(ns my-ns (:require [taoensso.trove :as trove]))
2931

30-
;; Logging call:
31-
(log! {:level :info, :id :auth/user-login, :data {:user-name user-name}, :msg "User logged in!"})
32+
(trove/log! {:level :info, :id :auth/login, :data {:user-id 1234}, :msg "User logged in!"})
33+
```
3234

33-
;; Above logging call expands to:
34-
(when-let [log-fn trove/*log-fn*] ; Configured backend fn
35-
(log-fn ... "my.namespace" :info :auth/user-login [line-num column-num]
36-
{:msg "User logged in!", :data {:user-name user-name}} ...))
35+
The above logging call expands to:
3736

38-
;; The configured *log-fn* then takes care of filtering and output...
37+
```clojure
38+
(when-let [log-fn trove/*log-fn*] ; Chosen backend fn
39+
(log-fn ... "my-ns" :info :auth/login [line-num column-num]
40+
{:msg "User logged in!", :data {:user-id 1234}} ...))
3941
```
4042

41-
- Use [`log!`](TODO) for logging calls
42-
- Set [`*log-fn*`](TODO) to configure the backend
43+
And the chosen backend then takes care of filtering and output.
4344

44-
## Latest release/s
45+
## To choose a backend
4546

46-
- `YYYY-MM-DD` `vX.Y.Z`: [release info](../../releases/tag/vTODO)
47+
Just modify `trove/*log-fn*` (see [docstring](https://cljdoc.org/d/com.taoensso/trove/CURRENT/api/taoensso.trove#*log-fn*) for API).
4748

48-
[![Clj tests][Clj tests SVG]][Clj tests URL]
49-
[![Cljs tests][Cljs tests SVG]][Cljs tests URL]
50-
[![Graal tests][Graal tests SVG]][Graal tests URL]
49+
The default log-fn prints logs to `*out*` or the JS console. Alternatives are provided for some common backends:
50+
51+
```clojure
52+
(ns my-ns
53+
(:require
54+
[taoensso.trove :as trove]
55+
56+
;; Choose (uncomment) one:
57+
;; [taoensso.trove.console :as trove-backend] ; default
58+
;; [taoensso.trove.telemere :as trove-backend]
59+
;; [taoensso.trove.timbre :as trove-backend]
60+
;; [taoensso.trove.mulog :as trove-backend]
61+
;; [taoensso.trove.tools-logging :as trove-backend]
62+
;; [taoensso.trove.slf4j :as trove-backend]
63+
))
64+
65+
(trove/set-log-fn! (trove-backend/get-log-fn {}))
66+
```
67+
68+
It's easy to write your own log-fn if you want to use a different backend or customise anything.
5169

52-
See [here][GitHub releases] for earlier releases.
70+
## What about expensive data?
71+
72+
Structured logging sometimes involves expensive data collection or transformation, e.g.:
73+
74+
```clojure
75+
(trove/log! {:id ::my-event, :data (expensive) ...})
76+
```
5377

54-
## Documentation
78+
That's why Trove automatically delays any values that need runtime evaluation, allowing the backend to apply filtering *before* paying realization costs.
5579

56-
- [Wiki][GitHub wiki] (getting started, usage, etc.)
57-
- API reference via [cljdoc][cljdoc]
58-
- Support via [Slack channel][] or [GitHub issues][]
80+
This explains the `:lazy_` `{:keys [msg data error kvs]}` arg given to [`truss/*log-fn*`](https://cljdoc.org/d/com.taoensso/trove/CURRENT/api/taoensso.trove#*log-fn*).
5981

6082
## Funding
6183

62-
You can [help support][sponsor] continued work on this project, thank you!! 🙏
84+
You can [help support][sponsor] continued work on this project and [others][my work], thank you!! 🙏
6385

6486
## License
6587

@@ -71,14 +93,15 @@ Licensed under [EPL 1.0](LICENSE.txt) (same as Clojure).
7193
[GitHub releases]: ../../releases
7294
[GitHub issues]: ../../issues
7395
[GitHub wiki]: ../../wiki
74-
[Slack channel]: https://www.taoensso.com/trove/slack
96+
[Slack channel]: https://www.taoensso.com/trove/slack
7597

7698
[Peter Taoussanis]: https://www.taoensso.com
7799
[sponsor]: https://www.taoensso.com/sponsor
100+
[my work]: https://www.taoensso.com/clojure-libraries
78101

79102
<!-- Project -->
80103

81-
[cljdoc]: https://cljdoc.org/d/com.taoensso/trove/
104+
[cljdoc]: https://cljdoc.org/d/com.taoensso/trove/CURRENT/api/taoensso.trove
82105

83106
[Clojars SVG]: https://img.shields.io/clojars/v/com.taoensso/trove.svg
84107
[Clojars URL]: https://clojars.org/com.taoensso/trove

‎src/taoensso/trove.cljc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
(ns taoensso.trove
2-
"Modern logging facade for Clojure/Script."
2+
"A minimal, modern logging facade for Clojure/Script.
3+
Supports both traditional and structured logging."
34
{:author "Peter Taoussanis (@ptaoussanis)"}
45
(:require
56
[taoensso.trove.utils :as utils]

0 commit comments

Comments
 (0)