Integrate MinIO with Prometheus monitoring for performance metrics and observability

What this solves

MinIO object storage requires comprehensive monitoring to ensure optimal performance, track storage usage, and maintain service reliability in production environments. This tutorial shows you how to configure MinIO's built-in Prometheus metrics endpoint, set up automated metrics collection with Prometheus, create detailed Grafana dashboards for visualization, and implement alerting rules for proactive monitoring.

Prerequisites

Before starting this tutorial, you need a working MinIO installation with administrative access. You'll also need Prometheus and Grafana installed on your system. If you haven't set these up yet, refer to our MinIO clustering guide and Prometheus monitoring stack tutorial.

Step-by-step configuration

sudo systemctl stop minio
sudo mkdir -p /etc/minio

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your-secure-password-here
MINIO_VOLUMES=/data/minio
MINIO_OPTS="--console-address :9001"
MINIO_PROMETHEUS_AUTH_TYPE=public
MINIO_PROMETHEUS_URL=http://localhost:9000
MINIO_SERVER_URL=http://localhost:9000

[Unit]
Description=MinIO
Documentation=https://docs.min.io
Wants=network-online.target
After=network-online.target
AssertFileIsExecutable=/usr/local/bin/minio

[Service]
WorkingDirectory=/usr/local/
User=minio-user
Group=minio-user
EnvironmentFile=/etc/default/minio
ExecStartPre=/bin/bash -c "if [ -z \"${MINIO_VOLUMES}\" ]; then echo \"Variable MINIO_VOLUMES not set in /etc/default/minio\"; exit 1; fi"
ExecStart=/usr/local/bin/minio server $MINIO_OPTS $MINIO_VOLUMES
Restart=always
LimitNOFILE=65536
TasksMax=infinity
TimeoutStopSec=infinity
SendSIGKILL=no

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl start minio
sudo systemctl enable minio
sudo systemctl status minio

curl -s http://localhost:9000/minio/v2/metrics/cluster | head -20

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - "minio_alerts.yml"

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

  - job_name: 'minio-job'
    metrics_path: /minio/v2/metrics/cluster
    scheme: http
    static_configs:
      - targets: ['localhost:9000']
    scrape_interval: 15s
    scrape_timeout: 10s

groups:
  - name: minio-alerts
    rules:
      - alert: MinIONodeDown
        expr: up{job="minio-job"} == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "MinIO node is down"
          description: "MinIO node {{ $labels.instance }} has been down for more than 5 minutes."

      - alert: MinIOHighDiskUsage
        expr: (minio_cluster_capacity_usable_free_bytes / minio_cluster_capacity_usable_total_bytes) * 100 < 15
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "MinIO disk usage is high"
          description: "MinIO cluster has less than 15% free disk space remaining."

      - alert: MinIOHighAPIErrorRate
        expr: rate(minio_s3_requests_errors_total[5m]) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "MinIO API error rate is high"
          description: "MinIO API error rate is above 10% for the last 5 minutes."

      - alert: MinIOHighMemoryUsage
        expr: (minio_cluster_usage_total_bytes / minio_cluster_capacity_usable_total_bytes) * 100 > 85
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "MinIO memory usage is high"
          description: "MinIO cluster memory usage is above 85% for 15 minutes."

      - alert: MinIOSlowRequests
        expr: histogram_quantile(0.95, rate(minio_s3_requests_duration_seconds_bucket[5m])) > 1
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "MinIO requests are slow"
          description: "95th percentile of MinIO request duration is above 1 second."

sudo systemctl restart prometheus
sudo systemctl status prometheus

curl -X POST \
  http://admin:admin@localhost:3000/api/datasources \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Prometheus",
    "type": "prometheus",
    "url": "http://localhost:9090",
    "access": "proxy",
    "isDefault": true
  }'

{
  "dashboard": {
    "id": null,
    "title": "MinIO Cluster Monitoring",
    "tags": ["minio", "storage"],
    "timezone": "browser",
    "panels": [
      {
        "id": 1,
        "title": "MinIO Cluster Status",
        "type": "stat",
        "targets": [
          {
            "expr": "up{job=\"minio-job\"}",
            "legendFormat": "{{ instance }}"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 0, "y": 0}
      },
      {
        "id": 2,
        "title": "Storage Usage",
        "type": "graph",
        "targets": [
          {
            "expr": "minio_cluster_usage_total_bytes",
            "legendFormat": "Used Storage"
          },
          {
            "expr": "minio_cluster_capacity_usable_total_bytes",
            "legendFormat": "Total Capacity"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 12, "y": 0}
      },
      {
        "id": 3,
        "title": "API Request Rate",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(minio_s3_requests_total[5m])",
            "legendFormat": "{{ method }}"
          }
        ],
        "gridPos": {"h": 8, "w": 24, "x": 0, "y": 8}
      },
      {
        "id": 4,
        "title": "Error Rate",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(minio_s3_requests_errors_total[5m])",
            "legendFormat": "Errors per second"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 0, "y": 16}
      },
      {
        "id": 5,
        "title": "Response Time",
        "type": "graph",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(minio_s3_requests_duration_seconds_bucket[5m]))",
            "legendFormat": "95th percentile"
          },
          {
            "expr": "histogram_quantile(0.50, rate(minio_s3_requests_duration_seconds_bucket[5m]))",
            "legendFormat": "50th percentile"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 12, "y": 16}
      }
    ],
    "refresh": "30s",
    "time": {"from": "now-1h", "to": "now"}
  }
}

curl -X POST \
  http://admin:admin@localhost:3000/api/dashboards/db \
  -H 'Content-Type: application/json' \
  -d @/tmp/minio-dashboard.json

curl -X POST \
  http://admin:admin@localhost:3000/api/alert-notifications \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "minio-alerts",
    "type": "email",
    "settings": {
      "addresses": "admin@example.com"
    }
  }'

Verify your monitoring setup

Test that your MinIO monitoring integration is working correctly by checking metrics collection and dashboard functionality.

# Check MinIO metrics endpoint
curl -s http://localhost:9000/minio/v2/metrics/cluster | grep minio_cluster

Verify Prometheus is scraping MinIO
curl -s http://localhost:9090/api/v1/query?query=up{job="minio-job"}

Check Prometheus targets
curl -s http://localhost:9090/api/v1/targets | grep minio

Test Grafana dashboard access
curl -s http://admin:admin@localhost:3000/api/dashboards/db/minio-cluster-monitoring

Advanced monitoring configuration

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your-secure-password-here
MINIO_VOLUMES=/data/minio
MINIO_OPTS="--console-address :9001"
MINIO_PROMETHEUS_AUTH_TYPE=public
MINIO_AUDIT_WEBHOOK_ENDPOINT=http://localhost:8080/audit
MINIO_AUDIT_WEBHOOK_AUTH_TOKEN=audit-token-here

  - job_name: 'minio-node-metrics'
    metrics_path: /minio/v2/metrics/node
    scheme: http
    static_configs:
      - targets: ['localhost:9000']
    scrape_interval: 30s

  - job_name: 'minio-bucket-metrics'
    metrics_path: /minio/v2/metrics/bucket
    scheme: http
    static_configs:
      - targets: ['localhost:9000']
    scrape_interval: 60s

Security considerations

When deploying MinIO monitoring in production, consider implementing authentication for the metrics endpoint and encrypting communications between components. For comprehensive security hardening, refer to our MinIO security guide.

Common issues

Next steps

• Configure advanced Grafana dashboards and alerting with Prometheus integration
• Configure MinIO backup and disaster recovery with automated snapshots and replication
• Set up MinIO multi-tenant configuration with Prometheus monitoring
• Implement MinIO performance tuning with monitoring-based optimization
• Configure Prometheus long-term storage with Thanos for unlimited data retention