Build a Lightweight Java Logging System with Loki, Loki4j, and Grafana

In software development, logging systems are essential for debugging and monitoring applications in production.

This guide shows how to build a lightweight Java logging solution using Loki, Loki4j, Grafana, and Spring Boot.

System Component Overview

What is Loki?

Loki is an open‑source, highly available, horizontally scalable, multi‑tenant log aggregation system from Grafana Labs, inspired by Prometheus. It stores logs efficiently by indexing only metadata (timestamps, labels) and compressing log data, which reduces storage costs and improves query performance.

What is Loki4j?

Loki4j is a Java log appender that sends log events directly to a Loki server. It integrates smoothly with Spring Boot applications using Logback or Log4j2, providing a simple yet powerful logging solution for Java developers.

What is Grafana?

Grafana is an open‑source visualization and monitoring platform that supports many data sources, including Loki. It enables users to create dynamic, customizable dashboards to display log data intuitively.

Setup Steps

1. Install Loki and Grafana

Use Docker to quickly deploy both services.

# Install Loki
docker run -d --name loki -p 3100:3100 grafana/loki:latest -config.file=/etc/loki/local-config.yaml

# Install Grafana
docker run -d --name grafana -p 3000:3000 grafana/grafana:latest

2. Configure Loki4j

Add the Loki4j dependency to your pom.xml:

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

Create a logback.xml in src/main/resources with the following configuration:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- Spring application name -->
    <springProperty name="name" source="spring.application.name"/>

    <!-- Console appender -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [thread %thread] %-5level %logger{35}.%method - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Loki appender -->
    <appender name="LOKI" class="com.github.loki4j.logback.Loki4jAppender">
        <http>
            <url>http://localhost:3100/loki/api/v1/push</url>
        </http>
        <format>
            <label>
                <pattern>application=${name},level=%level</pattern>
                <readMarkers>true</readMarkers>
            </label>
            <message>
                <pattern>
{"timestamp":"%d{yyyy-MM-dd HH:mm:ss.SSS}","level":"%level","logger":"%logger{36}.%method","method":"%M","line":"%line","thread":"%thread","message":"%msg%n"}
                </pattern>
            </message>
            <sortByTime>true</sortByTime>
        </format>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="LOKI"/>
    </root>
</configuration>

3. Configure Grafana

Open Grafana at http://localhost:3000 (default admin/admin), change the password, add Loki as a data source, and point it to the running Loki service.

4. Run the Spring Boot Application

Start your Spring Boot service; all logs will be sent to Loki and can be viewed in Grafana.

5. View Logs

In Grafana, create a dashboard using Loki as the data source, or use the Explore view. Select the appropriate label (e.g., application) and value (e.g., muqing-api), then run the query to see the logs.

Conclusion

By following these steps you have built a simple Java logging system that combines Loki’s powerful log aggregation, Loki4j’s easy log shipping, and Grafana’s visualization. In real projects you may need to consider additional aspects such as security.

Future articles will cover Loki’s alternative collector Promtail, which offers flexible deployment and format support.