/dora

name: dora
description: Measure, benchmark, instrument, and debug DORA metrics (Deployment Frequency, Lead Time for Changes, Change Failure Rate, MTTR) for production engineering teams. Covers GitHub Actions instrumentation, Prometheus recording rules, Grafana dashboards, incident source integration, SaaS tool selection, and anti-pattern detection. Use when asked to "instrument DORA metrics", "benchmark our deployment frequency", "why is my MTTR data missing", or "generate a DORA dashboard".
argument-hint: "[instrument|dashboard|benchmark|debug] [description or file path]"
title: "DORA Metrics Command"
sidebar_label: "dora"
custom_edit_url: null

Measure, benchmark, and instrument DORA metrics for production engineering teams.

Mode: instrument

Add DORA event emission to a GitHub Actions workflow.

Steps: 1. Identify which events to capture:

• **Deploy event**: triggered on successful deployment to a target environment
• **Incident open event**: triggered by PagerDuty/OpsGenie webhook when an incident is created
• **Incident close event**: triggered when the incident is resolved

2. Detect: does a Prometheus Pushgateway exist in the stack? If not, it must be deployed before instrumentation can work:

   kubectl get svc -A | grep pushgateway

If absent, deploy via Helm before proceeding:

   helm upgrade --install prometheus-pushgateway prometheus-community/prometheus-pushgateway \
     --namespace monitoring \
     --create-namespace

3. Generate GitHub Actions steps for each event type:

• **Deploy event**: push `dora_deployment_timestamp` and `dora_lead_time_seconds` to Pushgateway
• **Incident triggered** (PagerDuty/OpsGenie webhook): push `dora_incident_start_timestamp`
• **Incident resolved**: push `dora_incident_duration_seconds` and `dora_incident_caused_by_deploy`

4. Output: exact YAML to append to the existing workflow, using the Pushgateway job name convention `job/dora/instance/<repo-owner_repo-name>`. Sanitize `owner/repo` → `owner_repo` to avoid breaking Pushgateway path segments.

Example deploy event step:

   - name: Push DORA deploy metrics
     if: success()
     env:
       PUSHGATEWAY_URL: ${{ secrets.PUSHGATEWAY_URL }}
       REPO: ${{ github.repository }}
     run: |
       DEPLOY_TS=$(date +%s)
       # Lead time from first commit in this batch — requires fetch-depth: 0 in checkout.
       FIRST_COMMIT_TS=$(git log --reverse --format="%ct" origin/main..HEAD | head -1)
       FIRST_COMMIT_TS=${FIRST_COMMIT_TS:-$DEPLOY_TS}
       LEAD_TIME=$((DEPLOY_TS - FIRST_COMMIT_TS))
       INSTANCE="${REPO//\//_}"
       cat <<EOF | curl --data-binary @- "${PUSHGATEWAY_URL}/metrics/job/dora/instance/${INSTANCE}"
       # TYPE dora_deployment_timestamp gauge
       dora_deployment_timestamp{repo="${REPO}",env="production"} ${DEPLOY_TS}
       # TYPE dora_lead_time_seconds gauge
       dora_lead_time_seconds{repo="${REPO}",env="production"} ${LEAD_TIME}
       EOF

5. Warn: Change Failure Rate requires incident source integration — a rate of 0% without incident data is a configuration gap, not a real metric. Never report 0% CFR without confirmed incident source connectivity.

**Validation:**

# Confirm Pushgateway received the metric
curl -s http://pushgateway:9091/metrics | grep dora_deployment_timestamp

# Confirm Prometheus scraped it (allow up to 1 scrape interval, default 15s)
curl -s 'http://prometheus:9090/api/v1/query?query=dora_deployment_timestamp' \
  | jq '.data.result[0].value[1] // "not yet scraped — wait 15s and retry"'

Reference: `references/dora.md` → Open-source instrumentation pattern

Mode: dashboard

Generate a Grafana dashboard for all four DORA metrics.

Steps: 1. Confirm the four recording rules are deployed before building the dashboard:

• `dora:deployment_frequency:rate30d`
• `dora:lead_time_seconds:p50`
• `dora:change_failure_rate:ratio30d`
• `dora:mttr_seconds:p50`

Verify with:

   curl -s 'http://prometheus:9090/api/v1/query?query=dora:deployment_frequency:rate30d' | jq '.data.result[0].value[1] // "no data"'

If any query returns no data, check the recording rule deployment — see `references/dora.md` for the full rule set.

2. Dashboard structure: four panels arranged in a 2×2 grid, one per DORA metric:

• **Panel 1 — Deployment Frequency**: stat + time-series, unit: deploys/day
• **Panel 2 — Lead Time for Changes**: stat + time-series, unit: hours (p50)
• **Panel 3 — Change Failure Rate**: stat + time-series, unit: percentage
• **Panel 4 — MTTR**: stat + time-series, unit: hours (p50)

Each panel includes DORA performance band overlays as threshold regions (Elite/High/Medium/Low). A time range selector provides 30/60/90 day views.

3. Import the complete dashboard JSON from `examples/dora/grafana-dashboard.json`:

   # Import via Grafana API
   curl -s -X POST http://grafana:3000/api/dashboards/import \
     -H "Content-Type: application/json" \
     -d @examples/dora/grafana-dashboard.json

4. Threshold values for each performance tier are embedded directly in the panel JSON as threshold bands. Update them in the panel `thresholds` field if your organisation uses different band definitions.

Reference: `references/dora.md` → DORA performance bands

Mode: benchmark

Classify current metric values against DORA performance bands.

Steps: 1. Accept current metric values — either provided directly or queried from Prometheus:

   # Query current values
   curl -s 'http://prometheus:9090/api/v1/query?query=dora:deployment_frequency:rate30d' | jq '.data.result[0].value[1] // "no data"'
   curl -s 'http://prometheus:9090/api/v1/query?query=dora:lead_time_seconds:p50' | jq '.data.result[0].value[1] // "no data"'
   curl -s 'http://prometheus:9090/api/v1/query?query=dora:change_failure_rate:ratio30d' | jq '.data.result[0].value[1] // "no data"'
   curl -s 'http://prometheus:9090/api