DORA Metrics

Quick Links

🚀 Quick Start Guide - Get started in 10 minutes
📚 API Reference - Complete API specification
💻 CI/CD Examples - Integration code samples
🔧 Troubleshooting - Common issues and solutions
🔗 ServiceNow Integration - Incident management setup

Overview

DORA (DevOps Research and Assessment) metrics help you measure and improve your software delivery performance. This guide explains how DevGrid calculates each metric and what data you need to provide.

Important: All timestamps are converted to UTC for consistent calculations across timezones.

Prerequisites

Before you can track DORA metrics, ensure you have:

✅ DevGrid Account - Sign up at devgrid.io
✅ API Key - Generated from DevGrid Settings → API Keys
✅ Application Entities - Created in DevGrid for each service you want to track
✅ CI/CD Integration - Deployment events sent from your pipeline (see examples)
✅ Version Control Connected - GitHub/GitLab/Bitbucket (required for Lead Time)
✅ Incident Management Connected - ServiceNow or similar (required for MTTR and CFR)

Deployment Frequency

What it measures: How often your team successfully deploys code to production.

What Counts as a Deployment

✅ Production deployments only
✅ Rollbacks count as deployments
✅ Hotfixes count as deployments
❌ Failed CI/CD pipeline runs (these never reached production)

Two Views of the Same Metric

View 1: Deployments Per Time Period

We calculate your deployment rate across daily, weekly, and monthly windows:

Daily deployments = Number of deployments / Total days in window
Weekly deployments = Daily deployments × 7
Monthly deployments = Daily deployments × 30

Example:

Window: 60 days
Total production deployments: 12

Daily rate = 12 / 60 = 0.2 deployments per day
Weekly rate = 0.2 × 7 = 1.4 deployments per week
Monthly rate = 0.2 × 30 = 6 deployments per month

View 2: Average Time Between Deployments

For each consecutive pair of deployments, we calculate:

Time between = Deployment[n+1] timestamp - Deployment[n] timestamp
Average time between deployments = Sum(all time differences) / Number of deployment pairs

We show both views because teams resonate with different perspectives. Some want "deployments per week," others want "average hours between deployments."

Lead Time for Change

What it measures: How long it takes for a code commit to reach production.

Calculation Method

For each deployment:

Identify the Pull Request (PR) associated with the deployment
Find the timestamp of the previous deployment
Find the first commit in the PR that occurred after the previous deployment
Calculate: Current deployment timestamp - First commit timestamp
Repeat for all deployments and take the final average

Key Considerations

Only the first commit after the previous deployment is measured - this represents when work started on this change
If you use squash commits, be aware this may affect accuracy

Example

Previous deployment: 2025-10-20T14:00:00Z
Current deployment (PR #123): 2025-10-30T18:25:43Z

PR #123 contains multiple commits:
- Commit A: 2025-10-22T10:30:00Z (first commit after previous deployment) ✓
- Commit B: 2025-10-25T15:00:00Z
- Commit C: 2025-10-29T08:00:00Z

Lead time for this deployment = 2025-10-30T18:25:43Z - 2025-10-22T10:30:00Z
                               = ~8 days

Repeat for all deployments and average the results.

Mean Time to Restore (MTTR)

What it measures: How quickly your team recovers from production incidents.

Calculation

MTTR = Average(Resolved timestamp - Detected timestamp)

Important Notes

Detected timestamp: When the incident was created in your incident management system (e.g., ServiceNow)
Resolved timestamp: When the incident was marked as resolved/closed
Only resolved incidents are included (open incidents are excluded from calculation)

Priority-Based Filtering

MTTR can be calculated for different incident priorities:

P1 MTTR (critical outages)
P2 MTTR (major issues)
P3 MTTR (minor issues)
P4 MTTR (low priority)
All Priorities MTTR (combined view)

This allows you to understand recovery times for critical vs. minor incidents separately.

Example

Incident 1: Opened 2025-10-01T10:00:00Z, Closed 2025-10-01T12:00:00Z (2 hours)
Incident 2: Opened 2025-10-05T14:00:00Z, Closed 2025-10-05T16:30:00Z (2.5 hours)
Incident 3: Opened 2025-10-10T08:00:00Z, Closed 2025-10-10T09:00:00Z (1 hour)

MTTR = (2 + 2.5 + 1) / 3 = 1.83 hours average

Change Failure Rate (CFR)

What it measures: The percentage of deployments that result in production incidents requiring remediation.

🚨 CRITICAL REQUIREMENT 🚨

You MUST provide a link between incidents and the deployments that caused them. This data must come from your systems - we cannot automatically infer which deployment caused which incident.

What Counts as a Failed Deployment

✅ Production deployments that caused incidents requiring remediation
❌ CI/CD pipeline failures (these never reached production)
❌ Incidents that happened near a deployment but weren't caused by it

Calculation

CFR = (Number of deployments that caused incidents / Total number of deployments) × 100

Example

Time window: 90 days
Total production deployments: 60
Deployments that caused incidents: 30

CFR = (30 / 60) × 100 = 50%

Implementation Considerations

Since incident causation isn't always immediately clear:

Link incidents to deployments in your incident management system
If an incident's root cause is later determined to be unrelated to a deployment, update the linkage in your system
The metric accuracy depends on your team's diligence in linking incidents to their actual root causes

Data Sources & Integration

Supported Integrations

DevGrid integrates with the following platforms:

Version Control & CI/CD:

GitHub
GitLab
Bitbucket

Incident Management:

ServiceNow (primary platform for pilot customers)
Other platforms supported (contact your account team)

How Data Flows to DevGrid

Deployment Events

You send deployment events to the DevGrid API when deployments occur. This gives you full control over what constitutes a "deployment" in your environment.

API Endpoint:

POST https://api.dev.devgrid.io/events
POST https://prod.api.devgrid.io/events

Authentication:

Include your DevGrid API key in the request headers
Header: x-api-key: YOUR_API_KEY

Sample JSON Payload:

{
  "events": [
    {
      "type": "event-deploy",
      "timestamp": "2025-10-29T18:25:43Z",
      "entityShortId": "your-app-entity-id",
      "attributes": {
        "env": "production",
        "status": "success",
        "build_id": "build-12345",
        "build_commit_sha": "a1b2c3d4e5f6",
        "build_url": "https://ci.example.com/builds/12345",
        "description": "Deploy v2.3.1 to production",
        "initiator": "[email protected]",
        "change_id": "CHG0012345",
        "change_url": "https://servicenow.example.com/change/CHG0012345",
        "change_title": "Production deployment v2.3.1",
        "change_author": "[email protected]",
        "change_approver": "[email protected]",
        "change_window_start": "2025-10-29T18:00:00Z",
        "change_window_end": "2025-10-29T20:00:00Z",
        "deployment_start_time": "2025-10-29T18:25:43Z"
      }
    }
  ]
}

Required fields:

type: Must be "event-deploy" for deployment events
timestamp: Deployment timestamp in ISO 8601 format (UTC)
entityShortId: The DevGrid entity ID (typically your application/service ID)
attributes.env: Environment (e.g., "production", "staging", "dev")
attributes.status: Deployment status ("success" or "failed")

Optional but recommended fields:

attributes.build_id: CI/CD build identifier
attributes.build_commit_sha: Git commit SHA
attributes.build_url: URL to the CI/CD build job
attributes.description: Human-readable description
attributes.initiator: Person or system that triggered the deployment
attributes.change_id: Change management system ticket ID (required for linking incidents to deployments)
attributes.change_url: URL to the change management ticket
attributes.change_title: Change ticket title
attributes.change_author: Change ticket author
attributes.change_approver: Change ticket approver
attributes.change_window_start: Scheduled change window start time
attributes.change_window_end: Scheduled change window end time
attributes.deployment_start_time: When the deployment actually started

Integration methods:

Direct API calls from your CI/CD pipeline
Webhook forwarding from GitHub/GitLab/Bitbucket
DevGrid CLI tool: ./devgrid-cli event --type event-deploy --entityShortId <entity-id> --attributes <json>
DevGrid API keys for authentication (set DEVGRID_API_KEY environment variable for CLI)

Commit & Pull Request Data

We pull commit history and PR metadata directly from your version control system via API integration.

What we collect:

Commit timestamps
Commit-to-PR associations
PR merge times
Branch information

Setup:

Provide API keys or OAuth tokens for your GitHub/GitLab/Bitbucket organization
Configure repository access permissions

Incident Data

We integrate with your incident management system to collect incident records.

What we collect:

Incident creation timestamp (detection time)
Incident resolution timestamp (closed time)
Incident priority/severity (P1, P2, P3, P4)
Deployment link (required for Change Failure Rate)

Setup:

ServiceNow: API integration using your instance credentials
Other platforms: Contact your DevGrid account team for custom integration options

Critical: Change Failure Rate Data Requirement

For CFR calculations to work, your incident records MUST include a link to the deployment that caused the incident.

In ServiceNow: Add a custom field or use an existing field (e.g., "Related Deployment," "Caused By") that references the deployment ID.

Example incident record:

Incident: INC0012345
Priority: P1
Created: 2025-10-15T14:30:00Z
Resolved: 2025-10-15T16:45:00Z
Caused By Deployment: deploy-abc123  ← THIS IS REQUIRED

Without this link, we cannot calculate your Change Failure Rate accurately.

Data Requirements Summary

Metric	Required Data	Source System
Deployment Frequency	Production deployment timestamps	DevGrid API (you push)
Lead Time for Change	Deployment timestamps, PR associations, commit timestamps	DevGrid API + GitHub/GitLab/Bitbucket
Mean Time to Restore	Incident detection timestamps, resolution timestamps, priority levels	ServiceNow (or other incident system)
Change Failure Rate	Deployment timestamps, incident-to-deployment linkages	DevGrid API + ServiceNow with deployment links

Data Validation

How to Verify Your Events Are Being Received

After sending deployment events, verify they're being processed correctly:

Check API Response:

curl -X POST https://prod.api.devgrid.io/events \
  -H "x-api-key: $DEVGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [...]}' \
  -v

Look for:

HTTP 201 status code
"success": [...] array containing your events
Empty "failures": [] array

Verify in DevGrid UI:

Log in to DevGrid
Navigate to your application
Check the Events tab
Confirm recent deployment events appear

Check Metrics Dashboard:

Go to Metrics → DORA Metrics
Note: Metrics are calculated daily at UTC midnight
You may need to wait until the next day to see updated metrics

Testing Your Integration

Before deploying to production:

Test in DevGrid Development Environment:

curl -X POST https://api.dev.devgrid.io/events \
  -H "x-api-key: $DEVGRID_DEV_API_KEY" \
  -d '{"events": [...]}'

Send Test Deployment:

Use a test entity ID
Include all required fields
Verify event appears in DevGrid

Test Failure Scenarios:

Invalid entity ID
Missing required fields
Malformed JSON
Verify error messages are helpful

Data Freshness

Understanding when your data updates:

Data Type	Update Frequency	Notes
Deployment Events	Immediate	Events appear in DevGrid within seconds of API call
DORA Metrics	Daily at UTC midnight	Metrics recalculated once per day
Commit/PR Data	Hourly	Synced from GitHub/GitLab/Bitbucket every hour
Incident Data	Hourly	Synced from ServiceNow every hour

Important: Even though events are ingested immediately, metrics won't reflect changes until the next daily calculation (UTC midnight).

Visual Overview

Data Flow Diagram

┌─────────────────┐
│   CI/CD Pipeline │
│  (GitHub Actions,│
│   GitLab CI,     │
│   Jenkins, etc.) │
└────────┬────────┘
         │ Deployment Events
         │ (with build_commit_sha,
         │  change_id, env, etc.)
         ▼
┌─────────────────────────┐
│   DevGrid Events API    │
│  POST /events           │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐     ┌──────────────────┐
│   DevGrid Platform      │◄────┤   GitHub/GitLab  │
│                         │     │  (Commits & PRs) │
│  • Stores events        │     └──────────────────┘
│  • Links data           │
│  • Calculates metrics   │     ┌──────────────────┐
│    (daily at UTC 00:00) │◄────┤   ServiceNow     │
└─────────┬───────────────┘     │  (Incidents)     │
          │                     └──────────────────┘
          ▼
┌─────────────────────────┐
│   DORA Metrics          │
│                         │
│  • Deployment Frequency │
│  • Lead Time for Change │
│  • Change Failure Rate  │
│  • Mean Time to Restore │
└─────────────────────────┘

Lead Time Calculation Flow

Deployment N-1        First Commit         Deployment N
     │                    │                     │
     │                    │                     │
     ▼                    ▼                     ▼
2025-10-20          2025-10-22           2025-10-30
  14:00                10:30                18:25
                       │◄──────────────────►│
                       Lead Time = ~8 days

Change Failure Rate Dependencies

Deployment Event (DevGrid)
     │
     ├─ change_id: "CHG0012345"
     │
     ▼
ServiceNow Incident
     │
     ├─ Caused By Deployment: "CHG0012345"  ← MUST MATCH
     │
     ▼
CFR Calculation
     │
     └─ This deployment caused an incident = FAILURE

Questions?

These calculations align with industry-standard DORA metric definitions. If you have questions about how to structure your data or integrate with DevGrid, contact your account team.