Loki4j is the simplest way to push logs from your Java application to Loki and to connect them with all other metrics using Grafana dashboards. No extra tools needed, just add Loki4j appender to your Logback configuration and enjoy.

Quick Start

For Maven project add the following dependency to your pom.xml:

<dependency>
    <groupId>com.github.loki4j</groupId>
    <artifactId>loki-logback-appender</artifactId>
    <version>1.4.2</version>
</dependency>

<dependency>
    <groupId>com.github.loki4j</groupId>
    <artifactId>loki-logback-appender-jdk8</artifactId>
    <version>1.4.2</version>
</dependency>
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.14</version>
</dependency>

For Gradle project add the following dependency to your build.gradle:

implementation 'com.github.loki4j:loki-logback-appender:1.4.2'

implementation 'com.github.loki4j:loki-logback-appender-jdk8:1.4.2'
implementation 'org.apache.httpcomponents:httpclient:4.5.14'

Then add Loki appender to your logback.xml:

<appender name="LOKI" class="com.github.loki4j.logback.Loki4jAppender">
    <http>
        <url>http://localhost:3100/loki/api/v1/push</url>
    </http>
    <format>
        <label>
            <pattern>app=my-app,host=${HOSTNAME},level=%level</pattern>
        </label>
        <message>
            <pattern>l=%level h=${HOSTNAME} c=%logger{20} t=%thread | %msg %ex</pattern>
        </message>
        <sortByTime>true</sortByTime>
    </format>
</appender>

<root level="DEBUG">
    <appender-ref ref="LOKI" />
</root>

<appender name="LOKI" class="com.github.loki4j.logback.Loki4jAppender">
    <http class="com.github.loki4j.logback.ApacheHttpSender">
        <url>http://localhost:3100/loki/api/v1/push</url>
    </http>
    <format>
        <label>
            <pattern>app=my-app,host=${HOSTNAME},level=%level</pattern>
        </label>
        <message>
            <pattern>l=%level h=${HOSTNAME} c=%logger{20} t=%thread | %msg %ex</pattern>
        </message>
        <sortByTime>true</sortByTime>
    </format>
</appender>

<root level="DEBUG">
    <appender-ref ref="LOKI" />
</root>

For more details, please refer to Docs.

Migrating from the previous version? Read the Migration Guide.

Key Features:

• Support for both JSON and Protobuf formats. With Loki4j you can try out both JSON and Protobuf API for sending log records to Loki. Learn more...

• Compatibility with Grafana Cloud. Loki4j supports HTTP basic authentication, so you can use it for hosted Loki services (e.g. Grafana Cloud) as well as for on-premise Loki instances. See the example...

• Flexible management of Loki labels using MDC and SLF4J Markers. You can specify Loki labels dynamically for any set of log records, and even on per-record basis. Learn more...

• Logback formatting patterns are used for both labels and messages. Loki4j allows you to use all the power and flexibility of Logback patterns both for labels and messages. Same patterns are used in Logback's standard ConsoleAppender or FileAppender, so you are probably familiar with the syntax.

• Optional sorting of log records by timestamp before sending them to Loki. In Loki versions pre 2.4.0, to prevent log records loss, Loki4j can sort log records by timestamp inside each batch, so they will not be rejected by Loki with 'entry out of order' error.

• No JSON library bundled. Instead of bundling with any JSON library (e.g. Jackson), Loki4j comes with a small part of JSON rendering functionality borrowed from DSL-JSON.

• Zero-dependency. Loki4j does not bring any new transitive dependencies to your project, assuming that you already use logback-classic for logging. See the example...

• Logging performance metrics. You can monitor Loki4j's performance (e.g. encode/send duration, number of batches sent, etc.) by enabling instrumentation powered by Micrometer. Learn more...

Project Status

At the moment all the main logging features are implemented and stabilized.

Further development will be concentrated on bug fixes (if any), keeping up with new versions of Loki, and improving the codebase so it's easier to maintain.

If you have found this project helpful, please drop a ☆ on GitHub.