From b7dff9e2316728532a86cde39c97683348bf1ffa Mon Sep 17 00:00:00 2001 From: datadog-bits <263423550+datadog-bits@users.noreply.github.com> Date: Tue, 21 Jul 2026 08:02:36 +0000 Subject: [PATCH 1/4] Clarify OpenAPI traffic matching --- .../catalog/endpoints/_index.md | 12 ++++++++++++ .../catalog/troubleshooting.md | 11 ++++++----- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/content/en/internal_developer_portal/catalog/endpoints/_index.md b/content/en/internal_developer_portal/catalog/endpoints/_index.md index 357142251ef..50b6d7ea2a8 100644 --- a/content/en/internal_developer_portal/catalog/endpoints/_index.md +++ b/content/en/internal_developer_portal/catalog/endpoints/_index.md @@ -87,6 +87,16 @@ Assign automatically detected endpoints to API groups to track usage, define own Read [Adding Entries][9] for more information. +### How OpenAPI specifications are combined with traffic + +When you add an OpenAPI specification to an API entity, Datadog adds each declared HTTP method and path to the Endpoints list, including endpoints for which Datadog has not observed traffic. Datadog then compares recent endpoint telemetry with the specification and combines the data when all of the following values match: + +- **Service**: The service from the telemetry matches a service in the API entity's `spec.implementedBy` field. If the telemetry contains a service override, Datadog also checks its [`base_service`][13]. A definition without `spec.implementedBy` can match the same route on any service, so specify this field to avoid broad or ambiguous matches. +- **HTTP method**: The observed method matches the method declared in the specification. +- **Path**: Literal path segments match exactly. OpenAPI path parameters, such as `{user_id}`, match a single segment. Datadog first checks the observed URL path, then the normalized `http.route` value. + +When these values do not match unambiguously, the endpoint declared by the specification and the endpoint discovered from traffic remain separate entries. For an API entity example that uses `spec.implementedBy`, see [API entities][14]. + ### Adding metadata to APIs Add metadata to APIs through the Datadog UI or API, or use automated pipelines through the GitHub integration or Terraform. @@ -116,3 +126,5 @@ Read [Adding Metadata to APIs][10] for more information. [10]: /internal_developer_portal/catalog/entity_model/ [11]: /internal_developer_portal/catalog/endpoints/explore_endpoints/ [12]: https://app.datadoghq.com/services?selectedComponent=endpoint +[13]: /tracing/guide/base_service/ +[14]: /internal_developer_portal/catalog/entity_model/native_entities/#api diff --git a/content/en/internal_developer_portal/catalog/troubleshooting.md b/content/en/internal_developer_portal/catalog/troubleshooting.md index 1284966bc40..9e323277310 100644 --- a/content/en/internal_developer_portal/catalog/troubleshooting.md +++ b/content/en/internal_developer_portal/catalog/troubleshooting.md @@ -54,14 +54,15 @@ The total monitor count displayed on the **Setup Guidance** tab for a single ser The Endpoints list is based on APM tracing, so make sure your [services are instrumented][7]. -### Definition matches too many services +### Definition and traffic appear as separate endpoints -By default, the Endpoints list matches a definition to all instances that fit the defined path. -You can scope the definition to a specific service by adding the [service parameter][6] to the API definition. +Datadog combines traffic with an OpenAPI definition by matching the service, HTTP method, and path. If the definition and traffic remain separate, verify that `spec.implementedBy` includes the service from the telemetry, the HTTP methods match, and the paths use compatible literal segments and path parameters. For service overrides, Datadog also checks `base_service`. + +A definition without `spec.implementedBy` can match the same route on any service. Define the implementing services to avoid broad or ambiguous matches. For the complete matching rules, see [How OpenAPI specifications are combined with traffic][8]. ### No telemetry data for OpenAPI file -The Endpoints list is derived from APM tracing, so traffic information is displayed only if traces are available for the endpoint. After uploading an OpenAPI file, deployment data becomes visible after Datadog ingests a span for the endpoint. +Uploading an OpenAPI file adds its declared endpoints to the Endpoints list even if Datadog has not observed traffic. Traffic and performance information become visible after Datadog ingests matching spans for an endpoint. ### No data for new monitor @@ -79,5 +80,5 @@ The Endpoints list relies on APM tracing, so traffic information is displayed on [3]: /tracing/guide/setting_primary_tags_to_scope [4]: /help/ [5]: /tracing/trace_pipeline/ingestion_controls/ -[6]: /api_catalog/add_metadata/ [7]: /tracing/trace_collection/ +[8]: /internal_developer_portal/catalog/endpoints/#how-openapi-specifications-are-combined-with-traffic From 8fe78f3877439c06ae526c359a688ca8ba6ca345 Mon Sep 17 00:00:00 2001 From: datadog-bits <263423550+datadog-bits@users.noreply.github.com> Date: Tue, 21 Jul 2026 08:13:23 +0000 Subject: [PATCH 2/4] Document OpenAPI span matching details --- .../catalog/endpoints/_index.md | 4 ++-- .../catalog/troubleshooting.md | 12 +++++++++++- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/content/en/internal_developer_portal/catalog/endpoints/_index.md b/content/en/internal_developer_portal/catalog/endpoints/_index.md index 50b6d7ea2a8..f9928e1783a 100644 --- a/content/en/internal_developer_portal/catalog/endpoints/_index.md +++ b/content/en/internal_developer_portal/catalog/endpoints/_index.md @@ -92,8 +92,8 @@ Read [Adding Entries][9] for more information. When you add an OpenAPI specification to an API entity, Datadog adds each declared HTTP method and path to the Endpoints list, including endpoints for which Datadog has not observed traffic. Datadog then compares recent endpoint telemetry with the specification and combines the data when all of the following values match: - **Service**: The service from the telemetry matches a service in the API entity's `spec.implementedBy` field. If the telemetry contains a service override, Datadog also checks its [`base_service`][13]. A definition without `spec.implementedBy` can match the same route on any service, so specify this field to avoid broad or ambiguous matches. -- **HTTP method**: The observed method matches the method declared in the specification. -- **Path**: Literal path segments match exactly. OpenAPI path parameters, such as `{user_id}`, match a single segment. Datadog first checks the observed URL path, then the normalized `http.route` value. +- **HTTP method**: The `http.method` span attribute matches the method declared in the specification. +- **Path**: The span must have an `http.route` attribute. Datadog first compares `http.url_details.path` with the declared path and then falls back to the normalized `http.route` value. Literal path segments match exactly. OpenAPI path parameters match one segment: for example, `/users/{user_id}` matches `/users/123`, but not `/users/123/orders`. When these values do not match unambiguously, the endpoint declared by the specification and the endpoint discovered from traffic remain separate entries. For an API entity example that uses `spec.implementedBy`, see [API entities][14]. diff --git a/content/en/internal_developer_portal/catalog/troubleshooting.md b/content/en/internal_developer_portal/catalog/troubleshooting.md index 9e323277310..782c6593107 100644 --- a/content/en/internal_developer_portal/catalog/troubleshooting.md +++ b/content/en/internal_developer_portal/catalog/troubleshooting.md @@ -56,10 +56,20 @@ The Endpoints list is based on APM tracing, so make sure your [services are inst ### Definition and traffic appear as separate endpoints -Datadog combines traffic with an OpenAPI definition by matching the service, HTTP method, and path. If the definition and traffic remain separate, verify that `spec.implementedBy` includes the service from the telemetry, the HTTP methods match, and the paths use compatible literal segments and path parameters. For service overrides, Datadog also checks `base_service`. +Datadog combines traffic with an OpenAPI definition by matching the service, HTTP method, and path. If the definition and traffic remain separate, verify the following: + +- `spec.implementedBy` includes the `service` from the span. For service overrides, Datadog also checks `base_service`. +- The span's `http.method` matches the method in the definition. +- The span has `http.route`, and its `http.url_details.path` or `http.route` matches the defined path. A path parameter matches exactly one segment. For example, `/users/{user_id}` matches `/users/123`, but not `/users/123/orders`. A definition without `spec.implementedBy` can match the same route on any service. Define the implementing services to avoid broad or ambiguous matches. For the complete matching rules, see [How OpenAPI specifications are combined with traffic][8]. +### Catch-all definition does not combine with traffic + +A catch-all path is a path made entirely of parameters, such as `/{resource}` or `/{resource}/{id}`. To prevent an ambiguous match across services, Datadog does not combine traffic with an unscoped catch-all definition. Add the traffic's service to `spec.implementedBy`. + +For example, `GET /{resource}` without `spec.implementedBy` remains separate from traffic with `service:store-api`, `http.method:GET`, and `http.route:/orders`. Adding `service:store-api` to `spec.implementedBy` allows them to combine. Each parameter still matches only one path segment, so `/{resource}` does not match `/orders/123`; use `/{resource}/{id}` for that shape. + ### No telemetry data for OpenAPI file Uploading an OpenAPI file adds its declared endpoints to the Endpoints list even if Datadog has not observed traffic. Traffic and performance information become visible after Datadog ingests matching spans for an endpoint. From 17aa1331e1ad476ad02ba6173c7aaff5d1f1ec9d Mon Sep 17 00:00:00 2001 From: datadog-bits <263423550+datadog-bits@users.noreply.github.com> Date: Tue, 21 Jul 2026 08:16:42 +0000 Subject: [PATCH 3/4] Restore broad definition troubleshooting --- .../en/internal_developer_portal/catalog/troubleshooting.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/en/internal_developer_portal/catalog/troubleshooting.md b/content/en/internal_developer_portal/catalog/troubleshooting.md index 782c6593107..ff6ae31edfe 100644 --- a/content/en/internal_developer_portal/catalog/troubleshooting.md +++ b/content/en/internal_developer_portal/catalog/troubleshooting.md @@ -54,6 +54,11 @@ The total monitor count displayed on the **Setup Guidance** tab for a single ser The Endpoints list is based on APM tracing, so make sure your [services are instrumented][7]. +### Definition matches too many services + +By default, the Endpoints list matches a definition to all instances that fit the defined path. +You can scope the definition to a specific service by adding the [service parameter][6] to the API definition. + ### Definition and traffic appear as separate endpoints Datadog combines traffic with an OpenAPI definition by matching the service, HTTP method, and path. If the definition and traffic remain separate, verify the following: @@ -90,5 +95,6 @@ The Endpoints list relies on APM tracing, so traffic information is displayed on [3]: /tracing/guide/setting_primary_tags_to_scope [4]: /help/ [5]: /tracing/trace_pipeline/ingestion_controls/ +[6]: /api_catalog/add_metadata/ [7]: /tracing/trace_collection/ [8]: /internal_developer_portal/catalog/endpoints/#how-openapi-specifications-are-combined-with-traffic From 0104dd69be320a37a2f7991578c3f92351f39be0 Mon Sep 17 00:00:00 2001 From: Nicolas Vivet Date: Tue, 21 Jul 2026 11:40:58 +0200 Subject: [PATCH 4/4] prepend span attributes with @ --- .../catalog/endpoints/_index.md | 4 ++-- .../catalog/troubleshooting.md | 18 +++++++++--------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/content/en/internal_developer_portal/catalog/endpoints/_index.md b/content/en/internal_developer_portal/catalog/endpoints/_index.md index f9928e1783a..57d52708899 100644 --- a/content/en/internal_developer_portal/catalog/endpoints/_index.md +++ b/content/en/internal_developer_portal/catalog/endpoints/_index.md @@ -92,8 +92,8 @@ Read [Adding Entries][9] for more information. When you add an OpenAPI specification to an API entity, Datadog adds each declared HTTP method and path to the Endpoints list, including endpoints for which Datadog has not observed traffic. Datadog then compares recent endpoint telemetry with the specification and combines the data when all of the following values match: - **Service**: The service from the telemetry matches a service in the API entity's `spec.implementedBy` field. If the telemetry contains a service override, Datadog also checks its [`base_service`][13]. A definition without `spec.implementedBy` can match the same route on any service, so specify this field to avoid broad or ambiguous matches. -- **HTTP method**: The `http.method` span attribute matches the method declared in the specification. -- **Path**: The span must have an `http.route` attribute. Datadog first compares `http.url_details.path` with the declared path and then falls back to the normalized `http.route` value. Literal path segments match exactly. OpenAPI path parameters match one segment: for example, `/users/{user_id}` matches `/users/123`, but not `/users/123/orders`. +- **HTTP method**: The `@http.method` span attribute matches the method declared in the specification. +- **Path**: The span must have an `@http.route` attribute. Datadog first compares `@http.url_details.path` with the declared path and then falls back to the normalized `@http.route` value. Literal path segments match exactly. OpenAPI path parameters match one segment: for example, `/users/{user_id}` matches `/users/123`, but not `/users/123/orders`. When these values do not match unambiguously, the endpoint declared by the specification and the endpoint discovered from traffic remain separate entries. For an API entity example that uses `spec.implementedBy`, see [API entities][14]. diff --git a/content/en/internal_developer_portal/catalog/troubleshooting.md b/content/en/internal_developer_portal/catalog/troubleshooting.md index ff6ae31edfe..0833bee9073 100644 --- a/content/en/internal_developer_portal/catalog/troubleshooting.md +++ b/content/en/internal_developer_portal/catalog/troubleshooting.md @@ -22,7 +22,7 @@ If you experience unexpected behavior with Datadog Catalog, this guide may help ### APM-instrumented services not appearing -If services that you know are instrumented for APM are not appearing in the Catalog list, it's likely because they have not been emitting performance data in the past hour for the selected `env` (or any primary tag values of your choosing) or [additional primary tags][1]. To confirm, on the **Performance** tab, hover over the columns where you expect the performance metrics to appear and see information on which environments the services are active. +If services that you know are instrumented for APM are not appearing in the Catalog list, it's likely because they have not been emitting performance data in the past hour for the selected `env` (or any primary tag values of your choosing) or [additional primary tags][1]. To confirm, on the **Performance** tab, hover over the columns where you expect the performance metrics to appear and see information on which environments the services are active. {{< img src="tracing/software_catalog/svc_cat_troubleshooting_1.png" alt="Hover message indicating that no performance data has been reported in the past hour" >}} @@ -32,21 +32,21 @@ The count in the Catalog Setup Guidance section reflects the number of SLOs with ### Additional telemetry is available to a service but it's not listed -Catalog relies on the `DD_SERVICE` tag in all telemetry types (infrastructure metrics, logs, Cloud Network Monitoring) to gather information about a given service. If you don't see a telemetry type that you expect in the Catalog, ensure that you have configured the `DD_SERVICE` tag according to the instructions in [Unified Service Tagging][2]. +Catalog relies on the `DD_SERVICE` tag in all telemetry types (infrastructure metrics, logs, Cloud Network Monitoring) to gather information about a given service. If you don't see a telemetry type that you expect in the Catalog, ensure that you have configured the `DD_SERVICE` tag according to the instructions in [Unified Service Tagging][2]. ### Can't add metadata for RUM services -Adding metadata for RUM services is not supported. +Adding metadata for RUM services is not supported. ### Multiple services share the same metadata - -If you have many services that share the same metadata, you do not need separate `service.datadog.yaml` files for each one. You can define multiple services in a single `service.datadog.yaml` file by separating each service with a `---` separator. Copy and paste the shared metadata for the relevant dd-service entities. + +If you have many services that share the same metadata, you do not need separate `service.datadog.yaml` files for each one. You can define multiple services in a single `service.datadog.yaml` file by separating each service with a `---` separator. Copy and paste the shared metadata for the relevant dd-service entities. ### Associated monitors not displayed in the Setup Guidance section -The Catalog associates monitors to services when they are tagged, scoped, or grouped with service or [APM primary tags][3]. +The Catalog associates monitors to services when they are tagged, scoped, or grouped with service or [APM primary tags][3]. -The total monitor count displayed on the **Setup Guidance** tab for a single service does not include muted monitors and groups. +The total monitor count displayed on the **Setup Guidance** tab for a single service does not include muted monitors and groups. ## Endpoints @@ -64,8 +64,8 @@ You can scope the definition to a specific service by adding the [service parame Datadog combines traffic with an OpenAPI definition by matching the service, HTTP method, and path. If the definition and traffic remain separate, verify the following: - `spec.implementedBy` includes the `service` from the span. For service overrides, Datadog also checks `base_service`. -- The span's `http.method` matches the method in the definition. -- The span has `http.route`, and its `http.url_details.path` or `http.route` matches the defined path. A path parameter matches exactly one segment. For example, `/users/{user_id}` matches `/users/123`, but not `/users/123/orders`. +- The span's `@http.method` matches the method in the definition. +- The span has `@http.route`, and its `@http.url_details.path` or `@http.route` matches the defined path. A path parameter matches exactly one segment. For example, `/users/{user_id}` matches `/users/123`, but not `/users/123/orders`. A definition without `spec.implementedBy` can match the same route on any service. Define the implementing services to avoid broad or ambiguous matches. For the complete matching rules, see [How OpenAPI specifications are combined with traffic][8].