Documentation Index
Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Overview
DevEx Metrics helps you understand developer productivity at your organization. The plugin, displayed as a tab within the Insights plugin, automatically collects and ingests important data points covering the developer lifecycle (pull requests, CI/CD executions, incidents, and more) and aggregates them into metrics that are displayed in intuitive visualizations and dashboards. On the main page, you’ll get a snapshot of all metrics, grouped into categories like “DORA Metrics” and “AI Usage Metrics.” Each metric snapshot shows comparisons to previous periods as well as one or more supporting metrics for additional context.
Even though DevEx Metrics is shown within the Insights plugin, all data is
stored within your Portal instance and is covered by all of the same data
security and data privacy controls in place for the rest of the data available
in your Portal instance.
Getting started
No action is necessary to get started! Core metrics that can be derived from systems for which you’ve already granted Portal access (e.g. SCM providers like GitHub or Azure DevOps) are available as soon as initial data loads are complete. Default metric calculations are based on input from developer productivity experts at Spotify and are designed to have the widest relevance within organizations.Configuring sources
While many core metrics are automatically derived from data already available to Portal, you can unlock additional metrics by configuring credentials for relevant source systems. To add credentials for a source, click the ”?” icon to open the “Learn More” drawer for a given metric. There, you’ll see a list of Data Sources that can be used to power that metric, as well as a configuration status. Click the “Manage Integration” icon to add credentials in Portal’s integration settings.
Supported sources
| Type | Source | Details |
|---|---|---|
| Source Code Management | GitHub | Deployment frequency, lead time for change, and supporting metrics can be tracked via repositories, pull requests, and workflow runs; these are automatically ingested based on credentials you’ve already configured in Portal. CI metrics derived from GitHub Actions are currently in beta. |
| Azure DevOps | Deployment frequency, lead time for change, and supporting metrics can be tracked via repositories, pull requests, and workflow runs; these are automatically ingested based on credentials you’ve already configured in Portal. | |
| AI | GitHub Copilot | Copilot usage and billing data can be ingested to track key AI Usage metrics. Follow the guide above to configure this source. |
| Cursor | Cursor data can be used to track key AI usage metrics. Grab an Admin API key and follow the guide above to configure this source. | |
| Claude | Coming soon. | |
| Incident Management | PagerDuty | Time to Recovery and supporting metrics can be tracked via incidents and services; learn more aboutusing PagerDuty in Portal, then follow the guide above to configure this source. |
Configuring metric calculations
Most metrics are built on common assumptions about how organizations use tools, however some metrics require additional configuration for accuracy. Like data sources, metric configurations can be configured from a metric’s “Learn More” drawer: in the section outlining how the metric is calculated, an “Edit” icon will appear. Clicking the icon will expose a form specific to the metric.
Measurement strategies
Some metrics support multiple measurement strategies. A measurement strategy controls the underlying methodology used to calculate a metric — for example, which events or signals are counted. When more than one strategy is available, you can switch between them by going to the metric’s “Learn More” drawer > Edit Calculation to find the approach that best matches how your organization works. Strategies are configured separately for each SCM provider (e.g. GitHub and Azure DevOps), so you can tailor the calculation to each provider’s tooling. Measurement strategies are currently available for Deployment Frequency. Use them to define what counts as a “deployment” for your organization — whether that’s all pull requests merged to the main branch, matched CI/CD workflow runs, or neither.
Workflow filters
When you select a workflow-based measurement strategy for Deployment Frequency, you can add workflow filters to control which workflow runs are included in the metric calculation. Each filter can be set to include or exclude matching runs, and multiple filters can be combined. All text fields accept POSIX regular expressions, so a single filter can match an arbitrary number of workflows. Filters support multiple fields — for example, workflow name, branch, and conclusion — so you can express rules like “include all workflows whose name matches^deploy-.* on the main branch” or “exclude all runs with a failure conclusion.” Workflow filters only apply when a workflow-based strategy is selected.
Metrics that require configuration
The following metrics require configuration for accuracy: AI Cost Per Engaged User While variable costs are calculated based on data provided by each vendor, this metric also requires fixed license costs for each vendor. Engineering Time Saved Time savings is calculated based on Software Template executions; a per-template time savings estimation is required to calculate total time savings.Frequently asked questions
How does date filtering work?
DevEx Metrics allows you to set and compare dates in either rolling windows (e.g. the most recent 1, 3, or 6 months) for staying on top of recent trends, as well as fixed windows (e.g. quarters or halves) for big-picture reflection. In order to always show you complete, accurate data, the plugin aligns date windows to ISO weeks (Monday-to-Monday) when viewing data at a weekly granularity. At a monthly granularity, dates will be aligned to ISO months, except for the last month which ends before the last Monday.How does team filtering work?
In both the overview and metric detail views, you’re able to filter down to specific teams. These teams are groups represented in the Software Catalog. If your catalog represents group hierarchy accurately, selecting a higher-level group (e.g. a product area, department, or business unit) will effectively show metrics for all child ancestors that belong to the selected group. How each metric is filtered depends on the underlying data behind the metric, as well as the accuracy of metadata and relationships within the Catalog. Use the following table as a guide when troubleshooting team-based filtering of metrics.| Source | Required Relationship | Required Entity Metadata |
|---|---|---|
| GitHub Copilot Usage and Billing | Ensure that Users are accurately reflected as members of relevant Groups | Ensure that users’ GitHub logins are accurately reflected on the backstage.io/managed-by-location annotation. The Catalog Org provider should set this annotation for you. |
| Cursor or Claude Usage and Billing | Ensure that Users are accurately reflected as members of relevant Groups | Ensure that users’ spec.profile.email is set to the email address used to authenticate with Cursor or Claude. If you use the GitHub Org catalog provider, be sure to toggle on “Use Verified Emails.” A future release of Portal will handle this for you. |
| GitHub or Azure DevOps repositories, pull requests, CI/CD executions, etc. | Ensure that Components are accurately reflected as owned by relevant Groups, e.g. via spec.owner | Ensure that components have a backstage.io/source-location annotation that points to the repository where code is maintained. Catalog Providers and components that are managed by Portal should automatically set this annotation for you. |
| PagerDuty services and incidents | Ensure that Components are accurately reflected as owned by relevant Groups, e.g. via spec.owner | Ensure that entities’ various pagerduty.com/* annotations are set up correctly, either via an explicit pagerduty.com/service-id value, or via pagerduty.com/integration-key. You can use the PagerDuty plugin to help set these values in bulk, if they’re not already present. |