docker.recipes

Grafana Loki Logging Stack

intermediate

Grafana Loki logging stack with Promtail for log aggregation and visualization.

Overview

Grafana Loki is a horizontally scalable log aggregation system inspired by Prometheus, designed to efficiently store and query logs using label-based indexing rather than full-text search. Unlike traditional logging solutions that index entire log content, Loki indexes only metadata labels, making it significantly more cost-effective while providing powerful querying capabilities through its LogQL query language. This approach makes Loki particularly attractive for organizations already using Prometheus for metrics, as it follows similar labeling principles and integrates natively with Grafana. This deployment creates a complete logging stack with three interconnected services: Loki as the central log storage engine, Promtail as the log collection agent, and Grafana for visualization and querying. Promtail automatically discovers and ships logs from the host system and Docker containers to Loki, which stores them efficiently using its unique indexing strategy. Grafana connects directly to Loki as a data source, providing rich dashboards and real-time log exploration capabilities through its Explore interface. This stack is ideal for teams wanting to implement centralized logging without the complexity and cost of Elasticsearch-based solutions. It's particularly valuable for Kubernetes environments, development teams needing quick log analysis, and organizations building comprehensive observability platforms. The combination provides enterprise-grade log aggregation capabilities while maintaining simplicity in deployment and operation, making it accessible to both small teams and large-scale production environments.

Key Features

  • Label-based log indexing inspired by Prometheus for efficient storage and querying
  • LogQL query language for powerful log filtering, parsing, and aggregation
  • Promtail agent with automatic Docker container and system log discovery
  • Native Grafana integration with built-in Loki data source support
  • Multi-tenant architecture supporting isolated log streams per tenant or environment
  • Cost-effective storage model that doesn't require full-text indexing
  • Real-time log streaming and alerting capabilities through Grafana
  • Horizontal scalability with support for object storage backends like S3

Common Use Cases

  • 1Kubernetes cluster log aggregation and monitoring across multiple namespaces
  • 2Application troubleshooting and debugging with correlated metrics and logs in Grafana
  • 3Docker container log centralization for microservices architectures
  • 4Development environment log analysis without expensive enterprise tools
  • 5Infrastructure monitoring combining system logs with Prometheus metrics
  • 6Security incident investigation using label-based log filtering and correlation
  • 7Multi-environment log management with tenant isolation between dev, staging, and production

Prerequisites

  • Docker host with at least 2GB RAM (1GB+ for Loki, 512MB+ for Grafana, 256MB for Promtail)
  • Available ports 3000 (Grafana) and 3100 (Loki) on the host system
  • Promtail configuration file (promtail-config.yaml) defining log sources and Loki endpoint
  • Environment variables GF_ADMIN_USER and GF_ADMIN_PASSWORD for Grafana authentication
  • Basic understanding of LogQL syntax for effective log querying and dashboard creation
  • Read access to /var/log and Docker container logs directory for Promtail collection

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  loki: 
3    image: grafana/loki:2.9.0
4    container_name: loki
5    ports: 
6      - "3100:3100"
7    volumes: 
8      - loki_data:/loki
9    command: -config.file=/etc/loki/local-config.yaml
10    networks: 
11      - loki-network
12
13  promtail: 
14    image: grafana/promtail:2.9.0
15    container_name: promtail
16    volumes: 
17      - /var/log:/var/log:ro
18      - /var/lib/docker/containers:/var/lib/docker/containers:ro
19      - ./promtail-config.yaml:/etc/promtail/config.yml:ro
20    command: -config.file=/etc/promtail/config.yml
21    networks: 
22      - loki-network
23
24  grafana: 
25    image: grafana/grafana:latest
26    container_name: grafana
27    environment: 
28      - GF_SECURITY_ADMIN_USER=${GF_ADMIN_USER}
29      - GF_SECURITY_ADMIN_PASSWORD=${GF_ADMIN_PASSWORD}
30    ports: 
31      - "3000:3000"
32    volumes: 
33      - grafana_data:/var/lib/grafana
34    depends_on: 
35      - loki
36    networks: 
37      - loki-network
38
39volumes: 
40  loki_data: 
41  grafana_data: 
42
43networks: 
44  loki-network: 
45    driver: bridge

.env Template

.env
1# Grafana Loki Stack
2GF_ADMIN_USER=admin
3GF_ADMIN_PASSWORD=admin123

Usage Notes

  1. 1Grafana at http://localhost:3000
  2. 2Add Loki as datasource (http://loki:3100)
  3. 3Create promtail-config.yaml
  4. 4Label-based log querying
  5. 5LogQL for queries

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

loki
loki:
  image: grafana/loki:2.9.0
  container_name: loki
  ports:
    - "3100:3100"
  volumes:
    - loki_data:/loki
  command: "-config.file=/etc/loki/local-config.yaml"
  networks:
    - loki-network
promtail
promtail:
  image: grafana/promtail:2.9.0
  container_name: promtail
  volumes:
    - /var/log:/var/log:ro
    - /var/lib/docker/containers:/var/lib/docker/containers:ro
    - ./promtail-config.yaml:/etc/promtail/config.yml:ro
  command: "-config.file=/etc/promtail/config.yml"
  networks:
    - loki-network
grafana
grafana:
  image: grafana/grafana:latest
  container_name: grafana
  environment:
    - GF_SECURITY_ADMIN_USER=${GF_ADMIN_USER}
    - GF_SECURITY_ADMIN_PASSWORD=${GF_ADMIN_PASSWORD}
  ports:
    - "3000:3000"
  volumes:
    - grafana_data:/var/lib/grafana
  depends_on:
    - loki
  networks:
    - loki-network

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  loki:
5    image: grafana/loki:2.9.0
6    container_name: loki
7    ports:
8      - "3100:3100"
9    volumes:
10      - loki_data:/loki
11    command: -config.file=/etc/loki/local-config.yaml
12    networks:
13      - loki-network
14
15  promtail:
16    image: grafana/promtail:2.9.0
17    container_name: promtail
18    volumes:
19      - /var/log:/var/log:ro
20      - /var/lib/docker/containers:/var/lib/docker/containers:ro
21      - ./promtail-config.yaml:/etc/promtail/config.yml:ro
22    command: -config.file=/etc/promtail/config.yml
23    networks:
24      - loki-network
25
26  grafana:
27    image: grafana/grafana:latest
28    container_name: grafana
29    environment:
30      - GF_SECURITY_ADMIN_USER=${GF_ADMIN_USER}
31      - GF_SECURITY_ADMIN_PASSWORD=${GF_ADMIN_PASSWORD}
32    ports:
33      - "3000:3000"
34    volumes:
35      - grafana_data:/var/lib/grafana
36    depends_on:
37      - loki
38    networks:
39      - loki-network
40
41volumes:
42  loki_data:
43  grafana_data:
44
45networks:
46  loki-network:
47    driver: bridge
48EOF
49
50# 2. Create the .env file
51cat > .env << 'EOF'
52# Grafana Loki Stack
53GF_ADMIN_USER=admin
54GF_ADMIN_PASSWORD=admin123
55EOF
56
57# 3. Start the services
58docker compose up -d
59
60# 4. View logs
61docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/grafana-loki-promtail/run | bash

Troubleshooting

  • Promtail 'no such file or directory' error: Ensure promtail-config.yaml exists and verify volume mount paths match your system
  • Loki connection refused in Grafana: Check that Loki service is running and use http://loki:3100 as the data source URL
  • No logs appearing in Grafana: Verify Promtail configuration targets correct log paths and Loki endpoint is reachable
  • Grafana login fails: Check GF_ADMIN_USER and GF_ADMIN_PASSWORD environment variables are properly set
  • High memory usage in Loki: Adjust retention policies and consider using object storage for older logs
  • LogQL queries timing out: Use more specific label filters to reduce query scope and improve performance

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

lokigrafanapromtail

Tags

#loki#grafana#promtail#logging#observability

Category

Monitoring & Observability

Related Recipes

Ad Space