Prometheus for Docker: Installation & Monitoring

Prometheus monitors your Docker containers by collecting metrics like CPU usage, memory consumption, and network traffic. This guide shows you how to install and run Prometheus using Docker, configure it to monitor your containers, and collect useful metrics.

Quick Start: Run Prometheus in Docker

The fastest way to get Prometheus running is with a single Docker command:

# Pull the official Prometheus image
docker pull prom/prometheus

# Run Prometheus (basic setup)
docker run -d \
  --name prometheus \
  -p 9090:9090 \
  prom/prometheus

Open http://localhost:9090 in your browser - you should see the Prometheus web interface.

What this does: Downloads the official prom/prometheus image and runs Prometheus on port 9090. This basic setup works for testing, but you'll need a configuration file for real monitoring.

System Requirements

Prometheus is lightweight, but you'll need:

• CPU: 2 cores minimum (4+ for production with many containers)
• RAM: 4GB minimum (8GB+ recommended for production)
• Disk: Depends on retention period - plan ~1-2GB per day of metrics for 10-20 containers
• Docker: Version 20.10+ installed and running

Why these requirements? Prometheus stores metrics in memory before writing to disk, so more RAM = better query performance. CPU usage scales with number of containers monitored and query complexity. Disk space fills up based on how long you keep metrics (default: 15 days).

Using Docker Compose (Recommended)

Docker Compose makes it easier to manage Prometheus with configuration files. Create a docker-compose.yml:

version: '3'
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.retention.time=15d'

volumes:
  prometheus-data:

Create a simple prometheus.yml configuration:

global:
  scrape_interval: 15s  # How often to collect metrics

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']  # Monitor Prometheus itself

Start Prometheus:

docker-compose up -d

Why Docker Compose? It saves your configuration in files, automatically recreates containers with the same settings, and makes it easy to add Grafana or Alertmanager later. For detailed Grafana setup with Prometheus, see the OpenTelemetry Collector Prometheus guide.

prom/prometheus Image

The official Prometheus Docker image is prom/prometheus on Docker Hub. Here's what you need to know:

Image tags:

• prom/prometheus:latest - newest version (updates frequently)
• prom/prometheus:v2.50.0 - specific version (recommended for production)

Default configuration:

• Prometheus UI runs on port 9090
• Configuration file: /etc/prometheus/prometheus.yml
• Data storage: /prometheus directory
• User: nobody (runs without root for security)

Finding the right version:

# Check latest version
docker pull prom/prometheus:latest
docker run --rm prom/prometheus --version

# Use specific version for stability
docker pull prom/prometheus:v2.50.0

Why version matters: Using latest is fine for testing, but production should pin a specific version (like v2.50.0) so updates don't break your setup.

Monitoring Docker Containers with Prometheus

To monitor your Docker containers, you need a "metrics exporter" - a service that exposes container metrics in a format Prometheus understands. The easiest way is using cAdvisor (Container Advisor).

What is cAdvisor? It's a tool from Google that collects metrics about running containers (CPU, memory, network, disk usage) and exposes them for Prometheus to scrape.

Add cAdvisor to your docker-compose.yml:

version: '3'
services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'

  cadvisor:
    image: gcr.io/cadvisor/cadvisor:latest
    container_name: cadvisor
    ports:
      - "8080:8080"
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
    privileged: true

volumes:
  prometheus-data:

Update your prometheus.yml to scrape cAdvisor:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'docker-containers'
    static_configs:
      - targets: ['cadvisor:8080']  # cAdvisor exposes container metrics here

Restart your services:

docker-compose down
docker-compose up -d

Verify it's working:

1. Open http://localhost:9090/targets - you should see both "prometheus" and "docker-containers" targets as UP
2. Open http://localhost:8080 - cAdvisor web interface showing all running containers

Why this approach? Directly connecting Prometheus to Docker socket (/var/run/docker.sock) works but requires complex relabeling configs. Using cAdvisor is simpler and provides better formatted metrics.

Docker Container Metrics

Once Prometheus is scraping cAdvisor, you can query these metrics in the Prometheus UI (http://localhost:9090):

CPU metrics:

• container_cpu_usage_seconds_total - total CPU time used by container
• container_cpu_system_seconds_total - CPU time in system mode
• container_cpu_user_seconds_total - CPU time in user mode

Memory metrics:

• container_memory_usage_bytes - current memory usage
• container_memory_max_usage_bytes - maximum memory ever used
• container_memory_working_set_bytes - current working set size

Network metrics:

• container_network_receive_bytes_total - bytes received
• container_network_transmit_bytes_total - bytes sent
• container_network_receive_errors_total - receive errors

Disk metrics:

• container_fs_usage_bytes - disk space used
• container_fs_limit_bytes - disk space limit
• container_fs_reads_bytes_total - bytes read from disk
• container_fs_writes_bytes_total - bytes written to disk

Example query: To see CPU usage for a specific container:

rate(container_cpu_usage_seconds_total{name="my-container"}[5m])

Why these metrics matter: They help you identify containers using too much CPU/memory, detect network issues, and plan capacity. You can use them to create alerts (like "alert me when container uses >80% memory").

For comprehensive Docker monitoring with distributed tracing in addition to metrics, see OpenTelemetry Docker Monitoring.

Configuring Prometheus Health Checks

Health checks ensure Prometheus is running correctly. Add a healthcheck to your docker-compose.yml:

version: '3'
services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:9090/-/healthy"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--web.enable-lifecycle'

volumes:
  prometheus-data:

Check health status:

# Check if Prometheus is healthy
docker inspect prometheus --format='{{.State.Health.Status}}'

# View healthcheck logs
docker inspect prometheus --format='{{json .State.Health}}' | jq

What the healthcheck does: Prometheus exposes /-/healthy endpoint that returns 200 when running properly. Docker checks this every 30 seconds. If 3 checks fail, Docker marks the container as unhealthy, which can trigger automatic restarts or alerts.

Why use healthchecks? They help Docker orchestration tools (like Swarm or Kubernetes) know when to restart containers. Without healthchecks, a crashed Prometheus might stay "running" but not actually collecting metrics.

Additional Components

Setting Up Alertmanager

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

1. Create alertmanager.yml:

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'

2. Add Alertmanager to your Docker Compose file:

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

3. Update Prometheus configuration to use Alertmanager:

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

Using Pushgateway

For short-lived jobs that need to push metrics:

1. Add Pushgateway to Docker Compose:

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

2. Push metrics example:

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

3. Configure Prometheus to scrape Pushgateway:

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

Troubleshooting Common Issues

1. 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
   

2. Containers not showing up in Prometheus:
   • Verify that containers have the correct Prometheus labels
   • Check if the container exposes metrics on the specified port
   • Use docker logs prometheus to check for scraping errors. For detailed Docker log analysis, see Docker Logs Tail.
3. Incorrect metrics:
   • Ensure your application is exposing metrics in Prometheus format
   • Check if you need to use an exporter for your specific application
4. High CPU usage:
   • Adjust scrape interval in Prometheus configuration
   • Optimize your queries and alert rules
5. Storage issues:
   • Configure appropriate storage retention settings
   • Consider using remote storage solutions for long-term storage

Quick Reference Commands

Essential commands for managing Prometheus:

# 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. You can also ingest Prometheus metrics into Uptrace for unified observability:

1. Use Prometheus as your primary metrics collector
2. 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 the prom/prometheus Docker image? The prom/prometheus image is the official Prometheus Docker image hosted on Docker Hub. It contains Prometheus server pre-configured to run in containers. Use prom/prometheus:latest for testing or prom/prometheus:v2.50.0 for production with version pinning.

How do I install Prometheus using Docker? Pull the image with docker pull prom/prometheus, then run docker run -d -p 9090:9090 prom/prometheus. For production, use Docker Compose with a prometheus.yml configuration file mounted as a volume.

How do I run Prometheus in Docker with docker-compose? Create a docker-compose.yml with the prometheus service definition, mount your prometheus.yml config file, and run docker-compose up -d. This approach persists configuration and makes updates easier than manual docker run commands.

What is docker_sd_configs in Prometheus? docker_sd_configs is Prometheus service discovery for Docker. It automatically finds containers to monitor by reading Docker API. However, using cAdvisor is simpler for most users instead of complex docker_sd_configs and relabeling rules.

How do I monitor Docker containers with Prometheus? Use cAdvisor (Container Advisor) as a metrics exporter. Add it to your docker-compose.yml, configure Prometheus to scrape cAdvisor on port 8080, and it will collect CPU, memory, network, and disk metrics for all running containers.

What metrics does Prometheus collect from Docker? Through cAdvisor, Prometheus collects container_cpu_usage_seconds_total (CPU), container_memory_usage_bytes (memory), container_network_receive_bytes_total (network), and container_fs_usage_bytes (disk) metrics for each running container.

How do I configure Prometheus health checks in Docker? Add a healthcheck section to your docker-compose.yml that tests the /-/healthy endpoint. Docker will periodically check if Prometheus is responding and mark the container unhealthy if checks fail, enabling automatic restarts.

What is the prometheus.yml file? The prometheus.yml file configures what Prometheus monitors. It defines scrape targets (endpoints to collect metrics from), scrape intervals (how often to collect), and alerting rules. Mount it to /etc/prometheus/prometheus.yml in the container.

How do I check if Prometheus is running in Docker? Open http://localhost:9090 in your browser to access the Prometheus web UI. Alternatively, run docker ps to verify the container is running, or docker logs prometheus to check for errors in the logs.

How do I monitor Prometheus itself? Prometheus exposes its own metrics on localhost:9090/metrics. Add a scrape config with targets: ['localhost:9090'] to monitor Prometheus performance, including rule evaluation time, scrape duration, and storage metrics.

What is Pushgateway and when do I need it? Pushgateway (prom/pushgateway) is for short-lived jobs that can't be scraped directly (like cron jobs or batch scripts). Jobs push metrics to Pushgateway, then Prometheus scrapes Pushgateway. Regular long-running containers don't need it.

How do I add Alertmanager to Prometheus Docker setup? Add prom/alertmanager to your docker-compose.yml, create an alertmanager.yml config, and configure Prometheus to send alerts to alertmanager:9093. Alertmanager handles alert routing, grouping, and sending notifications via email/Slack/PagerDuty.

How do I persist Prometheus data in Docker? Use Docker volumes to persist the /prometheus directory. In docker-compose.yml, add volumes: - prometheus-data:/prometheus and define the named volume. Without this, stopping the container loses all collected metrics.

What is the latest Prometheus Docker image version? Check prom/prometheus:latest tag or visit Docker Hub for the newest version. As of 2025, version 2.50.x is current. For production, pin a specific version like prom/prometheus:v2.50.0 instead of using :latest to avoid unexpected updates.

How do I monitor Docker containers with Prometheus and Grafana? Set up Prometheus with cAdvisor for metrics collection (this guide), then add Grafana to docker-compose.yml. Configure Grafana to use Prometheus as a data source, and import dashboard templates for container monitoring visualization.