🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Prometheus
πŸ¦€ ClawHub

Prometheus

by @akellacom

Query Prometheus monitoring data to check server metrics, resource usage, and system health. Use when the user asks about server status, disk space, CPU/memo...

Versionv1.1.0
Installs18
#clawhub
TERMINAL
clawhub install prometheus

πŸ“– About This Skill

name: prometheus description: Query Prometheus monitoring data to check server metrics, resource usage, and system health. Use when the user asks about server status, disk space, CPU/memory usage, network stats, or any metrics collected by Prometheus. Supports multiple Prometheus instances with aggregated queries, config file or environment variables, and HTTP Basic Auth.

Prometheus Skill

Query Prometheus monitoring data from one or multiple instances. Supports federation across multiple Prometheus servers with a single command.

Quick Start

1. Initial Setup

Run the interactive configuration wizard:

cd ~/.openclaw/workspace/skills/prometheus
node scripts/cli.js init

This will create a prometheus.json config file in your OpenClaw workspace (~/.openclaw/workspace/prometheus.json).

2. Start Querying

# Query default instance
node scripts/cli.js query 'up'
Query all instances at once

node scripts/cli.js query 'up' --all
List configured instances

node scripts/cli.js instances

Configuration

Config File Location

By default, the skill looks for config in your OpenClaw workspace:

~/.openclaw/workspace/prometheus.json

Priority order: 1. Path from PROMETHEUS_CONFIG environment variable 2. ~/.openclaw/workspace/prometheus.json 3. ~/.openclaw/workspace/config/prometheus.json 4. ./prometheus.json (current directory) 5. ~/.config/prometheus/config.json

Config Format

Create prometheus.json in your workspace (or use node cli.js init):

{
  "instances": [
    {
      "name": "production",
      "url": "https://prometheus.example.com",
      "user": "admin",
      "password": "secret"
    },
    {
      "name": "staging",
      "url": "http://prometheus-staging:9090"
    }
  ],
  "default": "production"
}

Fields:

  • name β€” unique identifier for the instance
  • url β€” Prometheus server URL
  • user / password β€” optional HTTP Basic Auth credentials
  • default β€” which instance to use when none specified

    • Environment Variables (Legacy)

    For single-instance setups, you can use environment variables:

    export PROMETHEUS_URL=https://prometheus.example.com
export PROMETHEUS_USER=admin        # optional
export PROMETHEUS_PASSWORD=secret   # optional

    Usage

    Global Flags

    | Flag | Description | |------|-------------| | -c, --config | Path to config file | | -i, --instance | Target specific instance | | -a, --all | Query all configured instances |

    Commands

    #### Setup

    # Interactive configuration wizard
node scripts/cli.js init

    #### Query Metrics

    cd ~/.openclaw/workspace/skills/prometheus
    Query default instance
    
node scripts/cli.js query 'up'
    Query specific instance
    
node scripts/cli.js query 'up' -i staging
    Query ALL instances at once
    
node scripts/cli.js query 'up' --all
    Custom config file
    
node scripts/cli.js query 'up' -c /path/to/config.json

    #### Common Queries

    Disk space usage: 

    node scripts/cli.js query '100 - (node_filesystem_avail_bytes / node_filesystem_size_bytes * 100)' --all

    CPU usage: 

    node scripts/cli.js query '100 - (avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)' --all

    Memory usage: 

    node scripts/cli.js query '(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100' --all

    Load average: 

    node scripts/cli.js query 'node_load1' --all

    List Configured Instances

    node scripts/cli.js instances

    Output: 

    {
  "default": "production",
  "instances": [
    { "name": "production", "url": "https://prometheus.example.com", "hasAuth": true },
    { "name": "staging", "url": "http://prometheus-staging:9090", "hasAuth": false }
  ]
}

    Other Commands

    # List all metrics matching pattern
node scripts/cli.js metrics 'node_memory_*'
    Get label names
    
node scripts/cli.js labels --all
    Get values for a label
    
node scripts/cli.js label-values instance --all
    Find time series
    
node scripts/cli.js series '{__name__=~"node_cpu_.*", instance=~".*:9100"}' --all
    Get active alerts
    
node scripts/cli.js alerts --all
    Get scrape targets
    
node scripts/cli.js targets --all

    Multi-Instance Output Format

    When using --all, results include data from all instances:

    {
  "resultType": "vector",
  "results": [
    {
      "instance": "production",
      "status": "success",
      "resultType": "vector",
      "result": [...]
    },
    {
      "instance": "staging",
      "status": "success",
      "resultType": "vector",
      "result": [...]
    }
  ]
}

    Errors on individual instances don't fail the entire query β€” they appear with "status": "error" in the results array.

    Common Queries Reference

    | Metric | PromQL Query | |--------|--------------| | Disk free % | node_filesystem_avail_bytes / node_filesystem_size_bytes * 100 | | Disk used % | 100 - (node_filesystem_avail_bytes / node_filesystem_size_bytes * 100) | | CPU idle % | avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100 | | Memory used % | (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100 | | Network RX | rate(node_network_receive_bytes_total[5m]) | | Network TX | rate(node_network_transmit_bytes_total[5m]) | | Uptime | node_time_seconds - node_boot_time_seconds | | Service up | up |

    Notes

  • Time range defaults to last 1 hour for instant queries
  • Use range queries [5m] for rate calculations
  • All queries return JSON with data.result containing the results
  • Instance labels typically show host:port format
  • When using --all, queries run in parallel for faster results
  • Config is stored outside the skill directory so it persists across skill updates

    • πŸ’‘ Examples

    Global Flags

    | Flag | Description | |------|-------------| | -c, --config | Path to config file | | -i, --instance | Target specific instance | | -a, --all | Query all configured instances |

    Commands

    #### Setup

    # Interactive configuration wizard
node scripts/cli.js init

    #### Query Metrics

    cd ~/.openclaw/workspace/skills/prometheus
    Query default instance
    
node scripts/cli.js query 'up'
    Query specific instance
    
node scripts/cli.js query 'up' -i staging
    Query ALL instances at once
    
node scripts/cli.js query 'up' --all
    Custom config file
    
node scripts/cli.js query 'up' -c /path/to/config.json

    #### Common Queries

    Disk space usage: 

    node scripts/cli.js query '100 - (node_filesystem_avail_bytes / node_filesystem_size_bytes * 100)' --all

    CPU usage: 

    node scripts/cli.js query '100 - (avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)' --all

    Memory usage: 

    node scripts/cli.js query '(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100' --all

    Load average: 

    node scripts/cli.js query 'node_load1' --all

    List Configured Instances

    node scripts/cli.js instances

    Output: 

    {
  "default": "production",
  "instances": [
    { "name": "production", "url": "https://prometheus.example.com", "hasAuth": true },
    { "name": "staging", "url": "http://prometheus-staging:9090", "hasAuth": false }
  ]
}

    Other Commands

    # List all metrics matching pattern
node scripts/cli.js metrics 'node_memory_*'
    Get label names
    
node scripts/cli.js labels --all
    Get values for a label
    
node scripts/cli.js label-values instance --all
    Find time series
    
node scripts/cli.js series '{__name__=~"node_cpu_.*", instance=~".*:9100"}' --all
    Get active alerts
    
node scripts/cli.js alerts --all
    Get scrape targets
    
node scripts/cli.js targets --all

    βš™οΈ Configuration

    Config File Location

    By default, the skill looks for config in your OpenClaw workspace:

    ~/.openclaw/workspace/prometheus.json

    Priority order: 1. Path from PROMETHEUS_CONFIG environment variable 2. ~/.openclaw/workspace/prometheus.json 3. ~/.openclaw/workspace/config/prometheus.json 4. ./prometheus.json (current directory) 5. ~/.config/prometheus/config.json

    Config Format

    Create prometheus.json in your workspace (or use node cli.js init):

    {
  "instances": [
    {
      "name": "production",
      "url": "https://prometheus.example.com",
      "user": "admin",
      "password": "secret"
    },
    {
      "name": "staging",
      "url": "http://prometheus-staging:9090"
    }
  ],
  "default": "production"
}

    Fields:

  • name β€” unique identifier for the instance
  • url β€” Prometheus server URL
  • user / password β€” optional HTTP Basic Auth credentials
  • default β€” which instance to use when none specified

    • Environment Variables (Legacy)

    For single-instance setups, you can use environment variables:

    export PROMETHEUS_URL=https://prometheus.example.com
export PROMETHEUS_USER=admin        # optional
export PROMETHEUS_PASSWORD=secret   # optional

    πŸ“‹ Tips & Best Practices

  • Time range defaults to last 1 hour for instant queries
  • Use range queries [5m] for rate calculations
  • All queries return JSON with data.result containing the results
  • Instance labels typically show host:port format
  • When using --all, queries run in parallel for faster results
  • Config is stored outside the skill directory so it persists across skill updates