Document Processes API time window, retention, and filter semantics

.generator/schemas/v2/openapi.yaml

@@ -96421,7 +96421,9 @@ components:
       x-enum-varnames:
         - PROCESS
     ProcessScalarQuery:
-      description: A query for host-level process metrics such as CPU and memory usage.
+      description: |-
+        Per-process metrics from Live Processes. Queries without `aggregator` fail. To scope to one process,
+        set `tag_filters` to its `identifying_tags` from `GET /api/v2/processes`.
       properties:
         aggregator:
           $ref: "#/components/schemas/MetricsAggregator"
@@ -96433,11 +96435,15 @@ components:
           description: Whether CPU metrics should be normalized by core count.
           type: boolean
         limit:
-          description: Maximum number of results to return.
+          description: |-
+            Maximum number of processes or groups to return. Large values can fail with an `Unprocessable
+            Content` error. If so, retry with a smaller limit.
           format: int64
           type: integer
         metric:
-          description: The process metric to query.
+          description: |-
+            The process metric to query, such as `process.stat.cpu.total_pct`, `process.stat.memory.rss`, or
+            `process.stat.memory.vms`.
           example: process.stat.cpu.total_pct
           type: string
         name:
@@ -96447,7 +96453,9 @@ components:
         sort:
           $ref: "#/components/schemas/QuerySortOrder"
         tag_filters:
-          description: Tag filters to narrow down processes.
+          description: |-
+            Tags to narrow down processes. To scope to one process, use its `identifying_tags` from
+            `GET /api/v2/processes`, for example `host:web-01` and `pid:1234`.
           items:
             description: A tag filter value.
             example: "env:prod"
@@ -96559,7 +96567,9 @@ components:
       x-enum-varnames:
         - PROCESS
     ProcessTimeseriesQuery:
-      description: A query for host-level process metrics such as CPU and memory usage.
+      description: |-
+        Per-process metrics from Live Processes over time, such as CPU and memory usage. To scope to one
+        process, set `tag_filters` to its `identifying_tags` from `GET /api/v2/processes`.
       properties:
         cross_org_uuids:
           $ref: "#/components/schemas/CrossOrgUuids"
@@ -96569,11 +96579,15 @@ components:
           description: Whether CPU metrics should be normalized by core count.
           type: boolean
         limit:
-          description: Maximum number of results to return.
+          description: |-
+            Maximum number of processes or groups to return. Large values can fail with an `Unprocessable
+            Content` error. If so, retry with a smaller limit.
           format: int64
           type: integer
         metric:
-          description: The process metric to query.
+          description: |-
+            The process metric to query, such as `process.stat.cpu.total_pct`, `process.stat.memory.rss`, or
+            `process.stat.memory.vms`.
           example: process.stat.cpu.total_pct
           type: string
         name:
@@ -96583,7 +96597,9 @@ components:
         sort:
           $ref: "#/components/schemas/QuerySortOrder"
         tag_filters:
-          description: Tag filters to narrow down processes.
+          description: |-
+            Tags to narrow down processes. To scope to one process, use its `identifying_tags` from
+            `GET /api/v2/processes`, for example `host:web-01` and `pid:1234`.
           items:
             description: A tag filter value.
             example: "env:prod"
@@ -210510,36 +210526,48 @@ paths:
           - dashboards_write
   /api/v2/processes:
     get:
-      description: Get all processes for your organization.
+      description: |-
+        Get processes collected by Live Processes for your organization. One request covers a window of
+        at most 1 hour that starts within the past 36 hours. To cover a longer period, make one request
+        per hour. Older data is not available from this endpoint.
+
+        When a process includes `identifying_tags`, pass them as `tag_filters` in a `process` data source
+        query to `/api/v2/query/scalar` or `/api/v2/query/timeseries` to get CPU or memory metrics for that
+        one process. If absent, don't substitute an empty filter, which would query all processes.
       operationId: ListProcesses
       parameters:
-        - description: String to search processes by.
+        - description: |-
+            Free-text search over process fields such as the executable and user. When it contains several
+            words, a process must match all of them. Use `tags` for exact values such as host.
           in: query
           name: search
           required: false
           schema:
             type: string
-        - description: Comma-separated list of tags to filter processes by.
+        - description: |-
+            Comma-separated `key:value` tags. A process must match every tag. Wildcards, negation
+            (`-key:value`), spaces, and `IN (...)` are not supported. To cover several hosts, make one
+            request per host.
           example: account:prod,user:admin
           in: query
           name: tags
           required: false
           schema:
             type: string
         - description: |-
-            Unix timestamp (number of seconds since epoch) of the start of the query window.
-            If not provided, the start of the query window will be 15 minutes before the `to` timestamp. If neither
-            `from` nor `to` are provided, the query window will be `[now - 15m, now]`.
+            Start of the query window, in Unix seconds. Must be within the past 36 hours and at most 1 hour
+            before `to`. If not provided, the start of the query window is 15 minutes before the `to` timestamp.
+            If neither `from` nor `to` is provided, the query window is `[now - 15m, now]`.
           in: query
           name: from
           required: false
           schema:
             format: int64
             type: integer
         - description: |-
-            Unix timestamp (number of seconds since epoch) of the end of the query window.
-            If not provided, the end of the query window will be 15 minutes after the `from` timestamp. If neither
-            `from` nor `to` are provided, the query window will be `[now - 15m, now]`.
+            End of the query window, in Unix seconds. Must be at most 1 hour after `from`. If not provided, the
+            end of the query window is 15 minutes after the `from` timestamp. If neither `from` nor `to` is
+            provided, the query window is `[now - 15m, now]`.
           in: query
           name: to
           required: false

src/datadog_api_client/v2/api/processes_api.py

@@ -91,19 +91,28 @@ def list_processes(
     ) -> ProcessSummariesResponse:
         """Get all processes.
 
-        Get all processes for your organization.
+        Get processes collected by Live Processes for your organization. One request covers a window of
+        at most 1 hour that starts within the past 36 hours. To cover a longer period, make one request
+        per hour. Older data is not available from this endpoint.
 
-        :param search: String to search processes by.
+        When a process includes ``identifying_tags`` , pass them as ``tag_filters`` in a ``process`` data source
+        query to ``/api/v2/query/scalar`` or ``/api/v2/query/timeseries`` to get CPU or memory metrics for that
+        one process. If absent, don't substitute an empty filter, which would query all processes.
+
+        :param search: Free-text search over process fields such as the executable and user. When it contains several
+            words, a process must match all of them. Use ``tags`` for exact values such as host.
         :type search: str, optional
-        :param tags: Comma-separated list of tags to filter processes by.
+        :param tags: Comma-separated ``key:value`` tags. A process must match every tag. Wildcards, negation
+            ( ``-key:value`` ), spaces, and ``IN (...)`` are not supported. To cover several hosts, make one
+            request per host.
         :type tags: str, optional
-        :param _from: Unix timestamp (number of seconds since epoch) of the start of the query window.
-            If not provided, the start of the query window will be 15 minutes before the ``to`` timestamp. If neither
-            ``from`` nor ``to`` are provided, the query window will be ``[now - 15m, now]``.
+        :param _from: Start of the query window, in Unix seconds. Must be within the past 36 hours and at most 1 hour
+            before ``to``. If not provided, the start of the query window is 15 minutes before the ``to`` timestamp.
+            If neither ``from`` nor ``to`` is provided, the query window is ``[now - 15m, now]``.
         :type _from: int, optional
-        :param to: Unix timestamp (number of seconds since epoch) of the end of the query window.
-            If not provided, the end of the query window will be 15 minutes after the ``from`` timestamp. If neither
-            ``from`` nor ``to`` are provided, the query window will be ``[now - 15m, now]``.
+        :param to: End of the query window, in Unix seconds. Must be at most 1 hour after ``from``. If not provided, the
+            end of the query window is 15 minutes after the ``from`` timestamp. If neither ``from`` nor ``to`` is
+            provided, the query window is ``[now - 15m, now]``.
         :type to: int, optional
         :param page_limit: Maximum number of results returned.
         :type page_limit: int, optional
@@ -147,17 +156,20 @@ def list_processes_with_pagination(
 
         Provide a paginated version of :meth:`list_processes`, returning all items.
 
-        :param search: String to search processes by.
+        :param search: Free-text search over process fields such as the executable and user. When it contains several
+            words, a process must match all of them. Use ``tags`` for exact values such as host.
         :type search: str, optional
-        :param tags: Comma-separated list of tags to filter processes by.
+        :param tags: Comma-separated ``key:value`` tags. A process must match every tag. Wildcards, negation
+            ( ``-key:value`` ), spaces, and ``IN (...)`` are not supported. To cover several hosts, make one
+            request per host.
         :type tags: str, optional
-        :param _from: Unix timestamp (number of seconds since epoch) of the start of the query window.
-            If not provided, the start of the query window will be 15 minutes before the ``to`` timestamp. If neither
-            ``from`` nor ``to`` are provided, the query window will be ``[now - 15m, now]``.
+        :param _from: Start of the query window, in Unix seconds. Must be within the past 36 hours and at most 1 hour
+            before ``to``. If not provided, the start of the query window is 15 minutes before the ``to`` timestamp.
+            If neither ``from`` nor ``to`` is provided, the query window is ``[now - 15m, now]``.
         :type _from: int, optional
-        :param to: Unix timestamp (number of seconds since epoch) of the end of the query window.
-            If not provided, the end of the query window will be 15 minutes after the ``from`` timestamp. If neither
-            ``from`` nor ``to`` are provided, the query window will be ``[now - 15m, now]``.
+        :param to: End of the query window, in Unix seconds. Must be at most 1 hour after ``from``. If not provided, the
+            end of the query window is 15 minutes after the ``from`` timestamp. If neither ``from`` nor ``to`` is
+            provided, the query window is ``[now - 15m, now]``.
         :type to: int, optional
         :param page_limit: Maximum number of results returned.
         :type page_limit: int, optional

src/datadog_api_client/v2/model/process_scalar_query.py

@@ -73,7 +73,8 @@ def __init__(
         **kwargs,
     ):
         """
-        A query for host-level process metrics such as CPU and memory usage.
+        Per-process metrics from Live Processes. Queries without ``aggregator`` fail. To scope to one process,
+        set ``tag_filters`` to its ``identifying_tags`` from ``GET /api/v2/processes``.
 
         :param aggregator: The type of aggregation that can be performed on metrics-based queries.
         :type aggregator: MetricsAggregator, optional
@@ -87,10 +88,12 @@ def __init__(
         :param is_normalized_cpu: Whether CPU metrics should be normalized by core count.
         :type is_normalized_cpu: bool, optional
 
-        :param limit: Maximum number of results to return.
+        :param limit: Maximum number of processes or groups to return. Large values can fail with an ``Unprocessable
+            Content`` error. If so, retry with a smaller limit.
         :type limit: int, optional
 
-        :param metric: The process metric to query.
+        :param metric: The process metric to query, such as ``process.stat.cpu.total_pct`` , ``process.stat.memory.rss`` , or
+            ``process.stat.memory.vms``.
         :type metric: str
 
         :param name: The variable name for use in formulas.
@@ -99,7 +102,8 @@ def __init__(
         :param sort: Direction of sort.
         :type sort: QuerySortOrder, optional
 
-        :param tag_filters: Tag filters to narrow down processes.
+        :param tag_filters: Tags to narrow down processes. To scope to one process, use its ``identifying_tags`` from
+            ``GET /api/v2/processes`` , for example ``host:web-01`` and ``pid:1234``.
         :type tag_filters: [str], optional
 
         :param text_filter: A full-text search filter to match process names or commands.

src/datadog_api_client/v2/model/process_timeseries_query.py

@@ -68,7 +68,8 @@ def __init__(
         **kwargs,
     ):
         """
-        A query for host-level process metrics such as CPU and memory usage.
+        Per-process metrics from Live Processes over time, such as CPU and memory usage. To scope to one
+        process, set ``tag_filters`` to its ``identifying_tags`` from ``GET /api/v2/processes``.
 
         :param cross_org_uuids: Organization UUIDs to query when using `cross-organization visibility </account_management/org_settings/cross_org_visibility/>`_. Limited to one organization UUID.
         :type cross_org_uuids: [str], optional
@@ -79,10 +80,12 @@ def __init__(
         :param is_normalized_cpu: Whether CPU metrics should be normalized by core count.
         :type is_normalized_cpu: bool, optional
 
-        :param limit: Maximum number of results to return.
+        :param limit: Maximum number of processes or groups to return. Large values can fail with an ``Unprocessable
+            Content`` error. If so, retry with a smaller limit.
         :type limit: int, optional
 
-        :param metric: The process metric to query.
+        :param metric: The process metric to query, such as ``process.stat.cpu.total_pct`` , ``process.stat.memory.rss`` , or
+            ``process.stat.memory.vms``.
         :type metric: str
 
         :param name: The variable name for use in formulas.
@@ -91,7 +94,8 @@ def __init__(
         :param sort: Direction of sort.
         :type sort: QuerySortOrder, optional
 
-        :param tag_filters: Tag filters to narrow down processes.
+        :param tag_filters: Tags to narrow down processes. To scope to one process, use its ``identifying_tags`` from
+            ``GET /api/v2/processes`` , for example ``host:web-01`` and ``pid:1234``.
         :type tag_filters: [str], optional
 
         :param text_filter: A full-text search filter to match process names or commands.

src/datadog_api_client/v2/model/scalar_query.py

@@ -99,16 +99,19 @@ def __init__(self, **kwargs):
         :param is_normalized_cpu: Whether CPU metrics should be normalized by core count.
         :type is_normalized_cpu: bool, optional
 
-        :param limit: Maximum number of results to return.
+        :param limit: Maximum number of processes or groups to return. Large values can fail with an `Unprocessable
+            Content` error. If so, retry with a smaller limit.
         :type limit: int, optional
 
-        :param metric: The process metric to query.
+        :param metric: The process metric to query, such as `process.stat.cpu.total_pct`, `process.stat.memory.rss`, or
+            `process.stat.memory.vms`.
         :type metric: str
 
         :param sort: Direction of sort.
         :type sort: QuerySortOrder, optional
 
-        :param tag_filters: Tag filters to narrow down processes.
+        :param tag_filters: Tags to narrow down processes. To scope to one process, use its `identifying_tags` from
+            `GET /api/v2/processes`, for example `host:web-01` and `pid:1234`.
         :type tag_filters: [str], optional
 
         :param text_filter: A full-text search filter to match process names or commands.

src/datadog_api_client/v2/model/timeseries_query.py

@@ -96,16 +96,19 @@ def __init__(self, **kwargs):
         :param is_normalized_cpu: Whether CPU metrics should be normalized by core count.
         :type is_normalized_cpu: bool, optional
 
-        :param limit: Maximum number of results to return.
+        :param limit: Maximum number of processes or groups to return. Large values can fail with an `Unprocessable
+            Content` error. If so, retry with a smaller limit.
         :type limit: int, optional
 
-        :param metric: The process metric to query.
+        :param metric: The process metric to query, such as `process.stat.cpu.total_pct`, `process.stat.memory.rss`, or
+            `process.stat.memory.vms`.
         :type metric: str
 
         :param sort: Direction of sort.
         :type sort: QuerySortOrder, optional
 
-        :param tag_filters: Tag filters to narrow down processes.
+        :param tag_filters: Tags to narrow down processes. To scope to one process, use its `identifying_tags` from
+            `GET /api/v2/processes`, for example `host:web-01` and `pid:1234`.
         :type tag_filters: [str], optional
 
         :param text_filter: A full-text search filter to match process names or commands.