Daily-It

Grafana Loki Guide: Build a Log Collection System with Docker Compose

Summary

Grafana Loki is a log collection system that finds log streams based on labels without heavily indexing all of the logs. As of June 2026, the latest release is the Loki 3.7.x series, and if you follow the old Loki 3.0 standard article, old information may be mixed in Promtail, label design, and storage configuration. In this article, we will summarize how to configure a test environment with Docker Compose and common failure cases in actual operation.

Table of Contents

Background

When you first encounter Loki, it’s easy to think of it as a system that indexes the entire log body like Elasticsearch. But Loki’s core is different. Rather than indexing the entire log body, job, service_name, namespace, container Find log streams with the same label and filter by LogQL within them.

This structure has advantages in terms of cost and storage efficiency, but if the label is designed incorrectly, performance deteriorates. especially request_id, user_id, trace_idIf you put data whose value is constantly changing like this as a label, the cardinality explodes.

Another important change is Promtail. Based on Grafana’s official documentation, Promtail reached EOL on March 2, 2026, and future feature development will be conducted on Grafana Alloy. Existing Promtail examples are still widely searched, but if you are constructing a new one, it is safer to look at Alloy as a standard.

Understanding Loki Architecture

Loki-based log collection is usually divided into three parts:

Component Role
Loki A server that stores logs and processes LogQL queries.
Alloy or log collection agent Read files, containers, and Kubernetes logs and send them to Loki
Grafana Connect Loki data sources to search logs and configure dashboards/alerts

For a small test environment, running Loki as a single binary is sufficient. However, in a production environment, you need to consider storage, replication, retention period, query performance, multi-tenancy, and even notifications.

Docker Compose Test Setup

The official documentation states that Docker or Docker Compose can be used for evaluation, testing, and development purposes. For production environments, we recommend deployment methods such as Helm or Tanka.

For testing purposes, you can start with a simple configuration as shown below.

services:
  loki:
    image: grafana/loki:3.7.0
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=****
    depends_on:
      - loki

Run.

docker compose up -d

Loki status can be checked as follows:

curl http://localhost:3100/ready

If it’s normal readyYou can see a response close to . Grafana is accessed from your browser.

http://localhost:3000

This configuration is for learning purposes only. In actual operation, you should avoid relying on file system storage alone or storing logs for a long period of time in a single container.

Why You Should Look at Alloy Instead of Promtail

Most of the older Loki tutorials use Promtail. However, as of official documentation, Promtail is in EOL status.

Promtail EOL: 2026-03-02
향후 기능 개발: Grafana Alloy

If you are already using Promtail in an existing production environment, this will not be an immediate outage. However, if you are building something new or writing a new article, it is correct to look at Alloy-based configuration as well. Grafana also provides a guided migration tool to convert Promtail settings to Alloy settings.

That said, the recommended direction for current standards is:

새 프로젝트: Alloy 우선 검토
기존 Promtail 운영: 마이그레이션 계획 수립
단기 테스트: 기존 예제 참고 가능하나 EOL 상태 명시

Label Design and Storage Caveats

In Loki, labels are the starting point for searches. The official documentation advises to use labels with low cardinality values ​​that describe the log source.

Some good label examples include:

service_name="api-server"
environment="prod"
namespace="backend"
container="nginx"

Examples of labels to avoid include:

request_id="a1b2c3..."
user_id="123456"
ip="203.0.113.10"
trace_id="..."

For high-cardinality values ​​that need to be searched frequently, you should consider filtering structured metadata or log body rather than labels.

Storage is also important. For local testing, you can use a file system, but for operational purposes, you should review object storage and retention policies such as S3, GCS, and Azure Blob. In particular, if retention is not set, logs may continue to pile up and cause disk or storage cost problems.

Failure Cases and Fixes

Case 1. Unable to connect to Loki data source in Grafana

In Grafana http://localhost:3100, but you may not be able to connect. This is because the address when the Grafana container accesses Loki in Docker Compose and the address accessed by the user’s browser are different.

Inside Compose, we use the service name.

http://loki:3100

When checking directly from the host, use:

curl http://localhost:3100/ready

In other words, the settings inside the Grafana container include localhostnot loki There are many cases where you need to enter the service name.

Case 2. No logs coming in, but Loki is normal

Even if Loki is floating, Grafana won’t see anything unless the log collection agent sends it properly.

First, check Loki’s status.

curl http://localhost:3100/ready

Next, view the collection agent log.

docker compose logs

Here’s what to check:

Loki push URL이 맞는가?
컨테이너 간 네트워크 이름이 맞는가?
로그 파일 경로가 컨테이너 안에서 보이는가?
라벨 설정 때문에 다른 stream으로 들어간 것은 아닌가?

Case 3. label valuesWhen there are too many and queries become slow.

This is the most common operational mistake in Loki. pod, container, namespace This may be okay, but if you put a value that changes with each request as a label, the number of streams will increase dramatically.

If you suspect a problem, start by checking the label list.

{service_name="api-server"}

In our operations, we adhere to the following principles:

라벨은 낮은 카디널리티 값만 사용
사용자 ID, 요청 ID, 세션 ID는 라벨로 넣지 않기
자주 바뀌는 값은 structured metadata 또는 로그 본문으로 처리

Case 4. If you followed the Promtail example but it is different from the latest recommended method

There are tons of Promtail examples in search results. But Promtail is EOL. Therefore, when creating a new environment, you should check the Alloy documentation first.

If you have an existing Promtail setup, check the migration tool and Alloy documentation rather than deleting it right away.

Promtail 설정 백업
Alloy 마이그레이션 문서 확인
테스트 환경에서 변환 설정 검증
운영 반영 전 로그 유실 여부 확인

Case 5. If the storage continues to grow because the log retention period is not set

This is not often seen in testing, but occurs frequently in production. Logs pile up faster than you think. In particular, if you collect both debug logs and access logs, storage costs add up quickly.

Before operation, be sure to determine the following:

보존 기간
삭제 정책
저장소 타입
압축/청크 설정
환경별 로그 레벨

Case 6. Using Docker Compose test configuration as is for production

The official documentation also states that Docker Compose is suitable for evaluation, testing, and development purposes. Operations require separate design for failover, storage, scalability, security, authentication, and monitoring.

If operational, at a minimum, review the following:

Helm 기반 Kubernetes 배포
object storage 연동
retention 설정
Grafana 인증과 권한
Loki 자체 모니터링
백업과 장애 복구

Best Practices

When first deploying Loki, it’s a good idea to start small and establish your operating standards in advance.

  • Start testing quickly with Docker Compose
  • New collection configurations reviewed on an Alloy basis
  • Start with fewer labels and increase as needed
  • Do not include high cardinality values ​​as labels
  • Design operational storage and retention first
  • Check log loss/storage cost/query performance before Grafana dashboard

Common Mistakes

Understanding Loki like Elasticsearch

Loki does not index the entire log body. Label design has a significant impact on search performance and cost.

Mistaking the Promtail example for the latest recommended practice

There are many Promtail examples, but they are currently EOL. New deployments should consider Alloy first.

localhost Using the address as is inside the container

Inside Docker Compose localhostis each container itself. When looking for Loki in Grafana http://loki:3100You may need to use the service name like this.

Continuing to accumulate logs without retention

The log continues to grow. Operating without a retention period and deletion policy will result in disk or object storage cost issues.

Conclusion

Grafana Loki is a good choice for creating a cost-effective log collection system. However, to use it properly, you need to understand label design, collection agent selection, storage, retention, and query patterns before installation instructions.

If you are building a new project in 2026, it is recommended that you consider the Loki 3.7.x document as a standard, and consider the Promtail example’s EOL status and Alloy conversion as well. Testing can start with Docker Compose, but operations must be designed separately, including Helm, object storage, retention, and monitoring.

References

  • Grafana Loki GitHub Release v3.7.2: https://github.com/grafana/loki/releases/tag/v3.7.2
  • Grafana Loki Docker installation documentation: https://grafana.com/docs/loki/latest/setup/install/docker/
  • Grafana Loki Promtail documentation: https://grafana.com/docs/loki/latest/send-data/promtail/
  • Grafana Loki Alloy documentation: https://grafana.com/docs/loki/latest/send-data/alloy/
  • Grafana Loki Labels documentation: https://grafana.com/docs/loki/latest/get-started/labels/
  • Grafana Loki Storage documentation: https://grafana.com/docs/loki/latest/operations/storage/
  • Grafana Loki Query documentation: https://grafana.com/docs/loki/latest/query/