How to Set Up Prometheus for Docker [Step-by-Step Guide]

February 24, 2025

5 min read

Prometheus is a go-to solution for monitoring containerized environments. This detailed guide will walk you through setting up Prometheus for Docker, helping you achieve robust monitoring for your containerized applications.

System Requirements

Before starting the setup, ensure your system meets these minimum requirements:

2 CPU cores
4GB RAM
Sufficient disk space for metric storage (depends on retention period)
Docker installed and running

Integrating Prometheus with Docker

Integrating Prometheus with Docker allows you to monitor your containerized applications effectively. This integration provides several benefits:

Easy deployment: Prometheus can be run as a Docker container, simplifying setup and management.
Service discovery: Prometheus can automatically discover and monitor Docker containers.
Resource efficiency: Both Prometheus and your applications can run in containers, optimizing resource usage.

Step-by-Step Setup of Prometheus for Docker

Let's start the process of setting up Prometheus for Docker monitoring:

Create a Prometheus configuration file (prometheus.yml):

yaml

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'docker'
    docker_sd_configs:
      - host: unix:///var/run/docker.sock
    relabel_configs:
      - source_labels: [__meta_docker_container_name]
        regex: '/(.*)'
        target_label: container_name
        replacement: '$1'

Create a Docker network for Prometheus:

bash

docker network create prometheus-network

Run Prometheus as a Docker container:

bash

docker run -d --name prometheus \
    --network prometheus-network \
    -p 9090:9090 \
    -v /path/to/prometheus.yml:/etc/prometheus/prometheus.yml \
    -v /var/run/docker.sock:/var/run/docker.sock \
    prom/prometheus

Verify Prometheus is running:
- Open a web browser and navigate to http://localhost:9090
- You should see the Prometheus web interface
Configure your Docker containers for Prometheus scraping:
- Add the following labels to your Docker containers:
  yaml
```
labels:
  - 'prometheus.io/scrape=true'
  - 'prometheus.io/port=<metrics-port>'
```
Restart your Docker containers with the new labels.
Check Prometheus targets:
- In the Prometheus web interface, go to Status > Targets
- You should see your Docker containers listed as targets

Best Practices for Using Prometheus with Docker

Use Docker labels to configure scraping: Add labels to your containers to control how Prometheus scrapes them.
Implement health checks: Use Docker health checks to ensure your containers are functioning correctly.
Monitor Docker itself: Set up Prometheus to monitor Docker engine metrics.
Use Grafana for visualization: Combine Prometheus with Grafana for powerful data visualization.
Implement alerting: Use Prometheus Alertmanager to set up alerts for critical issues.

Using Docker Compose for Prometheus

Here's an example docker-compose.yml file that sets up Prometheus:

yaml

version: '3'
services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - 9090:9090
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
      - '--web.console.templates=/usr/share/prometheus/consoles'

To use this configuration:

Save it as docker-compose.yml
Create a prometheus.yml file in the same directory
Run docker-compose up -d
Access Prometheus at http://localhost:9090

Additional Components

Setting Up Alertmanager

Alertmanager handles alerts from Prometheus. Here's a basic setup:

Create alertmanager.yml:

yaml

route:
  group_by: ['alertname']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 1h
  receiver: 'email-notifications'

receivers:
  - name: 'email-notifications'
    email_configs:
      - to: 'team@example.com'

Add Alertmanager to your Docker Compose file:

yaml

services:
  alertmanager:
    image: prom/alertmanager
    volumes:
      - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml
    ports:
      - 9093:9093

Update Prometheus configuration to use Alertmanager:

yaml

alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - alertmanager:9093

Using Pushgateway

For short-lived jobs that need to push metrics:

Add Pushgateway to Docker Compose:

yaml

services:
  pushgateway:
    image: prom/pushgateway
    ports:
      - 9091:9091

Push metrics example:

bash

echo "some_metric 3.14" | curl --data-binary @- http://pushgateway:9091/metrics/job/some_job

Configure Prometheus to scrape Pushgateway:

yaml

scrape_configs:
  - job_name: 'pushgateway'
    static_configs:
      - targets: ['pushgateway:9091']

Troubleshooting Common Issues

Prometheus can't access Docker socket:
- Ensure the Docker socket is correctly mounted
- Check permissions on the Docker socket
bash
```
sudo chmod 666 /var/run/docker.sock
```
Containers not showing up in Prometheus:
- Verify that containers have the correct Prometheus labels
- Check if the container exposes metrics on the specified port
Incorrect metrics:
- Ensure your application is exposing metrics in Prometheus format
- Check if you need to use an exporter for your specific application
High CPU usage:
- Adjust scrape interval in Prometheus configuration
- Optimize your queries and alert rules
Storage issues:
- Configure appropriate storage retention settings
- Consider using remote storage solutions for long-term storage

Quick Reference Commands

Essential commands for managing Prometheus:

bash

# Pull Prometheus image
docker pull prom/prometheus

# Check Prometheus logs
docker logs prometheus

# Restart Prometheus
docker restart prometheus

# Check Prometheus configuration
docker exec prometheus promtool check config /etc/prometheus/prometheus.yml

# Check Alertmanager status
docker logs alertmanager

# Verify Pushgateway metrics
curl localhost:9091/metrics

Alternative Monitoring Solutions

While setting up Prometheus with Docker provides robust monitoring, you might also consider complementary solutions for enhanced observability. For example, Uptrace integrates well with Prometheus and adds distributed tracing capabilities:

Use Prometheus as your primary metrics collector
Add Uptrace for:
- Distributed tracing across services
- Combined metrics and logs view
- Extended query capabilities with ClickHouse
- Native OpenTelemetry support

This combination can provide more comprehensive monitoring, especially in microservices architectures.

Conclusion

Setting up Prometheus for Docker provides a powerful monitoring solution for containerized environments. By following this guide, you've learned how to integrate these technologies and implement best practices. Start with basic monitoring and gradually expand your setup with additional components like Alertmanager and Pushgateway as needed.

FAQ

What is Prometheus, and why use it for Docker monitoring? Prometheus is an open-source monitoring tool that collects and analyzes metrics. It’s ideal for Docker monitoring due to its service discovery and efficient metric collection.
How do I run Prometheus as a Docker container? You can run Prometheus in a Docker container by pulling the official image and configuring it with a Prometheus configuration file.
How do I check if Prometheus is running? You can verify Prometheus is running by accessing its web UI through a browser.
How do I configure Prometheus to monitor Docker containers? Prometheus needs a configuration file that defines scrape targets, including Docker container metrics endpoints.
How do I use Docker Compose for Prometheus? Docker Compose allows you to define Prometheus as a service with persistent storage and network settings.
How do I verify Prometheus is scraping my containers? You can check the Prometheus web UI under the "Targets" section to see if your containers are being monitored.
How can I monitor Docker itself with Prometheus? To monitor Docker, you can use exporters like cAdvisor or node-exporter, which expose container and system metrics.
What metrics does Prometheus collect from Docker containers? Prometheus collects CPU usage, memory consumption, network traffic, disk I/O, and other container-specific metrics.
How do I visualize Prometheus metrics? You can use Grafana to create dashboards and visualize Prometheus-collected metrics.
Can Prometheus send alerts for Docker container issues? Yes, Prometheus supports alerting through Alertmanager, allowing notifications based on predefined rules.

You may also be interested in: