/opendora

Team performance insights for your organization.

Primary LanguageGoGNU General Public License v3.0GPL-3.0

Backstage Plugin API Plugin version

OpenDORA

Team performance observability for your organization.

OpenDORA includes an open-source plugin for Backstage, a popular developer portal platform. It integrates with Apache DevLake to organize and aggregate data from deployment and project management tooling like Gitlab, GitHub, Jira, and Jenkins. OpenDORA extracts meaningful insights from this data through its API, and renders dashboards within Backstage that provide insights on the teams' performance.

What are DORA metrics?

DORA, short for DevOps Research and Assessment, is a research program that began in 2013 investigating ways to measure and improve software delivery, operations, team, and organizational performance. The program has collected data from thousands of professionals and publishes findings in annual reports.

The key 4 DORA metrics are:

  • Deployment frequency
  • Lead time to changes
  • Change failure rate
  • Mean time to recovery

Today, DORA metrics are widely accepted as a framework to determine stability and velocity of software teams. They provide a benchmark for determining the maturity of software teams, helping set a path towards high performance.

How does it work?

OpenDORA has largely a pluggable architecture, with some opinionated tooling choices that we can talk about at length. Ingestor scripts running on schedule fetch data from external tools (Gitlab, Jira, etc) and push them to DevLake. The devlake-go API exposes this data and provides endpoints to retrieve it from DevLake. The backstage-plugin utilizes this API and renders the results on the Backstage frontend. This is a React plugin based on Material UI.

Screenshot of the main OpenDORA dashboard

The resulting dashboard as rendered within Backstage:

Screenshot of the main OpenDORA dashboard

Below is a description of the main components of this repo.

backstage-plugin

This is a Backstage plugin setup used to develop the frontend plugin.

More details

devlake-go

This contains the docker image and configuration scripts to setup DevLake to properly ingest the DORA metrics from a GitLab repo and group them according to Backstage groups.

More details

dora-api-mock

This is a basic Spring application used to provide a mock for the DORA API metric datapoints. This can be used to develop the frontend plugin without needing to setup the local backend API.

More details

Setup

Goto Plugin setup documentation and follow the steps to install and setup the plugin in your Backstage environment.

Contributor Guide

The OpenDORA team are looking for feedback and contributions. We encourage you to try out the Backstage plugin or other parts of the solution. Please create an issue on GitHub or reach out to us at opendora@devoteam.com.

We also accept pull requests for the code and documentation. Kindly use the discussions in the issue, and please read the contribution guidelines page.

DORA Plugin Development Environment

Prerequisites

  • Docker Runtime
  • Docker Compose

Configuring the Environment

Running the Dev Environment

OpenDORA contains an initial Docker Compose with the services needed to test the metrics in the dev's local environment.

  • Make sure you have copied the .env.dist to .env. The .env is in .gitignore because it contains secrets and custom configuration
cp .env.dist .env
  • Run the Docker environment with Docker Compose v2.*
docker compose --profile dev up -d

It may take some time for all the containers to be available. Healthchecks to monitor this are not available right now.

  • When using the development profile. There won't be a Devlake available to manage. Instead, It will use a mock-api to create responses. If you want to test Opendora with a Devlake instance, use the test profile.
docker compose --profile test up -d
  • A Grafana container is also available in case you want to access the default dashboards delivered with Apache DevLake.

To start it, run the below:

docker compose --profile dashboard up -d

After that, the services will be accessible on the below:

For more information about Docker Compose, check their official documentation: Docker Compose

Apache DevLake

Before running the Dev Environment, some minor configurations needs to be performed. This development environment already provides default values for the majority of them but at least an encryption key (DEVLAKE_ENCRYPTION_SECRET) needs to be provided.

To generate one, run the below:

openssl rand -base64 2000 | tr -dc 'A-Z' | fold -w 128 | head -n 1

It can be configured globally, and it will be picked up by the docker compose, or it can be added to the .env file.

Some environment variables can be customised. The list below has all of them as well as their default values:

Variable Name Default Value
DEVLAKE_ENCRYPTION_SECRET
DEVLAKE_MYSQL_USER merico
DEVLAKE_MYSQL_PASSWORD merico
DEVLAKE_MYSQL_CONNECTION_URL mysql://merico:merico@mysql:3306/lake?charset=utf8mb4&parseTime=True
DEVLAKE_ADMIN_USER devlake
DEVLAKE_ADMIN_PASSWORD merico

For more information on how to configure Apache DevLake with docker compose, check their official reference: Launch DevLake with Docker Compose.

Also, make sure to check DevLake's Configuration documentation to correctly configure the connection, data scope, etc. For the DORA metrics, the most important part is the transformations, so make sure to configure it accordingly (job names) for the metrics to be properly calculated.