A Prometheus exporter for DORA (DevOps Research and Assessment) metrics.
DORA Exporter collects deployment events from GitHub and ticket events from Jira to calculate key DORA metrics. These metrics are exposed in Prometheus format and can be visualized using Grafana.
- GitHub deployment tracking
- Jira ticket monitoring
- Prometheus metrics export
- Team-based metrics aggregation
- Backstage integration
- Persistent metrics storage
The exporter:
- Listens for GitHub deployment webhooks
- Calculates deployment lead time by analyzing PR and commit data
- Exposes metrics for Prometheus to scrape
- Provides data for Grafana dashboards
dora-exporter listens to deployment events from GitHub and ticket events from Jira.
Upon every deployment GitHub triggers the webhook and calls dora-exporter with payload containing information about deployment environment and deployed commit.
dora-exporter tries to calculate duration of the commit either by looking into a related PR and the first commit in this PR, otherwise it takes the deployed commit duration.
The metrics about deployments count and deployments duration is enough to build DORA dashboards. Prometheus scrapes dora-exporter metrics and saves the data internally. Grafana uses Prometheus to query and build diagrams.
The exporter tracks two main metrics:
github_deployments_count: Counts successful deployments (labels: team, status, environment, repo)github_deployments_duration: Measures lead time from first commit to deployment
Team attribution can be configured via:
- Manual mapping in configuration file
- Backstage backend integration
Whenever GitHub deployment event received, dora-exporter does query to GitHub API to calculate a time between the first commit in the related Pull Request and deployment event.
This time is added to counter github_deployments_duration. Such counter contains labels:
team, status, environment, repo.
It could prove useful to supply -logs debug argument and check the output. Successful call log should look like this.
level=debug component=github_api call=https://api.github.com/repos/it-premium/adminka-core/git/commits/f68b7c12f90cf81adb6bae0e907693ebc435851b
level=debug component=github_api repo=adminka-core commit_info=f68b7c12f90cf81adb6bae0e907693ebc435851b
level=debug commit_message="chore(gems): nokogiri (#109)" pull_request_reference=found
level=debug component=github_api call=https://api.github.com/repos/it-premium/adminka-core/pulls/109/commits
level=debug component=github_api repo=adminka-core pull_request=109
level=debug repo=adminka-core sha=f68b7c12f90cf81adb6bae0e907693ebc435851b PR=109 date=pr_first_commit
level=debug commit_duration=25h33m42.887362188s
level=debug counter=deployments_count action=inc
level=debug counter=deployments_duration action=set value=92022.887365547
level=info endpoint=github environment=production repository=adminka-core status=in_progress team=Platform sha=f68b7c12f90cf81adb6bae0e907693ebc435851b
https://grafana.com/grafana/dashboards/20889-dora-v2/
DORA exporter is a single binary that doesn't require any dependencies. Though you might want to run it using docker. The default port is 8090, but this can be changed in the configuration.
docker run --rm -e GITHUB_TOKEN=gh_xxxxx -p 8090:8090 dora-exporterConfiguration file location can be specified using command line flag -config.file.
dora-exporter -config.file=config.ymlGitHub token is required to query information about the deployment and commit, so we expect the GITHUB_TOKEN environment variable to contain valid token. See Generate GitHub token for details.
DORA-exporter saves state in the prometheus compatible file format. This allows to preserve the statistics state between reboots.
Location for the storage can be set in the following config.yml section.
storage:
file:
path: /data/prometheus.promIt is advised to map it to the external volume to preserve state between restarts.
DORA exporter has support for catalog either from enterprise Backstage installation or from static source using Yaml configuration.
Backstage component in order to be available for dora-exporter query should contain github.com/project-slug annotation.
In case an owner can't be determined, default Unknown team will be used.
Example
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: dora-exporter
title: DORA-Metrics
description: DORA Metrics exporter
annotations:
github.com/project-slug: mprokopov/dora-exporter
github.com/team-slug: mprokopov/InfrastructurePut to the config file the following settings
catalog:
mode: backstage
endpoint: http://backstage.comStatis is the default mode and will use the information about the teams from the yaml dictionary as per example below.
catalog:
mode: static
teams:
- name: team1
github_repositories:
- owner/repo1
- owner/repo2
jira_projects:
- PROJECT1
- PROJECT2
- name: team2
github_repositories:
- owner/repo3
- owner/repo4Error level can be selected from command line using flag -log.
Possible error log values are: info,debug,warning or error
dora-exporter -log debugDora Exporter requires information about deployments of your applications. The easiest way is to setup a organization-wide webhook. Make sure your GitHub repository shows deployments information.
https://<dora-exporter-url>/api/github
Ensure GitHub repository has information about deployments
Ensure setting up organization-wide webhook as per screenshots. Deployments and Deployment statuses checkboxes should be selected.
If the integration successfull, and GitHub sends deployment signals to dora-exporter, its /metrics endpoint should contain github_deployments_duration metric.
# HELP github_deployments_duration The last deployments duration
# TYPE github_deployments_duration gauge
github_deployments_duration{environment="production",repo="adminka-core",status="in_progress",team="Platform"} 92022.887365547
github_deployments_duration{environment="production",repo="adminka-core",status="success",team="Platform"} 2677.657175116
github_deployments_duration{environment="staging",repo="adminka-core",status="in_progress",team="Platform"} 2820.405749159
github_deployments_duration{environment="staging",repo="adminka-core",status="success",team="Platform"} 2791.783721583
# HELP github_deployments_duration_sum The last deployments duration sum
# TYPE github_deployments_duration_sum gauge
github_deployments_duration_sum{environment="production",repo="adminka-core",status="in_progress",team="Platform"} 94778.17152176499
github_deployments_duration_sum{environment="production",repo="adminka-core",status="success",team="Platform"} 5294.0982427260005
github_deployments_duration_sum{environment="staging",repo="adminka-core",status="in_progress",team="Platform"} 2820.405749159
github_deployments_duration_sum{environment="staging",repo="adminka-core",status="success",team="Platform"} 2791.783721583
# HELP github_deployments_total The amount of successful deployments.
# TYPE github_deployments_total counter
github_deployments_total{environment="production",repo="adminka-core",status="in_progress",team="Platform"} 2
github_deployments_total{environment="production",repo="adminka-core",status="success",team="Platform"} 2
github_deployments_total{environment="staging",repo="adminka-core",status="in_progress",team="Platform"} 1
github_deployments_total{environment="staging",repo="adminka-core",status="success",team="Platform"} 1
Setup webhook for Jira issues to point to:
https://<dora-exporter-url>/api/jira
docker run --rm \
-e GITHUB_TOKEN=gh_xxxxx \
-p 8090:8090 \
dora-exporterSpecify a configuration file:
dora-exporter -config.file=config.ymlRequired environment variables:
GITHUB_TOKEN: GitHub API token with repository access
The exporter persists metrics in Prometheus format between restarts. Configure the storage location:
storage:
file:
path: /data/prometheus.promTip: Map this to an external volume in production environments.
Enable detailed logging:
dora-exporter -log debugLog levels:
info: Standard operational logsdebug: Detailed debugging informationwarning: Warning messageserror: Error conditions