From 7fd1a21c14434d9cedf25b3ffc0b43644b1a6ccb Mon Sep 17 00:00:00 2001 From: "tomasz.kowalczewski" Date: Sat, 13 Mar 2021 16:52:56 +0100 Subject: [PATCH] Re #36: Configuration options discussion. --- README.md | 52 ++++++-------------------------------- log4j2-appender/README.md | 49 ++++++++++++++++++++++++++++++++++- logback-appender/README.md | 51 ++++++++++++++++++++++++++++++++++++- 3 files changed, 106 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 6d91d94..e94dce0 100644 --- a/README.md +++ b/README.md @@ -9,62 +9,26 @@ Latest releases: [![Maven Central](https://img.shields.io/maven-central/v/pl.tkowalcz.tjahzi/core.svg?label=Core&style=for-the-badge)](https://search.maven.org/search?q=g:pl.tkowalcz.tjahzi) [![Maven Central](https://img.shields.io/maven-central/v/pl.tkowalcz.tjahzi/log4j2-appender.svg?label=Log4j2%20Appender&style=for-the-badge)](https://search.maven.org/search?q=g:pl.tkowalcz.tjahzi) +[![Maven Central](https://img.shields.io/maven-central/v/pl.tkowalcz.tjahzi/logback-appender.svg?label=Logback%20Appender&style=for-the-badge)](https://search.maven.org/search?q=g:pl.tkowalcz.tjahzi) ## Features Tjahzi allows pushing log data to Loki. It uses protobuf format to push log lines with timestamps and labels to Loki. This -is implemented in the `core` component. On top of that we built the `log4j2 appender`. It's features include: +is implemented in the `core` component. On top of that we built appenders for `log4j2` and `Logback`. These feature: 1. Logging does not allocate objects nor take any locks. 1. Sending data to Loki in batches allocates as little as possible. -1. We also provide a no-dependency version of log4j2 appender. -1. Includes in-house implementation of protobuf wire format for Loki to reduce dependencies and improve performance +1. We also provide a no-dependency versions of these appenders. +1. Includes in-house implementation of protobuf wire format for Loki to reduce dependencies and improve performance. -It is currently used (that I know of) to ship logs from tens of servers at about 10GB of logs per day. +Log4j2 appender is currently used to ship logs from tens of servers at about 10GB of logs per day. ## Getting started -1. Grab the no-dependency version of the appender: - - ```xml - - pl.tkowalcz.tjahzi - log4j2-appender-nodep - 0.9.4 - - ``` - - If you already use a compatible version of Netty in your project then to reduce the size of your dependencies include - regular appender distribution: - - ```xml - - pl.tkowalcz.tjahzi - log4j2-appender - 0.9.4 - - ``` - -1. Add `packages="pl.tkowalcz.tjahzi.log4j2"` attribute to your log4j2 configuration xml. -1. Include minimal appender configuration +For `log4j2` appender quick start guide and detailed discussions see this [README.md](log4j2-appender/README.md). +For `Logback` appender quick start guide and detailed discussions see this [README.md](logback-appender/README.md). -```xml - - ${sys:loki.host} - ${sys:loki.port} - - - %X{tid} [%t] %d{MM-dd HH:mm:ss.SSS} %5p %c{1} - %m%n%exception{full} - - - -``` - -Detailed discussion of how to configure the appender with examples and description of all possible tags check -[Log4j2 appender docs](log4j2-appender/README.md). - -## Design principles +## Core design principles Logging should be lightweight and not interfere with main business tasks of threads that happen to log a message. Asking the logging subsystem to log a message should be as CPU efficient as possible. diff --git a/log4j2-appender/README.md b/log4j2-appender/README.md index 912119a..9c0a314 100644 --- a/log4j2-appender/README.md +++ b/log4j2-appender/README.md @@ -3,7 +3,54 @@ On top of a `Core` component with rather simplistic API we intend to build several layers that make it truly useful. Log4j2 appender seemed like a good first. -## Example Log4j2 configuration +## Quick start guide + +1. Grab the no-dependency version of the appender: + + ```xml + + pl.tkowalcz.tjahzi + log4j2-appender-nodep + 0.9.4 + + ``` + + If you already use a compatible version of Netty in your project then to reduce the size of your dependencies include + regular appender distribution: + + ```xml + + pl.tkowalcz.tjahzi + log4j2-appender + 0.9.4 + + ``` + +1. Add `packages="pl.tkowalcz.tjahzi.log4j2"` attribute to your existing log4j2 configuration file. +1. Include minimal appender configuration: + +```xml + + ${sys:loki.host} + ${sys:loki.port} + + + %X{tid} [%t] %d{MM-dd HH:mm:ss.SSS} %5p %c{1} - %m%n%exception{full} + + + +``` + +1. Reference the appender from inside one of your logger definitions: + +```xml + + + +``` + +## Advanced configuration This example sets up a root logger with a Loki appender. Note that `pl.tkowalcz.tjahzi.log4j2` is added to `packages` attribute of configuration so that the appender can be found. diff --git a/logback-appender/README.md b/logback-appender/README.md index 2797f5b..09a6d3c 100644 --- a/logback-appender/README.md +++ b/logback-appender/README.md @@ -2,7 +2,56 @@ On top of the `Core` component that sends logs to Loki this project gives you Logback appender. -## Example configuration +## Quick start guide + +1. Grab the no-dependency version of the appender: + + ```xml + + pl.tkowalcz.tjahzi + logback-appender-nodep + 0.1.0 + + ``` + + If you already use a compatible version of Netty in your project then to reduce the size of your dependencies include + regular appender distribution: + + ```xml + + pl.tkowalcz.tjahzi + logback-appender + 0.1.0 + + ``` + +1. Include minimal appender configuration in your existing logback configuration: + +```xml + + ${loki.host} + ${loki.port} + + + %-4relative [%thread] %-5level %logger{35} - %msg%n + + + + +``` + +1. Reference the appender from inside one of your logger definitions: + +```xml + + + +``` + +## Advanced configuration This example sets up a root logger with Loki appender. The appender definition must point to class `pl.tkowalcz.tjahzi.logback.LokiAppender`.