Logjam is a library to capture log events emitted by Java logging frameworks. Log events are captured as a Clojure data structure in an in-memory atom, which can be searched, inspected and listened to.
Logjam is designed to be used by tooling such as CIDER's Log Mode, but can also be used with a plain REPL in combination with REBL or Morse.
This library is still experimental and APIs are subject to change.
Logjam supports log frameworks that allow reconfiguration at run time. More specifically the framework should support attaching log appenders to loggers, in order to capture events.
At the moment the following log frameworks are supported:
In order to capture log events, a log appender needs to be attached to a logger of a framework. Once an appender is attached to a logger it captures the log events emitted by the framework in an in-memory atom. A log appender can be configured to have a certain size (default: 100000) and a threshold in percentage (default: 10). Log events are cleared from the appender when threshold (appender size plus threshold in percentage of the appender size) is reached. Additionally an appender can be configured to only capture events that match a set of filters.
Log events can be streamed to a client by attaching a log consumer to an appender. Once a log consumer has been attached to an appender, it will receive events from the appender. Similar to log appenders, consumers can also be configured with a set of filters to only receive certain events.
Log events can be searched, streamed to a client or viewed in CIDER's
Inspector and Stacktrace Mode. When searching log events the user can
specify a set of filters. Events that match the filters are shown in
the *cider-log* buffer. Additionally a log consumer will be
attached to the appender to receive log events matching the search
criteria after the search command has been issued. The log appender
will be removed automatically once a new search has been submitted or
when the *cider-log* buffer gets killed.
Filters for log events can be attached to log appenders and consumers. They also take effect when searching events or streaming them to clients. If multiple filters are chosen they are combined using logical AND condition. The following filters are available:
exceptionslevelpatternstart-timeend-timethreadsloggers-allowlistloggers-blocklist
Logjam is used by CIDER's LogMode, but can also be used in a standalone REPL. Here is an example how such a REPL session could look like:
;; Use the :logback logging framework
(repl/set-framework! :logback)
;; Add an appender to the log framework that captures events.
(repl/add-appender)
;; Log something
(repl/log :message \"hello\")
;; Return all captured log events
(repl/events)
;; Search log events with :message field matching a regex :pattern
(repl/events :pattern \"hel.*\")
;; Search log events by level
(repl/events :level :INFO)
;; Add a log consumer that prints log events
(repl/add-consumer
:callback (fn [_consumer event]
(clojure.pprint/pprint event)))
;; Log something else
(repl/log :message \"world\")
;; Remove all consumers and appenders
(repl/shutdown)The following options can be set as Java system properties:
logjam.appender.default-event-size- The default maximum number of events that can be captured by a given appender.
- Default: 100000
The Makefile offers a variety of tasks: test kondo eastwood cljfmt lint clean repl.
Here's how to deploy to Clojars:
git tag -a v0.1.0 -m "0.1.0"
git push --tagsThanks to @rafaeldff for his initial idea on capturing the logs and supporting this project. Some of the code in this repository is based on his private development tooling.
Copyright © 2023-2024 CIDER Contributors
Distributed under the Eclipse Public License, the same as Clojure.