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

The current stable version of Loki4j requires Java 11+ and Logback v1.4.x. See the compatibility matrix for more information about older versions' support.

Add the following dependency to your project:

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

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

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>
            <!-- Labels -->
            <pattern>
                app = my-app,
                host = ${HOSTNAME}
            </pattern>
            <!-- Structured metadata (since Loki v2.9.0) -->
            <structuredMetadataPattern>
                level = %level,
                thread = %thread,
                class = %logger,
                traceId = %mdc{traceId:-none}
            </structuredMetadataPattern>
        </label>
        <message>
            <pattern>%-5level %logger{20} %msg %ex</pattern>
        </message>
    </format>
</appender>

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

<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}</pattern>
        </label>
        <message class="com.github.loki4j.logback.JsonLayout" />
    </format>
</appender>

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

For more details, please refer to Docs.

Migrating from the previous Loki4j version? Read the Migration Guide.

Key Features:

• Loki labels can be dynamically generated out of any Logback pattern, MDC, and SLF4J markers. Label values are specified as Logback patterns. This along with MDC and markers allows you to precisely control label set for each particular log record. Learn more...

• Structured metadata support. Unlike labels, structured metadata is not indexed, but it still can significantly increase search efficiency, as Loki does not have to scan entire message bodies for metadata. Loki4j provides the same capabilities of dynamic generation for structured metadata as it does for labels. Learn more...

• Fast JSON layout for log message formatting. If you prefer Logstash-like log message formatting, you can switch the layout from plain text to JSON. Learn more...

• Support of JSON and Protobuf Loki API flavors. By default, JSON endpoints are used, but you can switch to Protobuf API anytime. 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...

• Zero-dependency. Loki4j jar has a very small footprint. It does not bring any new transitive dependencies to your project, assuming you already use logback-classic for logging. See the example...

• 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 have been 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.