tjahzi/logback-appender/README.md

Logback Appender

On top of the Core component that sends logs to Loki this project gives you Logback appender.

Quick start guide

1. Grab the no-dependency version of the appender:

   <dependency>
     <groupId>pl.tkowalcz.tjahzi</groupId>
     <artifactId>logback-appender-nodep</artifactId>
     <version>0.1.0</version>
   </dependency>
   

   If you already use a compatible version of Netty in your project then to reduce the size of your dependencies include regular appender distribution:

   <dependency>
     <groupId>pl.tkowalcz.tjahzi</groupId>
     <artifactId>logback-appender</artifactId>
     <version>0.1.0</version>
   </dependency>
   

2. Include minimal appender configuration in your existing logback configuration:

<appender name="Loki" class="pl.tkowalcz.tjahzi.logback.LokiAppender">
   <host>${loki.host}</host>
   <port>${loki.port}</port>

   <encoder>
      <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
   </encoder>
   
   <label>
      <name>server</name>
      <value>${HOSTNAME}</value>
   </label>
</appender>

1. Reference the appender from inside one of your logger definitions:

<root level="debug">
   <appender-ref ref="Loki"/>
</root>

Advanced configuration

This example sets up a root logger with Loki appender. The appender definition must point to class pl.tkowalcz.tjahzi.logback.LokiAppender.

<configuration>
    <appender name="Loki" class="pl.tkowalcz.tjahzi.logback.LokiAppender">
        <host>${loki.host}</host>
        <port>${loki.port}</port>

        <encoder>
            <pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n</pattern>
        </encoder>
        
        <header>
            <name>X-Org-Id</name>
            <value>Codewise</value>
        </header>

        <label>
            <name>server</name>
            <value>127.0.0.1</value>
        </label>

        <logLevelLabel>
            log_level
        </logLevelLabel>
    </appender>

    <root level="debug">
        <appender-ref ref="Loki"/>
    </root>
</configuration>

Lookups / variable substitution

Contents of the properties are automatically interpolated by Logback (see here). All environment, system etc. variable references will be replaced by their values during initialization of the appender.

Details

Let's go through the example config above and analyze configuration options (Note: Tags are case-insensitive).

Tag	Required	Default value	Description
Host	Y		Network host address of Loki instance. Either IP address or host name. It will be passed to Netty and end up being resolved by call to InetSocketAddress.createUnresolved.
Port	Y		Self-explanatory :)
Header	N	(empty list)	This tag can be used multiple times to specify additional headers that are passed to Loki instance. One example is to pass a X-Scope-OrgID header when running Loki in multi-tenant mode.
Label	N	(empty list)	Specify additional labels attached to each log line sent via this appender instance. See also note about label naming.
LogLevelLabel	N	null	If defined then log level label of configured name will be added to each line sent to Loki. It will contain Log4j log level e.g. INFO, WARN etc. See also note about label naming.
BufferSizeMegabytes	N	32 MB	Size of the log buffer. Must be power of two between 1MB and 1GB. See log buffer sizing for more explanations.
MaxRetries	N	3	Maximum number of retries to perform when delivering log message to Loki. Log buffer data is delivered in order, one batch after the other, so too much retries will block delivery of subsequent log batches (on the other hand if we need to retry many times then next batches will probably fail too).
ConnectTimeoutMillis	N	5s	This configures socket connect timeout when connecting to Loki. After unsuccessful connection attempt it will continue to retry indefinitely employing exponential backoff (initial backoff = 250ms, maximum backoff = 30s, multiplier = 3).
ReadTimeoutMillis	N	60s	Sets socket read timeout on Loki connection.
UseOffHeapBuffer	N	true	Whether Tjahzi should allocate native buffer for Log buffer component. We can go into a rabbit hole of divagations what are the implications of this. Most important in our view is that having 10s or 100s of MB of space taken out of heap is not very friendly to garbage collector which might have to occasionally copy it around.
BatchSize	N	100 KB	Like in promtail configuration maximum batch size (in bytes) of logs to accumulate before sending the batch to Loki.
BatchWait	N	5s	Like in promtail configuration maximum amount of time to wait before sending a batch, even if that batch isn't full.