Document RUM-based metrics API behavior and constraints

src/datadog_api_client/v2/api/rum_metrics_api.py

@@ -138,7 +138,12 @@ def create_rum_metric(
         """Create a RUM-based metric.
 
         Create a metric based on your organization's RUM data.
-        Returns the RUM-based metric object from the request body when the request is successful.
+        The metric name is set in ``data.id`` , is unique within your organization, and cannot be changed after creation.
+        The ``event_type`` , ``compute`` , and ``uniqueness`` settings cannot be changed after creation either. Only ``filter`` , ``group_by`` , and ``compute.include_percentiles`` can be changed with ``UpdateRumMetric``.
+        ``uniqueness`` is required when ``event_type`` is ``session`` or ``view`` , and must be omitted for any other event type.
+        When ``aggregation_type`` is ``distribution`` , ``include_percentiles`` is required. When it is ``count`` , ``include_percentiles`` and ``path`` must be omitted.
+        Returns the created RUM-based metric when the request is successful.
+        The request returns a ``409 Conflict`` error if a metric with the same name already exists.
 
         :param body: The definition of the new RUM-based metric.
         :type body: RumMetricCreateRequest
@@ -156,8 +161,9 @@ def delete_rum_metric(
         """Delete a RUM-based metric.
 
         Delete a specific RUM-based metric from your organization.
+        Metric data that was already generated is not deleted. Deleting a metric cannot be undone.
 
-        :param metric_id: The name of the RUM-based metric.
+        :param metric_id: The name of the RUM-based metric, as returned in ``data.id`` by ``ListRumMetrics``.
         :type metric_id: str
         :rtype: None
         """
@@ -173,8 +179,9 @@ def get_rum_metric(
         """Get a RUM-based metric.
 
         Get a specific RUM-based metric from your organization.
+        The ``metric_id`` is the metric name returned in ``data.id`` by ``ListRumMetrics`` and ``CreateRumMetric``.
 
-        :param metric_id: The name of the RUM-based metric.
+        :param metric_id: The name of the RUM-based metric, as returned in ``data.id`` by ``ListRumMetrics``.
         :type metric_id: str
         :rtype: RumMetricResponse
         """
@@ -188,7 +195,10 @@ def list_rum_metrics(
     ) -> RumMetricsResponse:
         """Get all RUM-based metrics.
 
-        Get the list of configured RUM-based metrics with their definitions.
+        Get the list of all RUM-based metrics configured for your organization, with their definitions.
+        The list is not paginated.
+        Metrics whose stored definition cannot be converted to the RUM format are omitted from the list.
+        To retrieve a single metric, use ``GetRumMetric``.
 
         :rtype: RumMetricsResponse
         """
@@ -203,9 +213,13 @@ def update_rum_metric(
         """Update a RUM-based metric.
 
         Update a specific RUM-based metric from your organization.
-        Returns the RUM-based metric object from the request body when the request is successful.
+        Only ``filter`` , ``group_by`` , and ``compute.include_percentiles`` can be updated. ``event_type`` , ``uniqueness`` , ``compute.aggregation_type`` , ``compute.path`` , and the metric name are immutable. To change them, delete the metric and create a new one.
+        Omitted attributes keep their current value. When provided, ``filter.query`` replaces the whole filter query (an empty query is ignored) and ``group_by`` replaces the whole list of group by rules.
+        ``data.id`` is required and must match the ``metric_id`` path parameter, otherwise the request returns a ``409 Conflict`` error.
+        The request also returns a ``409 Conflict`` error when ``compute.include_percentiles`` is set on a metric whose ``aggregation_type`` is not ``distribution``.
+        Returns the updated RUM-based metric when the request is successful.
 
-        :param metric_id: The name of the RUM-based metric.
+        :param metric_id: The name of the RUM-based metric, as returned in ``data.id`` by ``ListRumMetrics``.
         :type metric_id: str
         :param body: New definition of the RUM-based metric.
         :type body: RumMetricUpdateRequest

src/datadog_api_client/v2/model/rum_metric_compute.py

@@ -42,17 +42,18 @@ def __init__(
         **kwargs,
     ):
         """
-        The compute rule to compute the RUM-based metric.
+        The compute rule to compute the RUM-based metric. It is set at creation and only ``include_percentiles`` can be updated afterwards.
 
         :param aggregation_type: The type of aggregation to use.
+            ``count`` counts the matching events. ``distribution`` aggregates the values found at ``path``.
         :type aggregation_type: RumMetricComputeAggregationType
 
-        :param include_percentiles: Toggle to include or exclude percentile aggregations for distribution metrics.
-            Only present when ``aggregation_type`` is ``distribution``.
+        :param include_percentiles: Toggle to include or exclude percentile aggregations (p50, p75, p90, p95, p99) for distribution metrics.
+            Required when ``aggregation_type`` is ``distribution`` , and must be omitted otherwise.
         :type include_percentiles: bool, optional
 
-        :param path: The path to the value the RUM-based metric will aggregate on.
-            Only present when ``aggregation_type`` is ``distribution``.
+        :param path: The path of the numeric RUM event attribute the metric aggregates on.
+            Only valid when ``aggregation_type`` is ``distribution``.
         :type path: str, optional
         """
         if include_percentiles is not unset:

src/datadog_api_client/v2/model/rum_metric_compute_aggregation_type.py

@@ -15,6 +15,7 @@
 class RumMetricComputeAggregationType(ModelSimple):
     """
     The type of aggregation to use.
+        `count` counts the matching events. `distribution` aggregates the values found at `path`.
 
     :param value: Must be one of ["count", "distribution"].
     :type value: str

src/datadog_api_client/v2/model/rum_metric_create_attributes.py

@@ -58,19 +58,20 @@ def __init__(
         """
         The object describing the Datadog RUM-based metric to create.
 
-        :param compute: The compute rule to compute the RUM-based metric.
+        :param compute: The compute rule to compute the RUM-based metric. It is set at creation and only ``include_percentiles`` can be updated afterwards.
         :type compute: RumMetricCompute
 
-        :param event_type: The type of RUM events to filter on.
+        :param event_type: The type of RUM events the metric is generated from. It is set at creation and cannot be changed.
         :type event_type: RumMetricEventType
 
-        :param filter: The RUM-based metric filter. Events matching this filter will be aggregated in this metric.
+        :param filter: The RUM-based metric filter. Events matching this filter will be aggregated in this metric. The ``event_type`` filter is added automatically.
         :type filter: RumMetricFilter, optional
 
-        :param group_by: The rules for the group by.
+        :param group_by: The rules to group the metric by. Each rule creates a tag on the generated metric. If omitted, the metric is not grouped.
         :type group_by: [RumMetricGroupBy], optional
 
-        :param uniqueness: The rule to count updatable events. Is only set if ``event_type`` is ``sessions`` or ``views``.
+        :param uniqueness: The rule to count updatable events.
+            Required when ``event_type`` is ``session`` or ``view`` , and must be omitted for other event types. It cannot be changed after creation.
         :type uniqueness: RumMetricUniqueness, optional
         """
         if filter is not unset:

src/datadog_api_client/v2/model/rum_metric_create_data.py

@@ -17,6 +17,12 @@
 
 
 class RumMetricCreateData(ModelNormal):
+    validations = {
+        "id": {
+            "max_length": 200,
+        },
+    }
+
     @cached_property
     def openapi_types(_):
         from datadog_api_client.v2.model.rum_metric_create_attributes import RumMetricCreateAttributes
@@ -42,9 +48,11 @@ def __init__(self_, attributes: RumMetricCreateAttributes, id: str, type: RumMet
         :type attributes: RumMetricCreateAttributes
 
         :param id: The name of the RUM-based metric.
+            On creation, it must be 1 to 200 characters long, contain only ASCII letters, digits, underscores, and periods, start with a letter, and not start with ``rum.measure`` or ``rum.investigate``.
+            It cannot be changed after creation.
         :type id: str
 
-        :param type: The type of the resource. The value should always be rum_metrics.
+        :param type: The type of the resource. The value must be ``rum_metrics``.
         :type type: RumMetricType
         """
         super().__init__(kwargs)

src/datadog_api_client/v2/model/rum_metric_event_type.py

@@ -14,7 +14,7 @@
 
 class RumMetricEventType(ModelSimple):
     """
-    The type of RUM events to filter on.
+    The type of RUM events the metric is generated from. It is set at creation and cannot be changed.
 
     :param value: Must be one of ["session", "view", "action", "error", "resource", "long_task", "vital"].
     :type value: str

src/datadog_api_client/v2/model/rum_metric_filter.py

@@ -23,9 +23,12 @@ def openapi_types(_):
 
     def __init__(self_, **kwargs):
         """
-        The RUM-based metric filter. Events matching this filter will be aggregated in this metric.
+        The RUM-based metric filter. Events matching this filter will be aggregated in this metric. The ``event_type`` filter is added automatically.
 
-        :param query: The search query - following the RUM search syntax.
+        :param query: The search query, following the `RUM search syntax <https://docs.datadoghq.com/real_user_monitoring/explorer/search_syntax/>`_.
+            Do not include a ``@type`` filter, it is derived from ``event_type``.
+            It must not contain invisible or control characters such as non-breaking or zero-width spaces.
+            When updating a metric, an empty query leaves the filter unchanged.
         :type query: str
         """
         super().__init__(kwargs)

src/datadog_api_client/v2/model/rum_metric_group_by.py

@@ -14,6 +14,12 @@
 
 
 class RumMetricGroupBy(ModelNormal):
+    validations = {
+        "tag_name": {
+            "max_length": 200,
+        },
+    }
+
     @cached_property
     def openapi_types(_):
         return {
@@ -30,10 +36,11 @@ def __init__(self_, path: str, tag_name: Union[str, UnsetType] = unset, **kwargs
         """
         A group by rule.
 
-        :param path: The path to the value the RUM-based metric will be aggregated over.
+        :param path: The path of the RUM event attribute to group the metric by.
         :type path: str
 
-        :param tag_name: Eventual name of the tag that gets created. By default, ``path`` is used as the tag name.
+        :param tag_name: Name of the tag that gets created on the metric. By default, ``path`` is used as the tag name.
+            It must be at most 200 characters long, start with a letter, and contain only lowercase letters, digits, underscores, hyphens, colons, periods, and slashes.
         :type tag_name: str, optional
         """
         if tag_name is not unset:

src/datadog_api_client/v2/model/rum_metric_response_attributes.py

@@ -58,19 +58,19 @@ def __init__(
         """
         The object describing a Datadog RUM-based metric.
 
-        :param compute: The compute rule to compute the RUM-based metric.
+        :param compute: The compute rule of the RUM-based metric.
         :type compute: RumMetricResponseCompute, optional
 
-        :param event_type: The type of RUM events to filter on.
+        :param event_type: The type of RUM events the metric is generated from. It is set at creation and cannot be changed.
         :type event_type: RumMetricEventType, optional
 
-        :param filter: The RUM-based metric filter. RUM events matching this filter will be aggregated in this metric.
+        :param filter: The RUM-based metric filter. RUM events matching this filter are aggregated in this metric. Omitted if the metric only filters on the event type.
         :type filter: RumMetricResponseFilter, optional
 
-        :param group_by: The rules for the group by.
+        :param group_by: The rules the metric is grouped by. Omitted if the metric is not grouped.
         :type group_by: [RumMetricResponseGroupBy], optional
 
-        :param uniqueness: The rule to count updatable events. Is only set if ``event_type`` is ``session`` or ``view``.
+        :param uniqueness: The rule to count updatable events. Only present if ``event_type`` is ``session`` or ``view`` , and absent on older metrics created before this setting existed.
         :type uniqueness: RumMetricResponseUniqueness, optional
         """
         if compute is not unset:

src/datadog_api_client/v2/model/rum_metric_response_compute.py

@@ -42,16 +42,17 @@ def __init__(
         **kwargs,
     ):
         """
-        The compute rule to compute the RUM-based metric.
+        The compute rule of the RUM-based metric.
 
         :param aggregation_type: The type of aggregation to use.
+            ``count`` counts the matching events. ``distribution`` aggregates the values found at ``path``.
         :type aggregation_type: RumMetricComputeAggregationType, optional
 
-        :param include_percentiles: Toggle to include or exclude percentile aggregations for distribution metrics.
-            Only present when ``aggregation_type`` is ``distribution``.
+        :param include_percentiles: Toggle to include or exclude percentile aggregations (p50, p75, p90, p95, p99) for distribution metrics.
+            Required when ``aggregation_type`` is ``distribution`` , and must be omitted otherwise.
         :type include_percentiles: bool, optional
 
-        :param path: The path to the value the RUM-based metric will aggregate on.
+        :param path: The path of the numeric RUM event attribute the metric aggregates on.
             Only present when ``aggregation_type`` is ``distribution``.
         :type path: str, optional
         """

src/datadog_api_client/v2/model/rum_metric_response_data.py

@@ -19,6 +19,12 @@
 
 
 class RumMetricResponseData(ModelNormal):
+    validations = {
+        "id": {
+            "max_length": 200,
+        },
+    }
+
     @cached_property
     def openapi_types(_):
         from datadog_api_client.v2.model.rum_metric_response_attributes import RumMetricResponseAttributes
@@ -50,9 +56,11 @@ def __init__(
         :type attributes: RumMetricResponseAttributes, optional
 
         :param id: The name of the RUM-based metric.
+            On creation, it must be 1 to 200 characters long, contain only ASCII letters, digits, underscores, and periods, start with a letter, and not start with ``rum.measure`` or ``rum.investigate``.
+            It cannot be changed after creation.
         :type id: str, optional
 
-        :param type: The type of the resource. The value should always be rum_metrics.
+        :param type: The type of the resource. The value must be ``rum_metrics``.
         :type type: RumMetricType, optional
         """
         if attributes is not unset:

src/datadog_api_client/v2/model/rum_metric_response_filter.py

@@ -26,9 +26,9 @@ def openapi_types(_):
 
     def __init__(self_, query: Union[str, UnsetType] = unset, **kwargs):
         """
-        The RUM-based metric filter. RUM events matching this filter will be aggregated in this metric.
+        The RUM-based metric filter. RUM events matching this filter are aggregated in this metric. Omitted if the metric only filters on the event type.
 
-        :param query: The search query - following the RUM search syntax.
+        :param query: The search query, following the `RUM search syntax <https://docs.datadoghq.com/real_user_monitoring/explorer/search_syntax/>`_. It does not include the event type filter.
         :type query: str, optional
         """
         if query is not unset:

src/datadog_api_client/v2/model/rum_metric_response_group_by.py

@@ -30,10 +30,10 @@ def __init__(self_, path: Union[str, UnsetType] = unset, tag_name: Union[str, Un
         """
         A group by rule.
 
-        :param path: The path to the value the RUM-based metric will be aggregated over.
+        :param path: The path of the RUM event attribute the metric is grouped by.
         :type path: str, optional
 
-        :param tag_name: Eventual name of the tag that gets created. By default, ``path`` is used as the tag name.
+        :param tag_name: Name of the tag created on the metric. By default, ``path`` is used as the tag name.
         :type tag_name: str, optional
         """
         if path is not unset:

src/datadog_api_client/v2/model/rum_metric_response_uniqueness.py

@@ -32,9 +32,9 @@ def openapi_types(_):
 
     def __init__(self_, when: Union[RumMetricUniquenessWhen, UnsetType] = unset, **kwargs):
         """
-        The rule to count updatable events. Is only set if ``event_type`` is ``session`` or ``view``.
+        The rule to count updatable events. Only present if ``event_type`` is ``session`` or ``view`` , and absent on older metrics created before this setting existed.
 
-        :param when: When to count updatable events. ``match`` when the event is first seen, or ``end`` when the event is complete.
+        :param when: When to count updatable events. ``match`` when the event is first seen, or ``end`` when the event is complete. Sessions and views are updated over time, each one is counted once.
         :type when: RumMetricUniquenessWhen, optional
         """
         if when is not unset:

src/datadog_api_client/v2/model/rum_metric_type.py

@@ -14,7 +14,7 @@
 
 class RumMetricType(ModelSimple):
     """
-    The type of the resource. The value should always be rum_metrics.
+    The type of the resource. The value must be `rum_metrics`.
 
     :param value: If omitted defaults to "rum_metrics". Must be one of ["rum_metrics"].
     :type value: str

src/datadog_api_client/v2/model/rum_metric_uniqueness.py

@@ -30,9 +30,10 @@ def openapi_types(_):
 
     def __init__(self_, when: RumMetricUniquenessWhen, **kwargs):
         """
-        The rule to count updatable events. Is only set if ``event_type`` is ``sessions`` or ``views``.
+        The rule to count updatable events.
+        Required when ``event_type`` is ``session`` or ``view`` , and must be omitted for other event types. It cannot be changed after creation.
 
-        :param when: When to count updatable events. ``match`` when the event is first seen, or ``end`` when the event is complete.
+        :param when: When to count updatable events. ``match`` when the event is first seen, or ``end`` when the event is complete. Sessions and views are updated over time, each one is counted once.
         :type when: RumMetricUniquenessWhen
         """
         super().__init__(kwargs)

src/datadog_api_client/v2/model/rum_metric_uniqueness_when.py

@@ -14,7 +14,7 @@
 
 class RumMetricUniquenessWhen(ModelSimple):
     """
-    When to count updatable events. `match` when the event is first seen, or `end` when the event is complete.
+    When to count updatable events. `match` when the event is first seen, or `end` when the event is complete. Sessions and views are updated over time, each one is counted once.
 
     :param value: Must be one of ["match", "end"].
     :type value: str

src/datadog_api_client/v2/model/rum_metric_update_attributes.py

@@ -46,15 +46,15 @@ def __init__(
         **kwargs,
     ):
         """
-        The RUM-based metric properties that will be updated.
+        The RUM-based metric properties that will be updated. Omitted properties keep their current value.
 
-        :param compute: The compute rule to compute the RUM-based metric.
+        :param compute: The compute rule properties that can be updated. Only valid for metrics whose ``aggregation_type`` is ``distribution``.
         :type compute: RumMetricUpdateCompute, optional
 
-        :param filter: The RUM-based metric filter. Events matching this filter will be aggregated in this metric.
+        :param filter: The RUM-based metric filter. Events matching this filter will be aggregated in this metric. The ``event_type`` filter is added automatically.
         :type filter: RumMetricFilter, optional
 
-        :param group_by: The rules for the group by.
+        :param group_by: The rules to group the metric by. When provided, replaces all the existing group by rules.
         :type group_by: [RumMetricGroupBy], optional
         """
         if compute is not unset: