Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/clojure/tools.logging
Clojure logging API
https://github.com/clojure/tools.logging
Last synced: 4 days ago
JSON representation
Clojure logging API
- Host: GitHub
- URL: https://github.com/clojure/tools.logging
- Owner: clojure
- License: epl-1.0
- Created: 2011-03-11T15:01:29.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2024-07-15T17:54:41.000Z (5 months ago)
- Last Synced: 2024-12-11T21:03:53.565Z (11 days ago)
- Language: Clojure
- Homepage:
- Size: 278 KB
- Stars: 387
- Watchers: 34
- Forks: 51
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Logging
Logging macros which delegate to a specific logging implementation, selected
at runtime when the `clojure.tools.logging` namespace is first loaded.
## Installation
Lastest stable release is [1.3.0]
[CLI/`deps.edn`](https://clojure.org/reference/deps_edn) dependency information:
```clojure
org.clojure/tools.logging {:mvn/version "1.3.0"}
```
Leiningen:
```clojure
[org.clojure/tools.logging "1.3.0"]
```
Maven:
```xml
org.clojure
tools.logging
1.3.0
```
## Usage
[Latest API Documentation](https://clojure.github.io/tools.logging)
Logging occurs with the `log` macro, or the level-specific convenience macros
(e.g., `debug`, `debugf`). Only when the specified logging level is enabled will
the message arguments be evaluated and the underlying logging implementation be
invoked. By default, that invocation will occur via an agent when inside a
running STM transaction.
### Namespacing of log entries
Unless otherwise specified, the current namespace (as identified by `*ns*`) will
be used as the "logger name" when interacting with logging implementations. Most
logging implementations allow for varying configuration by logger name.
Note: You should configure your logging implementation to display the logger
name that was passed to it. If instead the logging implementation performs
stack-inspection you'll see some ugly and unhelpful text in your logs.
### Redirecting output to logs
You can redirect all java writes of `System.out` and `System.err` to the log
system by calling `log-capture!`. To bind `*out*` and `*err*` to the log system
invoke `with-logs`. In both cases a logger name must be provided in lieu of
using `*ns*`.
## Configuration
_NOTE: Logging configuration (e.g., setting of logging levels, formatting) is
specific to the underlying logging implementation, and is out of scope for this
library._
### Selecting a logging implementation
To control which logging implementation is used, set the `clojure.tools.logging.factory`
system property to the fully-qualified name of a no-arg function that returns an
instance of `clojure.tools.logging.impl/LoggerFactory`. There are a number of
factory functions provided in the [`clojure.tools.logging.impl`](https://clojure.github.io/tools.logging/#clojure.tools.logging.impl/find-factory)
namespace.
[Leiningen example]:
```clojure
:jvm-opts ["-Dclojure.tools.logging.factory=clojure.tools.logging.impl/slf4j-factory"]
```
If the system property is unset, an implementation will be automatically chosen
based on whichever of the following implementations is successfully loaded first:
1. [SLF4J]
2. [Apache Commons Logging]
3. [Log4J 2]
4. [Log4J]
5. [java.util.logging]
The above approach is problematic given that applications often inadvertently pull
in multiple logging implementations as transitive dependencies. As such, it is
_strongly_ advised that you set the system property.
### Log4J2
A simple Log4j2 [configuration](https://logging.apache.org/log4j/2.x/manual/configuration.html):
```properties
status = warn
monitorInterval = 5
appender.console.type = Console
appender.console.name = STDOUT
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %date %level %logger %message%n%throwable
rootLogger.level = info
rootLogger.appenderRef.stdout.ref = STDOUT
```
*Note:* The above [pattern](https://logging.apache.org/log4j/2.x/manual/layouts.html#Patterns)
explicitly uses `%throwable` so that `clojure.lang.ExceptionInfo` exceptions
will be printed with their data maps. If either `%xThrowable` (the default) or
`%rThrowable` is used, the data maps will not be printed.
## FAQ
#### When logging an `ex-info` exception, why isn't the data map printed?
This is likely because the logging implementation is printing the contents of
`Throwable.getMessage()`, which returns just the message arg to `ex-info`.
Logging implementations that print the contents of `toString()` or use `Throwable.printStackTrace(...)`
will end up printing the data map.
## Thanks
* Chris Dean
* Phil Hagelberg
* Richard Newman
* Sean Corfield
* Timothy Pratley
## License
Copyright © Rich Hickey, Alex Taggart, and contributors
Licensed under the EPL. (See the file epl.html.)
[1.3.0]: https://github.com/clojure/tools.logging/tree/v1.3.0
[1.2.4]: https://github.com/clojure/tools.logging/tree/v1.2.4
[Leiningen example]: https://github.com/technomancy/leiningen/blob/master/doc/TUTORIAL.md#setting-jvm-options
[SLF4J]: https://www.slf4j.org/
[Apache Commons Logging]: https://commons.apache.org/logging
[Log4J 2]: https://logging.apache.org/log4j/2.x/
[Log4J]: https://logging.apache.org/log4j/1.2/
[java.util.logging]: https://docs.oracle.com/en/java/javase/13/docs/api/java.logging/java/util/logging/package-summary.html