mirror of https://github.com/deavmi/dlog.git
119 lines
3.2 KiB
Markdown
119 lines
3.2 KiB
Markdown
<p align="center">
|
|
<img src="branding/logo.png" width=220>
|
|
</p>
|
|
|
|
<br>
|
|
|
|
<h1 align="center">dlog</h1>
|
|
|
|
<h3 align="center"><i><b>Simple and modular logging library</i></b></h3>
|
|
|
|
---
|
|
|
|
<br>
|
|
<br
|
|
|
|
|
|
`[2021-Dec-23 11:17:35.3527637] (source/dlog/testing/thing.d:12): This is a log message`
|
|
|
|
---
|
|
|
|
[](https://github.com/deavmi/dlog/actions/workflows/d.yml)
|
|
|
|
## Usage
|
|
|
|
We recommend you use [dub](http://code.dlang.org) to add dlog to your project as follows:
|
|
|
|
```
|
|
dub add dlog
|
|
```
|
|
|
|
* [View on DUB](https://code.dlang.org/packages/dlog)
|
|
* [View API](https://dlog.dpldocs.info/)
|
|
|
|
### Components
|
|
|
|
dlog is formed out of two main components:
|
|
|
|
1. `Logger`
|
|
* The logger contains the needed barebones for facilitating the actual logging of text
|
|
* The _base logger_ (i.e. `Logger`) maintains a list of attaches _filters_, _message transformers_ and _handlers_
|
|
2. `Filter`
|
|
* Acts as a predicate on the incoming _message_ and determines whether it should be logged or not
|
|
* This is used by the `BasicLogger` to implement log levels
|
|
3. `Transform`
|
|
* A _message transform_ is attached to a logger and performs manipulation on the message logged
|
|
* They may be chained as to perform multiple transformations in a stream-like fashion
|
|
4. `Handler`
|
|
* A _handler_ handles the final transformed message, for some this means outputting to standard out, or a file
|
|
|
|
### Quick start
|
|
|
|
If you want to immediately begin logging text using the defaults and don't care about implementing your own transformations then you can
|
|
simply use the default logger as follows:
|
|
|
|
```d
|
|
import dlog;
|
|
|
|
DefaultLogger logger = new DefaultLogger();
|
|
|
|
logger.setLevel(Level.DEBUG);
|
|
logger.error(["woah", "LEVELS!"], 69.420);
|
|
logger.info(["woah", "LEVELS!"], 69.420);
|
|
logger.warn(["woah", "LEVELS!"], 69.420);
|
|
logger.debug_(["woah", "LEVELS!"], 69.420);
|
|
|
|
// Should not be able to see this
|
|
logger.setLevel(Level.INFO);
|
|
logger.debug_("Can't see me!");
|
|
```
|
|
|
|
This will output the following:
|
|
|
|
```
|
|
[2024-Apr-09 19:14:38.3077171] (ERROR): ["woah", "LEVELS!"] 69.42
|
|
[2024-Apr-09 19:14:38.3077346] (INFO): ["woah", "LEVELS!"] 69.42
|
|
[2024-Apr-09 19:14:38.3077559] (WARN): ["woah", "LEVELS!"] 69.42
|
|
[2024-Apr-09 19:14:38.3077759] (DEBUG): ["woah", "LEVELS!"] 69.42
|
|
```
|
|
|
|
You can see the [full API](https://dlog.dpldocs.info/) for more information.
|
|
|
|
### Custom loggers
|
|
|
|
#### Implementing your own transform
|
|
|
|
Perhaps the default transformation, `DefaultTransform`, may not be what you want. Maybe you want the module name included in the logged
|
|
messages or perhaps don't want the date-and-timestamp included at all. All of this can be up to you if you choose to implement your own
|
|
message transform.
|
|
|
|
You will need to start off with a class that inherits from the `Transform` class and then which overrides the `transform` method as shown below:
|
|
|
|
```d
|
|
import dlog;
|
|
|
|
public class CustomTransform : Transform
|
|
{
|
|
public override Message transform(Message message)
|
|
{
|
|
BasicMessage bmesg = cast(BasicMessage)message;
|
|
|
|
// Only handle BasicMessage(s) - ones which have `setText(string)`
|
|
if(bmesg is null)
|
|
{
|
|
return message;
|
|
}
|
|
|
|
string transformed;
|
|
/* Insert transformation code here */
|
|
bmesg.setText(transformed);
|
|
|
|
return message;
|
|
}
|
|
}
|
|
```
|
|
|
|
## License
|
|
|
|
LGPL v3
|