Add apm_metrics query support to dashboard OpenAPI spec (#3706)

api-clients-generation-pipeline[bot] · ci.datadog-api-spec · web-flow · commit 629126bf6020 · 2026-03-26T10:18:56.000Z
Co-authored-by: ci.datadog-api-spec &lt;packages@datadoghq.com&gt;
diff --git a/.generator/schemas/v1/openapi.yaml b/.generator/schemas/v1/openapi.yaml
@@ -2709,6 +2709,123 @@ components:
         - service
         - name
       type: object
+    FormulaAndFunctionApmMetricStatName:
+      description: APM metric stat name.
+      enum:
+        - errors
+        - error_rate
+        - errors_per_second
+        - latency_avg
+        - latency_max
+        - latency_p50
+        - latency_p75
+        - latency_p90
+        - latency_p95
+        - latency_p99
+        - latency_p999
+        - latency_distribution
+        - hits
+        - hits_per_second
+        - total_time
+        - apdex
+      example: "hits"
+      type: string
+      x-enum-varnames:
+        - ERRORS
+        - ERROR_RATE
+        - ERRORS_PER_SECOND
+        - LATENCY_AVG
+        - LATENCY_MAX
+        - LATENCY_P50
+        - LATENCY_P75
+        - LATENCY_P90
+        - LATENCY_P95
+        - LATENCY_P99
+        - LATENCY_P999
+        - LATENCY_DISTRIBUTION
+        - HITS
+        - HITS_PER_SECOND
+        - TOTAL_TIME
+        - APDEX
+    FormulaAndFunctionApmMetricsDataSource:
+      description: Data source for APM metrics queries.
+      enum:
+        - apm_metrics
+      example: apm_metrics
+      type: string
+      x-enum-varnames:
+        - APM_METRICS
+    FormulaAndFunctionApmMetricsQueryDefinition:
+      description: A formula and functions APM metrics query.
+      properties:
+        data_source:
+          $ref: "#/components/schemas/FormulaAndFunctionApmMetricsDataSource"
+        group_by:
+          description: Optional fields to group the query results by.
+          items:
+            description: A field to group results by.
+            example: "resource_name"
+            type: string
+          type: array
+        name:
+          description: Name of this query to use in formulas.
+          example: "query_errors"
+          type: string
+        operation_mode:
+          description: Optional operation mode to aggregate across operation names.
+          example: "primary"
+          type: string
+        operation_name:
+          description: Name of operation on service. If not provided, the primary operation name is used.
+          example: "web.request"
+          type: string
+        peer_tags:
+          description: Tags to query for a specific downstream entity (peer.service, peer.db_instance, peer.s3, peer.s3.bucket, etc.).
+          items:
+            example: "peer.service:my-service"
+            type: string
+          type: array
+        query_filter:
+          description: Additional filters for the query using metrics query syntax (e.g., env, primary_tag).
+          example: "env:prod"
+          type: string
+        resource_hash:
+          description: The hash of a specific resource to filter by.
+          example: "abc123"
+          type: string
+        resource_name:
+          description: The full name of a specific resource to filter by.
+          example: "GET /api/v1/users"
+          type: string
+        service:
+          description: APM service name.
+          example: "web-store"
+          type: string
+        span_kind:
+          $ref: "#/components/schemas/FormulaAndFunctionApmMetricsSpanKind"
+        stat:
+          $ref: "#/components/schemas/FormulaAndFunctionApmMetricStatName"
+      required:
+        - data_source
+        - name
+        - stat
+      type: object
+    FormulaAndFunctionApmMetricsSpanKind:
+      description: Describes the relationship between the span, its parents, and its children in a trace.
+      enum:
+        - consumer
+        - server
+        - client
+        - producer
+        - internal
+      example: "server"
+      type: string
+      x-enum-varnames:
+        - CONSUMER
+        - SERVER
+        - CLIENT
+        - PRODUCER
+        - INTERNAL
     FormulaAndFunctionApmResourceStatName:
       description: APM resource stat name.
       enum:
@@ -3138,6 +3255,7 @@ components:
         - $ref: "#/components/schemas/FormulaAndFunctionProcessQueryDefinition"
         - $ref: "#/components/schemas/FormulaAndFunctionApmDependencyStatsQueryDefinition"
         - $ref: "#/components/schemas/FormulaAndFunctionApmResourceStatsQueryDefinition"
+        - $ref: "#/components/schemas/FormulaAndFunctionApmMetricsQueryDefinition"
         - $ref: "#/components/schemas/FormulaAndFunctionSLOQueryDefinition"
         - $ref: "#/components/schemas/FormulaAndFunctionCloudCostQueryDefinition"
     FormulaAndFunctionResponseFormat:
diff --git a/cassettes/v1/Dashboards_1335235736/Create-a-new-dashboard-with-apm-metrics-widget_4218872847/frozen.json b/cassettes/v1/Dashboards_1335235736/Create-a-new-dashboard-with-apm-metrics-widget_4218872847/frozen.json
@@ -0,0 +1 @@
+"2025-02-20T10:00:00.000Z"
diff --git a/cassettes/v1/Dashboards_1335235736/Create-a-new-dashboard-with-apm-metrics-widget_4218872847/recording.har b/cassettes/v1/Dashboards_1335235736/Create-a-new-dashboard-with-apm-metrics-widget_4218872847/recording.har
@@ -0,0 +1,110 @@
+{
+  "log": {
+    "_recordingName": "Dashboards/Create a new dashboard with apm metrics widget",
+    "creator": {
+      "comment": "persister:fs",
+      "name": "Polly.JS",
+      "version": "6.0.5"
+    },
+    "entries": [
+      {
+        "_id": "1cfcf5ccd2e7dff3d4f3b05c53d79057",
+        "_order": 0,
+        "cache": {},
+        "request": {
+          "bodySize": 433,
+          "cookies": [],
+          "headers": [
+            {
+              "_fromType": "array",
+              "name": "accept",
+              "value": "application/json"
+            },
+            {
+              "_fromType": "array",
+              "name": "content-type",
+              "value": "application/json"
+            }
+          ],
+          "headersSize": 560,
+          "httpVersion": "HTTP/1.1",
+          "method": "POST",
+          "postData": {
+            "mimeType": "application/json",
+            "params": [],
+            "text": "{\"layout_type\":\"ordered\",\"title\":\"Test-Create_a_new_dashboard_with_apm_metrics_widget-1740045600\",\"widgets\":[{\"definition\":{\"requests\":[{\"queries\":[{\"data_source\":\"apm_metrics\",\"group_by\":[\"resource_name\"],\"name\":\"query1\",\"query_filter\":\"env:prod\",\"service\":\"web-store\",\"stat\":\"hits\"}],\"response_format\":\"scalar\"}],\"title\":\"\",\"title_align\":\"left\",\"title_size\":\"16\",\"type\":\"query_table\"},\"layout\":{\"height\":4,\"width\":4,\"x\":0,\"y\":0}}]}"
+          },
+          "queryString": [],
+          "url": "https://api.datadoghq.com/api/v1/dashboard"
+        },
+        "response": {
+          "bodySize": 819,
+          "content": {
+            "mimeType": "application/json",
+            "size": 819,
+            "text": "{\"id\":\"apm-met-ric\",\"title\":\"Test-Create_a_new_dashboard_with_apm_metrics_widget-1740045600\",\"description\":null,\"author_handle\":\"test@datadoghq.com\",\"author_name\":null,\"layout_type\":\"ordered\",\"url\":\"/dashboard/apm-met-ric/testcreateanewdashboardwithapmmetricswidget1740045600\",\"is_read_only\":false,\"template_variables\":null,\"widgets\":[{\"definition\":{\"requests\":[{\"queries\":[{\"data_source\":\"apm_metrics\",\"group_by\":[\"resource_name\"],\"name\":\"query1\",\"query_filter\":\"env:prod\",\"service\":\"web-store\",\"stat\":\"hits\"}],\"response_format\":\"scalar\"}],\"title\":\"\",\"title_align\":\"left\",\"title_size\":\"16\",\"type\":\"query_table\"},\"layout\":{\"height\":4,\"width\":4,\"x\":0,\"y\":0},\"id\":1234567890123456}],\"notify_list\":null,\"created_at\":\"2025-02-20T10:00:01.000000+00:00\",\"modified_at\":\"2025-02-20T10:00:01.000000+00:00\",\"restricted_roles\":[]}"
+          },
+          "cookies": [],
+          "headers": [
+            {
+              "name": "content-type",
+              "value": "application/json"
+            }
+          ],
+          "headersSize": 381,
+          "httpVersion": "HTTP/1.1",
+          "redirectURL": "",
+          "status": 200,
+          "statusText": "OK"
+        },
+        "startedDateTime": "2025-02-20T10:00:00.015Z",
+        "time": 430
+      },
+      {
+        "_id": "71162de52581d0f391d949ff27e2aac0",
+        "_order": 0,
+        "cache": {},
+        "request": {
+          "bodySize": 0,
+          "cookies": [],
+          "headers": [
+            {
+              "_fromType": "array",
+              "name": "accept",
+              "value": "application/json"
+            }
+          ],
+          "headersSize": 520,
+          "httpVersion": "HTTP/1.1",
+          "method": "DELETE",
+          "queryString": [],
+          "url": "https://api.datadoghq.com/api/v1/dashboard/apm-met-ric"
+        },
+        "response": {
+          "bodySize": 38,
+          "content": {
+            "mimeType": "application/json",
+            "size": 38,
+            "text": "{\"deleted_dashboard_id\":\"apm-met-ric\"}"
+          },
+          "cookies": [],
+          "headers": [
+            {
+              "name": "content-type",
+              "value": "application/json"
+            }
+          ],
+          "headersSize": 379,
+          "httpVersion": "HTTP/1.1",
+          "redirectURL": "",
+          "status": 200,
+          "statusText": "OK"
+        },
+        "startedDateTime": "2025-02-20T10:00:00.460Z",
+        "time": 380
+      }
+    ],
+    "pages": [],
+    "version": "1.2"
+  }
+}
diff --git a/examples/v1/dashboards/CreateDashboard_2252738813.ts b/examples/v1/dashboards/CreateDashboard_2252738813.ts
@@ -0,0 +1,55 @@
+/**
+ * Create a new dashboard with apm metrics widget
+ */
+
+import { client, v1 } from "@datadog/datadog-api-client";
+
+const configuration = client.createConfiguration();
+const apiInstance = new v1.DashboardsApi(configuration);
+
+const params: v1.DashboardsApiCreateDashboardRequest = {
+  body: {
+    title: "Example-Dashboard",
+    widgets: [
+      {
+        definition: {
+          title: "",
+          titleSize: "16",
+          titleAlign: "left",
+          type: "query_table",
+          requests: [
+            {
+              responseFormat: "scalar",
+              queries: [
+                {
+                  stat: "hits",
+                  name: "query1",
+                  service: "web-store",
+                  dataSource: "apm_metrics",
+                  queryFilter: "env:prod",
+                  groupBy: ["resource_name"],
+                },
+              ],
+            },
+          ],
+        },
+        layout: {
+          x: 0,
+          y: 0,
+          width: 4,
+          height: 4,
+        },
+      },
+    ],
+    layoutType: "ordered",
+  },
+};
+
+apiInstance
+  .createDashboard(params)
+  .then((data: v1.Dashboard) => {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  })
+  .catch((error: any) => console.error(error));
diff --git a/features/v1/dashboards.feature b/features/v1/dashboards.feature
@@ -329,6 +329,20 @@ Feature: Dashboards
     And the response "widgets[0].definition.requests[0].queries[0].primary_tag_name" is equal to "datacenter"
     And the response "widgets[0].definition.requests[0].queries[0].operation_name" is equal to "cassandra.query"
 
+  @team:DataDog/dashboards-backend
+  Scenario: Create a new dashboard with apm metrics widget
+    Given new "CreateDashboard" request
+    And body with value { "title": "{{ unique }}", "widgets": [{"definition": { "title": "", "title_size": "16", "title_align": "left", "type": "query_table", "requests": [ { "response_format": "scalar", "queries": [ { "stat": "hits", "name": "query1", "service": "web-store", "data_source": "apm_metrics", "query_filter": "env:prod", "group_by": ["resource_name"] } ] } ] }, "layout": { "x": 0, "y": 0, "width": 4, "height": 4 } } ], "layout_type": "ordered" }
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "widgets[0].definition.requests[0].response_format" is equal to "scalar"
+    And the response "widgets[0].definition.requests[0].queries[0].stat" is equal to "hits"
+    And the response "widgets[0].definition.requests[0].queries[0].group_by[0]" is equal to "resource_name"
+    And the response "widgets[0].definition.requests[0].queries[0].name" is equal to "query1"
+    And the response "widgets[0].definition.requests[0].queries[0].service" is equal to "web-store"
+    And the response "widgets[0].definition.requests[0].queries[0].data_source" is equal to "apm_metrics"
+    And the response "widgets[0].definition.requests[0].queries[0].query_filter" is equal to "env:prod"
+
   @team:DataDog/dashboards-backend
   Scenario: Create a new dashboard with apm resource stats widget
     Given new "CreateDashboard" request
diff --git a/packages/datadog-api-client-v1/index.ts b/packages/datadog-api-client-v1/index.ts
@@ -455,6 +455,10 @@ export { EventTimelineWidgetDefinitionType } from "./models/EventTimelineWidgetD
 export { FormulaAndFunctionApmDependencyStatName } from "./models/FormulaAndFunctionApmDependencyStatName";
 export { FormulaAndFunctionApmDependencyStatsDataSource } from "./models/FormulaAndFunctionApmDependencyStatsDataSource";
 export { FormulaAndFunctionApmDependencyStatsQueryDefinition } from "./models/FormulaAndFunctionApmDependencyStatsQueryDefinition";
+export { FormulaAndFunctionApmMetricsDataSource } from "./models/FormulaAndFunctionApmMetricsDataSource";
+export { FormulaAndFunctionApmMetricsQueryDefinition } from "./models/FormulaAndFunctionApmMetricsQueryDefinition";
+export { FormulaAndFunctionApmMetricsSpanKind } from "./models/FormulaAndFunctionApmMetricsSpanKind";
+export { FormulaAndFunctionApmMetricStatName } from "./models/FormulaAndFunctionApmMetricStatName";
 export { FormulaAndFunctionApmResourceStatName } from "./models/FormulaAndFunctionApmResourceStatName";
 export { FormulaAndFunctionApmResourceStatsDataSource } from "./models/FormulaAndFunctionApmResourceStatsDataSource";
 export { FormulaAndFunctionApmResourceStatsQueryDefinition } from "./models/FormulaAndFunctionApmResourceStatsQueryDefinition";
diff --git a/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricStatName.ts b/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricStatName.ts
@@ -0,0 +1,46 @@
+/**
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2020-Present Datadog, Inc.
+ */
+
+import { UnparsedObject } from "../../datadog-api-client-common/util";
+
+/**
+ * APM metric stat name.
+ */
+
+export type FormulaAndFunctionApmMetricStatName =
+  | typeof ERRORS
+  | typeof ERROR_RATE
+  | typeof ERRORS_PER_SECOND
+  | typeof LATENCY_AVG
+  | typeof LATENCY_MAX
+  | typeof LATENCY_P50
+  | typeof LATENCY_P75
+  | typeof LATENCY_P90
+  | typeof LATENCY_P95
+  | typeof LATENCY_P99
+  | typeof LATENCY_P999
+  | typeof LATENCY_DISTRIBUTION
+  | typeof HITS
+  | typeof HITS_PER_SECOND
+  | typeof TOTAL_TIME
+  | typeof APDEX
+  | UnparsedObject;
+export const ERRORS = "errors";
+export const ERROR_RATE = "error_rate";
+export const ERRORS_PER_SECOND = "errors_per_second";
+export const LATENCY_AVG = "latency_avg";
+export const LATENCY_MAX = "latency_max";
+export const LATENCY_P50 = "latency_p50";
+export const LATENCY_P75 = "latency_p75";
+export const LATENCY_P90 = "latency_p90";
+export const LATENCY_P95 = "latency_p95";
+export const LATENCY_P99 = "latency_p99";
+export const LATENCY_P999 = "latency_p999";
+export const LATENCY_DISTRIBUTION = "latency_distribution";
+export const HITS = "hits";
+export const HITS_PER_SECOND = "hits_per_second";
+export const TOTAL_TIME = "total_time";
+export const APDEX = "apdex";
diff --git a/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricsDataSource.ts b/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricsDataSource.ts
@@ -0,0 +1,16 @@
+/**
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2020-Present Datadog, Inc.
+ */
+
+import { UnparsedObject } from "../../datadog-api-client-common/util";
+
+/**
+ * Data source for APM metrics queries.
+ */
+
+export type FormulaAndFunctionApmMetricsDataSource =
+  | typeof APM_METRICS
+  | UnparsedObject;
+export const APM_METRICS = "apm_metrics";
diff --git a/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricsQueryDefinition.ts b/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricsQueryDefinition.ts
diff --git a/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricsSpanKind.ts b/packages/datadog-api-client-v1/models/FormulaAndFunctionApmMetricsSpanKind.ts
diff --git a/packages/datadog-api-client-v1/models/FormulaAndFunctionQueryDefinition.ts b/packages/datadog-api-client-v1/models/FormulaAndFunctionQueryDefinition.ts
diff --git a/packages/datadog-api-client-v1/models/ObjectSerializer.ts b/packages/datadog-api-client-v1/models/ObjectSerializer.ts
