Prometheus & Grafana

Export heartbeat metrics in Prometheus format for Grafana dashboards and Alertmanager rules.

Overview

Cronping exposes a Prometheus-compatible metrics endpoint that lets you integrate heartbeat data into your existing monitoring stack. If you already use Grafana, Prometheus, or Alertmanager, you can add Cronping as a scrape target and start building dashboards and alerts in minutes.

Unlike push-based integrations (Slack, PagerDuty, etc.), the Prometheus integration works by scraping — Prometheus periodically fetches metrics from Cronping's API.

Endpoint

GET /api/v1/metrics

Returns metrics in Prometheus Text Exposition v0.0.4 format.

Content-Type: text/plain; version=0.0.4; charset=utf-8

Authentication

This endpoint uses the same API keys as the Management API. Both header formats are supported:

X-Api-Key: cpk_abc123...

Authorization: Bearer cpk_abc123...

Use the Authorization: Bearer format for native Prometheus bearer_token configuration.

A Read Only API key is sufficient — the metrics endpoint only reads data.

Query parameters

Parameter	Type	Description
`tags`	string	Comma-separated tags to filter heartbeats
`ids`	string	Comma-separated heartbeat IDs to filter by

Examples:

GET /api/v1/metrics?tags=production
GET /api/v1/metrics?ids=550e8400-...,660e8400-...
GET /api/v1/metrics?tags=production,database

Exposed metrics

Metric	Type	Labels	Description
`cronping_heartbeat_status`	gauge	`id`, `name`, `tags`	Current status as a number (1=up, 0=down, 2=warn, 3=late, 4=paused, 5=new)
`cronping_heartbeat_up`	gauge	`id`, `name`, `tags`	1 if heartbeat is up or warn, 0 otherwise
`cronping_heartbeat_last_ping_timestamp_seconds`	gauge	`id`, `name`	Unix timestamp of the last ping received
`cronping_heartbeat_last_duration_seconds`	gauge	`id`, `name`	Duration of the last completed run in seconds
`cronping_heartbeat_pings_total`	counter	`id`, `name`, `type`	Total pings received, grouped by type (success, fail, warn, start, log)

Status value mapping

Status	Value
`up`	1
`down`	0
`warn`	2
`late`	3
`paused`	4
`new`	5

Example response

# HELP cronping_heartbeat_status Current status of a heartbeat (1=up, 0=down, 2=warn, 3=late, 4=paused, 5=new)
# TYPE cronping_heartbeat_status gauge
cronping_heartbeat_status{id="abc123",name="db-backup",tags="prod db"} 1

# HELP cronping_heartbeat_up 1 if heartbeat is up or warn, 0 if down or late
# TYPE cronping_heartbeat_up gauge
cronping_heartbeat_up{id="abc123",name="db-backup",tags="prod db"} 1

# HELP cronping_heartbeat_last_ping_timestamp_seconds Unix timestamp of the last ping received
# TYPE cronping_heartbeat_last_ping_timestamp_seconds gauge
cronping_heartbeat_last_ping_timestamp_seconds{id="abc123",name="db-backup"} 1743200400

# HELP cronping_heartbeat_last_duration_seconds Duration of the last completed run in seconds
# TYPE cronping_heartbeat_last_duration_seconds gauge
cronping_heartbeat_last_duration_seconds{id="abc123",name="db-backup"} 124.500

# HELP cronping_heartbeat_pings_total Total number of pings received by type
# TYPE cronping_heartbeat_pings_total counter
cronping_heartbeat_pings_total{id="abc123",name="db-backup",type="success"} 342
cronping_heartbeat_pings_total{id="abc123",name="db-backup",type="fail"} 3

Prometheus configuration

Add Cronping as a scrape target in your prometheus.yml:

scrape_configs:
  - job_name: cronping
    scheme: https
    static_configs:
      - targets: ["cronping.com"]
    metrics_path: /api/v1/metrics
    bearer_token: "cpk_your-api-key-here"
    scrape_interval: 60s

To filter by tags:

scrape_configs:
  - job_name: cronping-production
    scheme: https
    static_configs:
      - targets: ["cronping.com"]
    metrics_path: /api/v1/metrics
    params:
      tags: ["production"]
    bearer_token: "cpk_your-api-key-here"
    scrape_interval: 60s

Alertmanager rules

Basic down alert

groups:
  - name: cron_jobs
    rules:
      - alert: CronJobDown
        expr: cronping_heartbeat_up == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Cron job {{ $labels.name }} is down"
          description: "Heartbeat {{ $labels.id }} missed its expected ping."

Slow execution alert

- alert: CronJobSlow
  expr: cronping_heartbeat_last_duration_seconds > 300
  for: 10m
  labels:
    severity: warning
  annotations:
    summary: "Cron job {{ $labels.name }} is running slow"
    description: "Last run took {{ $value }}s (threshold: 300s)."

Grafana dashboard tips

Heartbeat overview table:

cronping_heartbeat_status

Uptime percentage (last 24h):

avg_over_time(cronping_heartbeat_up[24h]) * 100

Pings per hour:

rate(cronping_heartbeat_pings_total[1h])

Failed pings trend:

rate(cronping_heartbeat_pings_total{type="fail"}[1h])

Prometheus & Grafana

On this page