Monitor Cherokee web server performance with custom Grafana dashboards and Prometheus alerts

Update system packages

Start by updating your package manager to ensure you get the latest versions of all components.

sudo apt update && sudo apt upgrade -y

sudo dnf update -y

Install Cherokee web server with status module

Install Cherokee with the admin interface and status monitoring module enabled for metrics collection.

sudo apt install -y cherokee cherokee-admin libcherokee-mod-admin libcherokee-mod-server-info

sudo dnf install -y cherokee cherokee-admin

Configure Cherokee status endpoint

Enable the server-info module to expose performance metrics that Prometheus can scrape.

sudo cherokee-admin -b &
CHEROKEE_ADMIN_PID=$!

Access the Cherokee admin interface and configure the status endpoint:

# Navigate to http://localhost:9090
Go to vServers -> default -> Behavior
Add new rule: Directory /server-status
Set Handler to: Server Info
Apply and restart Cherokee

Install Prometheus

Download and install Prometheus for metrics collection and storage.

wget https://github.com/prometheus/prometheus/releases/download/v2.47.0/prometheus-2.47.0.linux-amd64.tar.gz
tar xzf prometheus-2.47.0.linux-amd64.tar.gz
sudo mv prometheus-2.47.0.linux-amd64 /opt/prometheus
sudo useradd --no-create-home --shell /bin/false prometheus
sudo chown -R prometheus:prometheus /opt/prometheus

Create Prometheus configuration

Configure Prometheus to scrape Cherokee metrics from the status endpoint.

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - "cherokee_alerts.yml"

alerting:
  alertmanagers:
    - static_configs:
        - targets:
          - localhost:9093

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

  - job_name: 'cherokee'
    static_configs:
      - targets: ['localhost:80']
    metrics_path: '/server-status'
    params:
      format: ['prometheus']
    scrape_interval: 10s

  - job_name: 'node_exporter'
    static_configs:
      - targets: ['localhost:9100']

Install Node Exporter for system metrics

Add Node Exporter to collect system-level metrics alongside Cherokee metrics.

wget https://github.com/prometheus/node_exporter/releases/download/v1.6.1/node_exporter-1.6.1.linux-amd64.tar.gz
tar xzf node_exporter-1.6.1.linux-amd64.tar.gz
sudo mv node_exporter-1.6.1.linux-amd64/node_exporter /usr/local/bin/
sudo useradd --no-create-home --shell /bin/false node_exporter

Create Cherokee metrics exporter script

Create a custom exporter to parse Cherokee status output into Prometheus format.

#!/usr/bin/env python3
import requests
import re
import time
from prometheus_client import start_http_server, Gauge, Counter

Define Cherokee metrics
cherokee_connections = Gauge('cherokee_connections_total', 'Total connections')
cherokee_requests = Counter('cherokee_requests_total', 'Total requests served')
cherokee_bytes_sent = Counter('cherokee_bytes_sent_total', 'Total bytes sent')
cherokee_uptime = Gauge('cherokee_uptime_seconds', 'Server uptime in seconds')
cherokee_cpu_usage = Gauge('cherokee_cpu_usage_percent', 'CPU usage percentage')
cherokee_memory_usage = Gauge('cherokee_memory_usage_bytes', 'Memory usage in bytes')

def collect_cherokee_metrics():
    try:
        response = requests.get('http://localhost/server-status?format=text', timeout=5)
        if response.status_code == 200:
            content = response.text
            
            # Parse metrics from Cherokee status output
            connections_match = re.search(r'Total connections:\s*(\d+)', content)
            if connections_match:
                cherokee_connections.set(int(connections_match.group(1)))
            
            requests_match = re.search(r'Total requests:\s*(\d+)', content)
            if requests_match:
                cherokee_requests._value._value = int(requests_match.group(1))
            
            bytes_match = re.search(r'Total bytes sent:\s*(\d+)', content)
            if bytes_match:
                cherokee_bytes_sent._value._value = int(bytes_match.group(1))
            
            uptime_match = re.search(r'Uptime:\s*(\d+)', content)
            if uptime_match:
                cherokee_uptime.set(int(uptime_match.group(1)))
                
    except Exception as e:
        print(f"Error collecting Cherokee metrics: {e}")

if __name__ == '__main__':
    start_http_server(9101)
    while True:
        collect_cherokee_metrics()
        time.sleep(10)

sudo chmod +x /opt/cherokee_exporter.py
sudo chown prometheus:prometheus /opt/cherokee_exporter.py

Create systemd services

Set up systemd services for Prometheus, Node Exporter, and Cherokee exporter.

[Unit]
Description=Prometheus
Wants=network-online.target
After=network-online.target

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/opt/prometheus/prometheus \
    --config.file=/etc/prometheus/prometheus.yml \
    --storage.tsdb.path=/var/lib/prometheus/ \
    --web.console.templates=/opt/prometheus/consoles \
    --web.console.libraries=/opt/prometheus/console_libraries \
    --web.listen-address=0.0.0.0:9090 \
    --web.enable-lifecycle

[Install]
WantedBy=multi-user.target

[Unit]
Description=Node Exporter
Wants=network-online.target
After=network-online.target

[Service]
User=node_exporter
Group=node_exporter
Type=simple
ExecStart=/usr/local/bin/node_exporter

[Install]
WantedBy=multi-user.target

[Unit]
Description=Cherokee Exporter
Wants=network-online.target
After=network-online.target cherokee.service

[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/bin/python3 /opt/cherokee_exporter.py
Restart=always

[Install]
WantedBy=multi-user.target

Create Prometheus data directories

Set up the required directories with correct ownership for Prometheus data storage.

sudo mkdir -p /etc/prometheus /var/lib/prometheus
sudo chown prometheus:prometheus /etc/prometheus /var/lib/prometheus
sudo mv /opt/prometheus/prometheus.yml /etc/prometheus/

Install Grafana

Install Grafana for dashboard visualization of Cherokee and system metrics.

wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install -y grafana

sudo dnf install -y https://dl.grafana.com/oss/release/grafana-10.1.2-1.x86_64.rpm

Create Cherokee alerting rules

Define Prometheus alerting rules for Cherokee performance thresholds and error conditions.

groups:
  - name: cherokee_alerts
    rules:
      - alert: CherokeeDown
        expr: up{job="cherokee"} == 0
        for: 30s
        labels:
          severity: critical
        annotations:
          summary: "Cherokee web server is down"
          description: "Cherokee has been down for more than 30 seconds."

      - alert: CherokeeHighConnections
        expr: cherokee_connections_total > 1000
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Cherokee high connection count"
          description: "Cherokee has {{ $value }} active connections."

      - alert: CherokeeHighCPUUsage
        expr: cherokee_cpu_usage_percent > 80
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Cherokee high CPU usage"
          description: "Cherokee CPU usage is {{ $value }}% for more than 5 minutes."

      - alert: CherokeeHighMemoryUsage
        expr: cherokee_memory_usage_bytes > 1073741824
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Cherokee high memory usage"
          description: "Cherokee memory usage is {{ $value | humanizeBytes }}."

      - alert: CherokeeHighResponseTime
        expr: increase(cherokee_requests_total[5m]) / increase(cherokee_uptime_seconds[5m]) < 10
        for: 3m
        labels:
          severity: warning
        annotations:
          summary: "Cherokee low request rate"
          description: "Cherokee request rate has dropped below 10 req/sec for 3 minutes."

Install and configure Alertmanager

Set up Alertmanager to handle alert notifications from Prometheus rules.

wget https://github.com/prometheus/alertmanager/releases/download/v0.26.0/alertmanager-0.26.0.linux-amd64.tar.gz
tar xzf alertmanager-0.26.0.linux-amd64.tar.gz
sudo mv alertmanager-0.26.0.linux-amd64 /opt/alertmanager
sudo useradd --no-create-home --shell /bin/false alertmanager
sudo chown -R alertmanager:alertmanager /opt/alertmanager

global:
  smtp_smarthost: 'localhost:587'
  smtp_from: 'alerts@example.com'

route:
  group_by: ['alertname']
  group_wait: 10s
  group_interval: 10s
  repeat_interval: 1h
  receiver: 'web.hook'

receivers:
  - name: 'web.hook'
    email_configs:
      - to: 'admin@example.com'
        subject: 'Cherokee Alert: {{ range .Alerts }}{{ .Annotations.summary }}{{ end }}'
        body: |
          {{ range .Alerts }}
          Alert: {{ .Annotations.summary }}
          Description: {{ .Annotations.description }}
          {{ end }}

[Unit]
Description=Alertmanager
Wants=network-online.target
After=network-online.target

[Service]
User=alertmanager
Group=alertmanager
Type=simple
ExecStart=/opt/alertmanager/alertmanager \
    --config.file=/etc/alertmanager/alertmanager.yml \
    --storage.path=/var/lib/alertmanager/

[Install]
WantedBy=multi-user.target

Start and enable all services

Enable and start Cherokee, Prometheus, Node Exporter, Cherokee exporter, Grafana, and Alertmanager.

sudo mkdir -p /var/lib/alertmanager /etc/alertmanager
sudo chown alertmanager:alertmanager /var/lib/alertmanager /etc/alertmanager

sudo systemctl daemon-reload
sudo systemctl enable --now cherokee
sudo systemctl enable --now prometheus
sudo systemctl enable --now node_exporter
sudo systemctl enable --now cherokee_exporter
sudo systemctl enable --now grafana-server
sudo systemctl enable --now alertmanager

Configure Cherokee admin interface access

Set up Cherokee admin access and configure the server-status endpoint properly.

# Stop the background admin process
kill $CHEROKEE_ADMIN_PID

Configure Cherokee via command line
sudo cherokee-admin -b -C /etc/cherokee/cherokee.conf

Create Grafana Cherokee dashboard

Import a custom dashboard configuration for Cherokee monitoring in Grafana.

{
  "dashboard": {
    "id": null,
    "title": "Cherokee Web Server Monitoring",
    "tags": ["cherokee", "web-server"],
    "timezone": "browser",
    "panels": [
      {
        "id": 1,
        "title": "Cherokee Status",
        "type": "stat",
        "targets": [
          {
            "expr": "up{job=\"cherokee\"}",
            "legendFormat": "Cherokee Status"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 0, "y": 0}
      },
      {
        "id": 2,
        "title": "Active Connections",
        "type": "graph",
        "targets": [
          {
            "expr": "cherokee_connections_total",
            "legendFormat": "Connections"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 12, "y": 0}
      },
      {
        "id": 3,
        "title": "Request Rate",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(cherokee_requests_total[5m])",
            "legendFormat": "Requests/sec"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 0, "y": 8}
      },
      {
        "id": 4,
        "title": "Bandwidth Usage",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(cherokee_bytes_sent_total[5m])",
            "legendFormat": "Bytes/sec"
          }
        ],
        "gridPos": {"h": 8, "w": 12, "x": 12, "y": 8}
      },
      {
        "id": 5,
        "title": "System Resources",
        "type": "graph",
        "targets": [
          {
            "expr": "cherokee_cpu_usage_percent",
            "legendFormat": "CPU %"
          },
          {
            "expr": "cherokee_memory_usage_bytes / 1024 / 1024",
            "legendFormat": "Memory MB"
          }
        ],
        "gridPos": {"h": 8, "w": 24, "x": 0, "y": 16}
      }
    ],
    "time": {
      "from": "now-1h",
      "to": "now"
    },
    "refresh": "5s"
  }
}

Add Prometheus data source to Grafana

Configure Grafana to use Prometheus as a data source for Cherokee metrics.

# Access Grafana at http://localhost:3000
Default login: admin/admin
Go to Configuration > Data Sources > Add data source
Select Prometheus
URL: http://localhost:9090
Click Save & Test

Import Cherokee dashboard

Import the custom Cherokee dashboard using the Grafana API or web interface.

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