Clarify OpenAPI traffic matching

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 `@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].
+
 ### 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

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
 
@@ -59,9 +59,25 @@ The Endpoints list is based on APM tracing, so make sure your [services are inst
 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:
+
+- `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
 
-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
 
@@ -81,3 +97,4 @@ The Endpoints list relies on APM tracing, so traffic information is displayed on
 [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