Clarify AggregateSpans and GetTraceById usage in descriptions

.generator/schemas/v2/openapi.yaml

@@ -2190,13 +2190,18 @@ components:
         type: integer
     TraceIDPathParameter:
       description: |-
-        The trace ID. Accepts either a 32-character hexadecimal string (128-bit trace ID)
-        or a decimal string of up to 39 digits.
+        The trace ID. Accepts either a hexadecimal string of up to 32 characters (128-bit trace ID)
+        or a decimal string of up to 39 digits. Hexadecimal IDs are case-insensitive, and shorter
+        values are left-padded with zeros.
+        Use the `trace_id` attribute of a span returned by the Search spans or Get a list of spans endpoints.
+        Values in any other format, such as UUIDs, return `400 Bad Request`. A well-formed ID with
+        no matching trace returns `404 Not Found`.
       example: "0000000000000000abc1230000000000"
       in: path
       name: trace_id
       required: true
       schema:
+        pattern: "^([0-9a-fA-F]{1,32}|[0-9]{1,39})$"
         type: string
     UnitCostID:
       description: The UUID of the unit cost.
@@ -123792,8 +123797,11 @@ components:
       type: string
       x-enum-varnames: ["DONE", "TIMEOUT"]
     SpansAggregateSort:
-      description: A sort rule.
-      example: {"aggregation": "count", "order": "asc"}
+      description: |-
+        A sort rule. With `type: alphabetical` (the default), buckets are sorted by facet value
+        and only `order` is allowed. With `type: measure`, buckets are sorted by a computed value:
+        set `aggregation`, and set `metric` unless the aggregation is `count`.
+      example: {"aggregation": "pc90", "metric": "@duration", "order": "desc", "type": "measure"}
       properties:
         aggregation:
           $ref: "#/components/schemas/SpansAggregationFunction"
@@ -123903,7 +123911,10 @@ components:
           type: string
       type: object
     SpansCompute:
-      description: A compute rule to compute metrics or timeseries.
+      description: |-
+        A compute rule to compute metrics or timeseries.
+        All computes in a request must have the same `type`, and `timeseries` computes must use the same `interval`.
+        To get both totals and timeseries, send separate requests.
       properties:
         aggregation:
           $ref: "#/components/schemas/SpansAggregationFunction"
@@ -123957,7 +123968,12 @@ components:
           $ref: "#/components/schemas/SpansGroupByHistogram"
         limit:
           default: 10
-          description: The maximum buckets to return for this group by.
+          description: |-
+            The maximum buckets to return for this group by.
+            A request can generate at most 10,000 groups. Nested `group_by` entries multiply, so the
+            product of their limits must stay within that bound. For example, two entries with a limit of 100 each
+            produce up to 10,000 groups. With a `timeseries` compute, the number of groups multiplied by
+            the number of time buckets must not exceed 400,000.
           format: int64
           type: integer
         missing:
@@ -212855,6 +212871,8 @@ paths:
         Retrieve a pruned, hierarchical view of an APM trace by its trace ID.
         The trace is summarized as a tree of spans rooted at the trace root and reduced in size
         to keep rendering large traces in the UI practical.
+        A `400 Bad Request` response means the trace ID is malformed. A `404 Not Found` response means
+        no trace with this ID is available, such as when the trace is outside the retention period.
         This endpoint is rate limited to `60` requests per minute per organization.
       operationId: GetPrunedTraceByID
       parameters:
@@ -212967,6 +212985,12 @@ paths:
               schema:
                 $ref: "#/components/schemas/PrunedTraceResponse"
           description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Bad Request
         "403":
           content:
             application/json:
@@ -237716,6 +237740,11 @@ paths:
       description: |-
         The API endpoint to aggregate spans into buckets and compute metrics and timeseries.
         This endpoint is rate limited to `300` requests per hour.
+
+        A request can generate at most 10,000 groups across all `group_by` entries, or 400,000 groups
+        including time buckets when a `timeseries` compute is used. Set `limit` on each `group_by` entry
+        to stay within these bounds. Requests over long time ranges or with many groups are more resource-intensive
+        and can fail. To reduce load, narrow the time range or lower the `limit` on each `group_by` entry.
       operationId: AggregateSpans
       requestBody:
         content:
@@ -237735,14 +237764,13 @@ paths:
                         query: service:web* AND @http.status_code:[200 TO 299]
                         to: now
                       group_by:
-                        - facet: host
-                          histogram:
-                            interval: 10
-                            max: 100
-                            min: 50
+                        - facet: service
+                          limit: 20
                           sort:
-                            aggregation: count
-                            order: asc
+                            aggregation: pc90
+                            metric: "@duration"
+                            order: desc
+                            type: measure
                       options:
                         timezone: GMT
                     type: aggregate_request
@@ -247816,6 +247844,8 @@ paths:
       description: |-
         Retrieve a full APM trace by its trace ID, including every span in the trace.
         Traces are returned from live storage when available and fall back to longer-term storage.
+        A `400 Bad Request` response means the trace ID is malformed. A `404 Not Found` response means
+        no trace with this ID is available, such as when the trace is outside the retention period.
         This endpoint is rate limited to `60` requests per minute per organization.
       operationId: GetTraceByID
       parameters:
@@ -247866,6 +247896,12 @@ paths:
               schema:
                 $ref: "#/components/schemas/TraceResponse"
           description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Bad Request
         "403":
           content:
             application/json:

src/datadog_api_client/v2/api/apm_trace_api.py

@@ -37,6 +37,7 @@ def __init__(self, api_client=None):
             params_map={
                 "trace_id": {
                     "required": True,
+                    "validation": {},
                     "openapi_types": (str,),
                     "attribute": "trace_id",
                     "location": "path",
@@ -101,6 +102,7 @@ def __init__(self, api_client=None):
             params_map={
                 "trace_id": {
                     "required": True,
+                    "validation": {},
                     "openapi_types": (str,),
                     "attribute": "trace_id",
                     "location": "path",
@@ -135,10 +137,16 @@ def get_pruned_trace_by_id(
         Retrieve a pruned, hierarchical view of an APM trace by its trace ID.
         The trace is summarized as a tree of spans rooted at the trace root and reduced in size
         to keep rendering large traces in the UI practical.
+        A ``400 Bad Request`` response means the trace ID is malformed. A ``404 Not Found`` response means
+        no trace with this ID is available, such as when the trace is outside the retention period.
         This endpoint is rate limited to ``60`` requests per minute per organization.
 
-        :param trace_id: The trace ID. Accepts either a 32-character hexadecimal string (128-bit trace ID)
-            or a decimal string of up to 39 digits.
+        :param trace_id: The trace ID. Accepts either a hexadecimal string of up to 32 characters (128-bit trace ID)
+            or a decimal string of up to 39 digits. Hexadecimal IDs are case-insensitive, and shorter
+            values are left-padded with zeros.
+            Use the ``trace_id`` attribute of a span returned by the Search spans or Get a list of spans endpoints.
+            Values in any other format, such as UUIDs, return ``400 Bad Request``. A well-formed ID with
+            no matching trace returns ``404 Not Found``.
         :type trace_id: str
         :param expand_span_id: Span ID to expand and preserve in the pruned tree even when its branch would
             normally be summarized.
@@ -198,10 +206,16 @@ def get_trace_by_id(
 
         Retrieve a full APM trace by its trace ID, including every span in the trace.
         Traces are returned from live storage when available and fall back to longer-term storage.
+        A ``400 Bad Request`` response means the trace ID is malformed. A ``404 Not Found`` response means
+        no trace with this ID is available, such as when the trace is outside the retention period.
         This endpoint is rate limited to ``60`` requests per minute per organization.
 
-        :param trace_id: The trace ID. Accepts either a 32-character hexadecimal string (128-bit trace ID)
-            or a decimal string of up to 39 digits.
+        :param trace_id: The trace ID. Accepts either a hexadecimal string of up to 32 characters (128-bit trace ID)
+            or a decimal string of up to 39 digits. Hexadecimal IDs are case-insensitive, and shorter
+            values are left-padded with zeros.
+            Use the ``trace_id`` attribute of a span returned by the Search spans or Get a list of spans endpoints.
+            Values in any other format, such as UUIDs, return ``400 Bad Request``. A well-formed ID with
+            no matching trace returns ``404 Not Found``.
         :type trace_id: str
         :param include_fields: List of span fields to include in the response. When omitted, every available field is returned.
             Values may be passed as repeated query parameters or as a single comma-separated value.

src/datadog_api_client/v2/api/spans_api.py

@@ -131,6 +131,11 @@ def aggregate_spans(
         The API endpoint to aggregate spans into buckets and compute metrics and timeseries.
         This endpoint is rate limited to ``300`` requests per hour.
 
+        A request can generate at most 10,000 groups across all ``group_by`` entries, or 400,000 groups
+        including time buckets when a ``timeseries`` compute is used. Set ``limit`` on each ``group_by`` entry
+        to stay within these bounds. Requests over long time ranges or with many groups are more resource-intensive
+        and can fail. To reduce load, narrow the time range or lower the ``limit`` on each ``group_by`` entry.
+
         :type body: SpansAggregateRequest
         :rtype: SpansAggregateResponse
         """

src/datadog_api_client/v2/model/spans_aggregate_sort.py

@@ -49,7 +49,9 @@ def __init__(
         **kwargs,
     ):
         """
-        A sort rule.
+        A sort rule. With ``type: alphabetical`` (the default), buckets are sorted by facet value
+        and only ``order`` is allowed. With ``type: measure`` , buckets are sorted by a computed value:
+        set ``aggregation`` , and set ``metric`` unless the aggregation is ``count``.
 
         :param aggregation: An aggregation function.
         :type aggregation: SpansAggregationFunction, optional

src/datadog_api_client/v2/model/spans_compute.py

@@ -48,6 +48,8 @@ def __init__(
     ):
         """
         A compute rule to compute metrics or timeseries.
+        All computes in a request must have the same ``type`` , and ``timeseries`` computes must use the same ``interval``.
+        To get both totals and timeseries, send separate requests.
 
         :param aggregation: An aggregation function.
         :type aggregation: SpansAggregationFunction

src/datadog_api_client/v2/model/spans_group_by.py

@@ -67,12 +67,18 @@ def __init__(
         :type histogram: SpansGroupByHistogram, optional
 
         :param limit: The maximum buckets to return for this group by.
+            A request can generate at most 10,000 groups. Nested ``group_by`` entries multiply, so the
+            product of their limits must stay within that bound. For example, two entries with a limit of 100 each
+            produce up to 10,000 groups. With a ``timeseries`` compute, the number of groups multiplied by
+            the number of time buckets must not exceed 400,000.
         :type limit: int, optional
 
         :param missing: The value to use for spans that don't have the facet used to group by.
         :type missing: SpansGroupByMissing, optional
 
-        :param sort: A sort rule.
+        :param sort: A sort rule. With ``type: alphabetical`` (the default), buckets are sorted by facet value
+            and only ``order`` is allowed. With ``type: measure`` , buckets are sorted by a computed value:
+            set ``aggregation`` , and set ``metric`` unless the aggregation is ``count``.
         :type sort: SpansAggregateSort, optional
 
         :param total: A resulting object to put the given computes in over all the matching records.

tests/v2/features/apm_trace.feature

@@ -7,6 +7,14 @@ Feature: APM Trace
     And a valid "appKeyAuth" key in the system
     And an instance of "APMTrace" API
 
+  @generated @skip @team:ddoghq/apm-reliability
+  Scenario: Get a pruned trace by ID returns "Bad Request" response
+    Given operation "GetPrunedTraceByID" enabled
+    And new "GetPrunedTraceByID" request
+    And request contains "trace_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 400 Bad Request
+
   @generated @skip @team:ddoghq/apm-reliability
   Scenario: Get a pruned trace by ID returns "Not Found" response
     Given operation "GetPrunedTraceByID" enabled
@@ -23,6 +31,14 @@ Feature: APM Trace
     When the request is sent
     Then the response status is 200 OK
 
+  @generated @skip @team:ddoghq/apm-reliability
+  Scenario: Get a trace by ID returns "Bad Request" response
+    Given operation "GetTraceByID" enabled
+    And new "GetTraceByID" request
+    And request contains "trace_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 400 Bad Request
+
   @generated @skip @team:ddoghq/apm-reliability
   Scenario: Get a trace by ID returns "Not Found" response
     Given operation "GetTraceByID" enabled