tencent cloud

APIs

文档APIsApplication Performance ManagementGeneral Query APIsDescribeGeneralMetricData

获取指标数据通用接口（推荐）

聚焦模式
字号
最后更新时间： 2026-05-08 20:49:06

1. 接口描述

接口请求域名： apm.intl.tencentcloudapi.com 。

获取指标数据通用接口。用户根据需要上送请求参数，返回对应的指标数据。
接口调用频率限制为：20次/秒，1200次/分钟。单请求的数据点数限制为1440个。

获取指标数据通用接口用法：DescribeGeneralMetricData 是通用的指标数据查询接口，支持灵活的获取指标数据。该接口的查询方式类似于使用如下 SQL 语句：SELECT {Metrics} FROM {ViewName} WHERE {Filters} GROUP BY {GroupBy}。在发起请求前，请确定如下关键入参：

  1. 视图（ViewName）
    决定您要查询的数据领域。
    例如：service_metric（服务监控视图）、db_metric（数据库视图）等。关于 APM 支持的视图，请参考 指标视图。

  2. 指标（Metrics）
    用于指定返回结果中包含的一个或多个指标项。
    例如：request_count（请求数）、duration_avg（平均耗时）、error_rate（错误率）。关于APM 支持的指标，请参考 APM 指标协议标准，每种视图（ViewName）支持专属的指标集。

  3. 过滤（Filters）
    支持一个或多个键值对（Key-Value）形式的过滤条件。
    例如：只查某个特定服务 service.name = "order-service"。通用维度和每种视图（ViewName）支持专属专属维度，可以用作过滤条件中的键（Key），更多详情请参考 APM 指标协议标准。

  4. 聚合（GroupBy）
    支持一个或多个聚合维度，相当于 SQL 的 GROUP BY。
    例如：按接口名称 operation 分组，查看每个接口的性能。通用维度和每种视图（ViewName）支持专属专属维度，可以用作聚合维度，更多详情请参考 APM 指标协议标准。

  5. 粒度 (Period)
    该参数决定了是否需要以时间切片聚合。

    • Period = 1：时间序列模式：返回结果中按时间切片聚合，时间序列（TimeSerial）和数据序列（DataSerial）中包含的多个值一一对应，分别代表特定时间切片上的聚合结果。时间序列模式主要用于展示时间趋势图。
    • Period = 0：汇总统计模式：返回结果中，数据序列（DataSerial）中只包含唯一的值，代表整个时间区间内的汇总数据。

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：DescribeGeneralMetricData。
Version 是 String 公共参数，本接口取值：2021-06-22。
Region 是 String 公共参数，详见产品支持的 地域列表。
Metrics.N 是 Array of String 需要查询的指标名称，不可自定义输入，详情请见。
InstanceId 是 String 业务系统 ID
ViewName 是 String 视图名称，不可自定义输入。详情请见。
Filters.N 是 Array of GeneralFilter 要过滤的维度信息，不同视图有对应的指标维度，详情请见。
GroupBy.N 否 Array of String 聚合维度，不同视图有对应的指标维度，详情请见。
StartTime 否 Integer 起始时间的时间戳，支持查询30天内的指标数据。（单位：秒）
EndTime 否 Integer 结束时间的时间戳，支持查询30天内的指标数据。（单位：秒）
Period 否 Integer 是否按固定时间跨度聚合，填入1及大于1的值按1处理，不填按0处理。
- 填入0，则计算开始时间到截止时间的指标数据。
- 填入1，则会按照开始时间到截止时间的时间跨度选择聚合粒度：
- 时间跨度 (0,12) 小时，则按一分钟粒度聚合。
- 时间跨度 [12,48] 小时，则按五分钟粒度聚合。
- 时间跨度 (48, +∞) 小时，则按一小时粒度聚合。
OrderBy 否 OrderBy 对查询指标进行排序：
Key 填写云 API 指标名称，详情请见。
Value 填写排序方式：
- asc：对查询指标进行升序排序
- desc：对查询指标进行降序排序
PageSize 否 Integer 查询指标的限制条数，目前最多展示50条数据，PageSize取值为1-50，上送PageSize则根据PageSize的值展示限制条数。

3. 输出参数

参数名称 类型 描述
Records Array of Line 指标结果集
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 获取接口分析列表数据

场景描述：查看一段时间内，各个接口的请求总量，或者查看平均响应时间、p99、最大响应时间、错误率等指标。
关键配置：

  • ViewName: 查询 service_metric（基础性能指标）视图。
  • Metrics: 返回 request_count（请求量）数据。
  • Filters: 指定span.kind（调用角色）、service.name（应用名称）查询条件。
  • GroupBy: 按 operation（接口名）聚合。
  • Period: 设置为 0，表示不按时间切片，计算整个时间范围内的汇总值。
    请求参数示例：查询服务 apm-test 下所有接口在指定时间段内的请求总数，并按接口名分组展示。

输入示例

POST / HTTP/1.1
Host: apm.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeGeneralMetricData
<公共请求参数>

{
    "InstanceId": "apm-instanceKey",
    "ViewName": "service_metric",
    "Metrics": [
        "request_count"
    ],
    "Filters": [
        {
            "Key": "span.kind",
            "Value": "server"
        },
        {
            "Key": "service.name",
            "Value": "apm-test"
        }
    ],
    "GroupBy": [
        "operation"
    ],
    "StartTime": 1768377000,
    "EndTime": 1768377900,
    "Period": 0
}

输出示例

{
    "Response": {
        "Records": [
            {
                "MetricName": "service_request_count_sum",
                "MetricNameCN": "总请求数",
                "Tags": [
                    {
                        "Key": "operation",
                        "Value": "GET /mall/test"
                    }
                ],
                "TimeSerial": [],
                "DataSerial": [
                    18
                ]
            }
        ],
        "RequestId": "bfcc1a20-b6ff-455b-8fab-1d9883f4f629"
    }
}

示例2 获取接口分析列表明细数据

场景描述：查看某个具体服务在一段时间内的流量趋势、耗时变化趋势。通常用于前端绘制折线图。
关键配置：

  • ViewName: 查询 service_metric（基础性能指标）视图。
  • Metrics: 返回 request_count（请求量）数据。
  • Filters: 指定span.kind（调用角色）、service.name（应用名称）、operation（接口）查询条件。
  • GroupBy: 未指定，代表不需要按照特定的维度进行聚合。
  • Period: 设置为 1，表示按时间切片聚合。
    请求参数示例：查询应用 apm-test 下特定接口POST /mall/test在指定时间段内的每分钟请求数趋势。

输入示例

POST / HTTP/1.1
Host: apm.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeGeneralMetricData
<公共请求参数>

{
    "InstanceId": "apm-instanceKey",
    "ViewName": "service_metric",
    "Metrics": [
        "request_count"
    ],
    "Filters": [
        {
            "Key": "span.kind",
            "Value": "server"
        },
        {
            "Key": "service.name",
            "Value": "apm-test"
        },
        {
            "Key": "operation",
            "Value": "POST /mall/test"
        }
    ],
    "StartTime": 1768377000,
    "EndTime": 1768377900,
    "Period": 1
}

输出示例

{
    "Response": {
        "Records": [
            {
                "MetricName": "service_request_count_sum",
                "MetricNameCN": "总请求数",
                "Tags": [
                    {
                        "Key": "service.name",
                        "Value": "apm-test"
                    }
                ],
                "TimeSerial": [
                    1768377000,
                    1768377060,
                    1768377120
                ],
                "DataSerial": [
                    1,
                    null,
                    1
                ]
            }
        ],
        "RequestId": "4d62d7d5-e4b7-491b-874e-3563968f1626"
    }
}

5. 开发者资源

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。

错误码 描述
FailedOperation 操作失败。
FailedOperation.AppIdNotMatchInstanceInfo AppID 和业务系统信息不匹配。
FailedOperation.InstanceIdIsEmpty 业务系统 ID 为空。
FailedOperation.InstanceNotFound APM 业务系统不存在。
FailedOperation.InvalidInstanceID 非法业务系统 ID。
FailedOperation.MetricFiltersLackParams 查询指标类数据查询条件缺少过滤参数。
FailedOperation.QueryTimeIntervalIsNotSupported 查询时间区间不支持。
FailedOperation.ViewNameNotExistOrIllegal 视图名不存在或非法。
InvalidParameter.FiltersFieldsNotExistOrIllegal Filters 中的字段不存在或非法。
InvalidParameter.GroupByFieldsNotExistOrIllegal GroupBy 中的字段不存在或非法。
InvalidParameter.MetricFiltersLackParams Filters 中必须存在 service.name 字段，否则会报错。
InvalidParameter.MetricsFieldNotExistOrIllegal Metrics 中的字段不存在或非法。
InvalidParameter.MetricsFieldsNotAllowEmpty Metrics 中不允许为空。
InvalidParameter.PeriodIsIllegal Period不为空，0或60。
InvalidParameter.QueryTimeIntervalIsNotSupported 查询时间不支持，最多只能查询最近30天的数据。
InvalidParameter.ViewNameNotExistOrIllegal 视图名称不存在或非法。
上一篇: DescribeTopologyNew下一篇: DescribeApmVulnerabilityCount

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈