--- title: "How should I set up the DX catalog for DORA metrics?" canonical_url: "https://docs.getdx.com/knowledgebase/how-should-i-set-up-the-dx-catalog-for-dora-metrics/" md_url: "https://docs.getdx.com/knowledgebase/how-should-i-set-up-the-dx-catalog-for-dora-metrics.md" last_updated: "2026-05-22" --- # How should I set up the DX catalog for DORA metrics? The DX catalog links incident, deployment, and service ownership data so DORA metrics can be calculated at the service and team level. DX recommends defining your production services and ownership in the catalog before sending deployment and incident data whenever you already maintain that service list outside DX. This approach keeps the DX catalog synchronized with your source of truth, makes service ownership explicit, and helps you identify which services still need deployment or incident data before DORA metrics are complete. ## Recommended approach: Define services first Use this approach when you have an existing list of production services, service owners, or ownership mappings that can be synced into DX. ### Step 1: Create services in the catalog Create each production service with [`catalog.entities.create`](https://docs.getdx.com/webapi/methods/catalog.entities.create/) or [`catalog.entities.upsert`](https://docs.getdx.com/webapi/methods/catalog.entities.upsert/). Include the service `identifier`, `name`, and ownership fields such as `owner_team_ids`, `owner_user_ids`, or `owner_user_emails`. Each service should use the same `identifier` that your deployment and incident sources will send to DX. ### Choose stable service identifiers Use service identifiers that are stable, globally unique, and shared across deployment and incident sources. The identifier should not change when a service display name changes. Large enterprises should not use only the service name as the identifier. Multiple organizations, business units, or product areas may have services with the same name, which can cause deployments from distinct services to be attributed to a single catalog service. Use an internal service ID when one exists. If you do not have a stable internal ID, use a prefixed identifier such as `-` or `-`. ### Step 2: Send deployment data for those services Send production deployment data with [`deployments.create`](https://docs.getdx.com/datacloudapi/methods/deployments.create/). The `service.identifier` value in each deployment must match the catalog service identifier. When the identifiers match, DX attributes the deployment to the existing catalog service automatically. ### Step 3: Send incident data for those services Send incident data with [`incidents.upsert`](https://docs.getdx.com/datacloudapi/methods/incidents.upsert/). Include service identifiers that match the same catalog services used for deployments. When deployment and incident records use the same service identifiers, DX can associate both data types with the same catalog service for DORA reporting. ### Why DX recommends this approach Defining services first gives DX a complete catalog before DORA instrumentation is fully in place. This helps platform and engineering operations teams answer questions such as: - Which production services are already in the catalog? - Which services have deployment data? - Which services have incident data? - Which services have owners assigned? - Why are DORA metrics missing for a specific service? This is the best fit for customers that already maintain service and ownership data in an internal system, CMDB, Backstage catalog, repository metadata, or another source of truth. ### Why ownership matters DX uses service ownership to support filtering and aggregating DORA metrics by team. If a service has deployment and incident data but does not have ownership assigned, service-level data may exist while team-level DORA views remain incomplete. ## Alternative approach: Let DX create services from deployment and incident data Use this approach when you do not have a reliable service catalog to sync into DX, or when instrumenting deployment and incident sources is the fastest way to discover services. DX creates a catalog service when it receives a service identifier from [`deployments.create`](https://docs.getdx.com/datacloudapi/methods/deployments.create/) or [`incidents.upsert`](https://docs.getdx.com/datacloudapi/methods/incidents.upsert/) that does not already exist in the catalog. DX uses the service `identifier` and `name` from the incoming record to create the service entry. ### If you send incidents through incidents.upsert If you send incident data through [`incidents.upsert`](https://docs.getdx.com/datacloudapi/methods/incidents.upsert/), the incident service identifiers must match the deployment service identifiers from [`deployments.create`](https://docs.getdx.com/datacloudapi/methods/deployments.create/) for DX to associate both data types with the same catalog service. For example, deployments and incidents for the payments service should both use the same identifier, such as `payments-service`. If deployment and incident API calls use different identifiers for the same production service, DX creates separate catalog entries: - One service with deployment data and no incident data. - One service with incident data and no deployment data. In that case, DORA metrics may be incomplete or split across services until the catalog is corrected. ### If you connect an incident management tool If you connect an incident management tool instead of sending incident data through [`incidents.upsert`](https://docs.getdx.com/datacloudapi/methods/incidents.upsert/), DX receives incident services from that tool. DX automatically aliases an incident service to a catalog service when the incident service name matches the catalog service identifier. If the incident service name does not match the catalog service identifier, associate the incident service with the correct catalog service. You can do this manually by setting the incident service alias on the catalog service, or programmatically with [`catalog.entities.update`](https://docs.getdx.com/webapi/methods/catalog.entities.update/). Use programmatic updates when you need to maintain mappings for many services or when your incident service mappings already exist in another system. ### Ownership considerations Services created implicitly from deployment or incident data may not have the ownership mapping you want. Large customers usually need to update those services with [`catalog.entities.update`](https://docs.getdx.com/webapi/methods/catalog.entities.update/) or sync ownership later with [`catalog.entities.upsert`](https://docs.getdx.com/webapi/methods/catalog.entities.upsert/). ## Choosing an approach | Approach | Best for | Tradeoff | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Define services first** | Customers with an existing list of production services and ownership mappings. | Requires catalog setup before DORA instrumentation, but gives the clearest view of missing data. | | **Create services from DORA data** | Customers that do not have a catalog source of truth or want to start by instrumenting deployments and incidents. | Faster to start, but only services with deployment or incident data appear in the catalog. Ownership may need to be added later. | For more implementation details, see [Setting up DORA metrics](https://docs.getdx.com/reports/dora-metrics/). --- ## Sitemap [Overview of all docs pages](/llms.txt)