Docker Integration

Collect logs from Docker containers automatically with LogFlux Agent

The LogFlux Docker plugin automatically collects logs from all Docker containers running on your system. It integrates seamlessly with Docker’s logging system and provides real-time log streaming with full metadata enrichment.

Overview

The Docker plugin provides:

Automatic Discovery: Detects all running containers automatically
Real-time Collection: Streams logs as they’re generated
Metadata Enrichment: Adds container name, image, labels, and environment info
Multi-line Support: Handles stack traces and multi-line log entries
Filtering Options: Include/exclude containers based on labels or names
Batch Processing: Efficient log batching for high-throughput scenarios

Installation

The Docker plugin is included with the LogFlux Agent but disabled by default.

Prerequisites

LogFlux Agent installed (see Installation Guide)
Docker daemon running
User permissions to access Docker socket

Enable the Plugin

1
2
3
4
5


# Enable and start the Docker plugin
sudo systemctl enable --now logflux-docker

# Check status
sudo systemctl status logflux-docker

Configuration

Basic Configuration

Create or edit the Docker plugin configuration:

1

sudo nano /etc/logflux-agent/plugins/docker.yaml

Basic configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# Docker Plugin Configuration
docker:
  # Docker socket path
  socket: "unix:///var/run/docker.sock"
  
  # Include all containers by default
  include_all: true
  
  # Add container metadata to logs
  add_metadata: true

# Log processing
batching:
  # Batch size for log entries
  size: 100
  # Flush interval
  interval: 5s

# Filtering (optional)
filters:
  # Include only containers with specific labels
  include_labels:
    - "logging.enabled=true"
  
  # Exclude containers by name pattern
  exclude_names:
    - "^logflux-.*"
    - "^test-.*"

Advanced Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


# Advanced Docker Plugin Configuration
docker:
  socket: "unix:///var/run/docker.sock"
  
  # Connection settings
  timeout: 30s
  retry_attempts: 3
  
  # Log collection settings
  collect_existing: false    # Only new logs (don't collect existing)
  follow: true              # Follow log streams
  timestamps: true          # Include Docker timestamps
  
  # Container filtering
  include_labels:
    - "com.docker.compose.project=production"
    - "app.tier=backend"
  
  exclude_labels:
    - "logging.exclude=true"
  
  include_names:
    - "^web-.*"
    - "^api-.*"
  
  exclude_names:
    - "^temp-.*"
    - "^debug-.*"

# Multi-line log handling
multiline:
  # Stack trace patterns
  patterns:
    - pattern: '^\s+'
      match: after
    - pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}'
      match: after
      negate: true

# Performance settings
performance:
  # Buffer size for log collection
  buffer_size: 64KB
  # Maximum concurrent containers
  max_containers: 100
  # Log line size limit
  max_line_size: 16KB

# Metadata enrichment
metadata:
  # Include container metadata
  container_name: true
  container_id: true
  image_name: true
  image_tag: true
  
  # Include container labels
  include_labels: true
  label_prefix: "docker."
  
  # Include environment variables (be careful with secrets)
  include_env: false
  env_whitelist: []

Docker Compose Integration

For Docker Compose environments, use labels to control logging:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# docker-compose.yml
version: '3.8'

services:
  web:
    image: nginx:alpine
    labels:
      - "logging.enabled=true"
      - "logging.level=info"
      - "app.tier=frontend"
    
  api:
    image: myapp:latest
    labels:
      - "logging.enabled=true"
      - "logging.level=debug"
      - "app.tier=backend"
    
  cache:
    image: redis:alpine
    labels:
      - "logging.exclude=true"  # Skip Redis logs

Usage Examples

Monitor All Containers

1
2
3
4
5


# Enable Docker plugin with default settings
sudo systemctl enable --now logflux-docker

# View plugin status
sudo journalctl -u logflux-docker -f

Filter by Container Labels

1
2
3
4
5
6
7
8
9


# /etc/logflux-agent/plugins/docker.yaml
docker:
  socket: "unix:///var/run/docker.sock"
  include_all: false

filters:
  include_labels:
    - "environment=production"
    - "logging=enabled"

Exclude System Containers

1
2
3
4
5
6
7


# /etc/logflux-agent/plugins/docker.yaml
filters:
  exclude_names:
    - "^logflux-.*"
    - "^prometheus-.*"
    - "^grafana-.*"
    - "^nginx-proxy$"

Multi-line Stack Traces

1
2
3
4
5
6
7
8


# Handle Java stack traces
multiline:
  patterns:
    - pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}'
      match: after
      negate: true
    - pattern: '^\s+at\s+'
      match: after

Container Log Metadata

The Docker plugin automatically adds metadata to each log entry:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
  "timestamp": "2024-01-20T14:30:45.123Z",
  "level": "info",
  "message": "Request processed successfully",
  "node": "docker-host-01",
  "docker": {
    "container_id": "abc123def456",
    "container_name": "web-server",
    "image": "nginx:alpine",
    "image_tag": "alpine",
    "labels": {
      "com.docker.compose.service": "web",
      "environment": "production",
      "app.tier": "frontend"
    }
  }
}

Performance Considerations

High-Volume Environments

For environments with many containers or high log volume:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Optimized configuration for high volume
performance:
  buffer_size: 1MB
  max_containers: 500
  max_line_size: 64KB

batching:
  size: 1000
  interval: 2s

# Reduce metadata collection
metadata:
  include_labels: false
  include_env: false

Resource Limits

Set appropriate resource limits for the Docker plugin:

1
2


# Edit systemd service
sudo systemctl edit logflux-docker

Add resource limits:

1
2
3


[Service]
MemoryLimit=512M
CPUQuota=50%

Troubleshooting

Check Plugin Status

1
2
3
4
5
6
7
8


# Check if plugin is running
sudo systemctl status logflux-docker

# View plugin logs
sudo journalctl -u logflux-docker -f

# Check Docker socket permissions
ls -la /var/run/docker.sock

Docker Socket Permissions

If the plugin cannot access Docker:

1
2
3
4
5


# Add logflux user to docker group
sudo usermod -a -G docker logflux

# Restart the service
sudo systemctl restart logflux-docker

Container Not Detected

1
2
3
4
5
6
7
8
9


# Check container labels
docker inspect <container-name> | jq '.Config.Labels'

# Verify filters in configuration
sudo nano /etc/logflux-agent/plugins/docker.yaml

# Test configuration
sudo systemctl restart logflux-docker
sudo journalctl -u logflux-docker -n 50

High Memory Usage

1
2
3
4
5


# Check buffer usage
docker stats logflux-docker

# Reduce buffer sizes in configuration
sudo nano /etc/logflux-agent/plugins/docker.yaml

Adjust settings:

1
2
3
4
5
6
7


performance:
  buffer_size: 256KB
  max_line_size: 8KB

batching:
  size: 500
  interval: 10s

Missing Logs

Check for common issues:

Container stopped quickly: Enable collect_existing: true
Multi-line logs split: Configure multi-line patterns
Filtered out: Check include/exclude filters
Permission denied: Verify Docker socket access

Security Considerations

Docker Socket Access

The Docker socket provides powerful system access:

1
2


# Run with minimal permissions
sudo systemctl edit logflux-docker

1
2
3
4
5
6
7
8


[Service]
User=logflux
Group=docker
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/tmp /var/lib/logflux-agent

Sensitive Data

Be careful with environment variables and labels:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# Avoid collecting sensitive environment variables
metadata:
  include_env: false

# Or use whitelist for safe variables only
metadata:
  include_env: true
  env_whitelist:
    - "NODE_ENV"
    - "LOG_LEVEL"
    - "SERVICE_NAME"

Integration Examples

Kubernetes + Docker

When running in Kubernetes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# kubernetes-optimized-docker.yaml
docker:
  socket: "unix:///var/run/docker.sock"
  
filters:
  # Include only non-Kubernetes containers
  exclude_labels:
    - "io.kubernetes.pod.name"
  
  # Or include specific Kubernetes namespaces
  include_labels:
    - "io.kubernetes.pod.namespace=production"

Docker Swarm

For Docker Swarm environments:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# docker-swarm.yaml
docker:
  socket: "unix:///var/run/docker.sock"

filters:
  include_labels:
    - "com.docker.swarm.service.name"
    
metadata:
  include_labels: true
  label_prefix: "swarm."

CI/CD Integration

For continuous integration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# ci-optimized.yaml
docker:
  collect_existing: true  # Collect logs from short-lived containers
  
filters:
  include_labels:
    - "ci.job=true"
  
batching:
  size: 50    # Smaller batches for quick feedback
  interval: 1s

Monitoring and Alerting

Plugin Health Checks

Monitor plugin health:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#!/bin/bash
# /usr/local/bin/check-docker-plugin.sh

if ! systemctl is-active --quiet logflux-docker; then
    echo "CRITICAL: LogFlux Docker plugin is not running"
    exit 2
fi

# Check if plugin is collecting logs
if ! journalctl -u logflux-docker --since="5 minutes ago" | grep -q "collected"; then
    echo "WARNING: No logs collected in last 5 minutes"
    exit 1
fi

echo "OK: LogFlux Docker plugin is healthy"
exit 0

Container Discovery Alerts

Set up alerts for container discovery issues:

1
2
3
4
5
6


# Monitor for permission errors
journalctl -u logflux-docker -f | grep -i "permission denied" | \
while read line; do
    echo "ALERT: Docker permission issue - $line" | \
    mail -s "LogFlux Docker Alert" admin@company.com
done

Disclaimer

Docker and the Docker logo are trademarks of Docker, Inc. LogFlux is not affiliated with, endorsed by, or sponsored by Docker, Inc. The Docker logo is used solely for identification purposes to indicate compatibility with Docker containers and the Docker platform.

Next Steps

Kubernetes Integration - Monitor pod logs
Nginx Integration - Web server log analysis
LogFlux Inspector - Analyze collected Docker logs
API Reference - Query Docker logs programmatically