1. 接口描述
接口请求域名: apm.tencentcloudapi.com 。
获取指标数据通用接口。用户根据需要上送请求参数,返回对应的指标数据。
接口调用频率限制为:20次/秒,1200次/分钟。单请求的数据点数限制为1440个。
默认接口请求频率限制:20次/秒。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:DescribeGeneralMetricData。 |
Version | 是 | String | 公共参数,本接口取值:2021-06-22。 |
Region | 是 | String | 公共参数,详见产品支持的 地域列表。 |
Filters.N | 是 | Array of GeneralFilter | 要过滤的维度信息: service_metric视图支持:service.name(服务名)、span.kind(客户端/服务端视角)为维度进行过滤,service.name(服务名)必填。 span.kind: server:服务端视角 client:客户端视角 默认为服务端视角进行查询。 runtime_metric视图支持:service.name(服务名)维度进行过滤,service.name(服务名)必填。 sql_metric视图支持:service.name(服务名)、db.instance(数据库名称)、db.ip(数据库实例ip)维度进行过滤,查询service_slow_sql_count(慢sql)指标时service.name必填,查询sql_duration_avg(耗时)指标时db.instance(数据库名称)必填。 示例值:{ "Key": "service.name", "Value": "java-order-service" } { "Key |
Metrics.N | 是 | Array of String | 需要查询的指标,不可自定义输入。 service_metric视图支持:service_request_count(总请求)、service_duration(平均响应时间)、service_error_req_rate(平均错误率)、service_slow_call_count(慢调用)、service_error_request_count(异常数量)。 runtime_metric视图支持:service_gc_full_count(Full GC)。 sql_metric视图支持:service_slow_sql_count(慢sql)、sql_duration_avg(耗时)。 示例值:"service_request_count"、“service_duration” |
InstanceId | 是 | String | 业务系统ID 示例值:apm-ylTJfTSbn |
ViewName | 是 | String | 视图名称,不可自定义输入。支持:service_metric、runtime_metric、sql_metric。 示例值:service_metric |
GroupBy.N | 否 | Array of String | 聚合维度: service_metric视图支持:service.name(服务名)、span.kind (客户端/服务端视角)维度进行聚合,service.name(服务名)必填。 runtime_metric视图支持:service.name(服务名)维度进行聚合,service.name(服务名)必填。 sql_metric视图支持:service.name(服务名)、db.statement(sql语句)维度进行聚合,查询service_slow_sql_count(慢sql)时service.name(服务名)必填,查询sql_duration_avg(耗时)指标时service.name(服务名)、db.statement(sql语句)必填。 示例值:"service.name"、"span.kind" |
StartTime | 否 | Integer | 起始时间的时间戳,单位为秒,只支持查询2天内最多1小时的指标数据。 示例值:1617123538 |
EndTime | 否 | Integer | 结束时间的时间戳,单位为秒,只支持查询2天内最多1小时的指标数据。 示例值:1617123538 |
Period | 否 | Integer | 聚合粒度,单位为秒,最小为60s,即一分钟的聚合粒度;如果为空或0则计算开始时间到截止时间的指标数据,上报其他值会报错。 示例值:60 |
OrderBy | 否 | OrderBy | 对查询指标进行排序: service_metric视图支持:service_request_count(总请求)、service_duration(平均响应时间)、service_error_req_rate(平均错误率)、service_slow_call_count(慢调用)、service_error_request_count(异常数量)。 runtime_metric视图支持:service_gc_full_count(Full GC)。 sql_metric视图支持:service_slow_sql_count(慢sql)、sql_duration_avg(耗时)。 asc:对查询指标进行升序排序 desc:对查询指标进行降序排序 示例值:"OrderBy": { "Key": "sql_duration_avg", "Value": "desc" |
PageSize | 否 | Integer | 查询指标的限制条数,目前最多展示50条数据,PageSize取值为1-50,上送PageSize则根据PageSize的值展示限制条数。 示例值:5 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
Records | Array of Line | 指标结果集 注意:此字段可能返回 null,表示取不到有效值。 |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 查询1分钟聚合粒度的runtime_metric指标数据示例
该示例查询实例为apm-ylTJfTSbn,按照service.name(服务名)为维度过滤,以service.name(服务名)进行聚合,查找开始时间-终止时间内以一分钟为聚合粒度的service_gc_full_count(Full GC)的指标数据。
输入示例
POST / HTTP/1.1
Host: apm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeGeneralMetricData
<公共请求参数>
{
"Filters": [
{
"Key": "service.name",
"Value": "tapm-api-ap-beijing"
}
],
"ViewName": "runtime_metric",
"InstanceId": "apm-ylTJfTSbn",
"Period": 60,
"Metrics": [
"service_gc_full_count"
],
"StartTime": "1652666416",
"EndTime": "1652667616",
"GroupBy": [
"service.name"
]
}
输出示例
{
"Response": {
"Records": [
{
"Tags": [
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "service_gc_full_count",
"MetricNameCN": "full GC",
"TimeSerial": [
1656428160,
1656428220,
1656428280,
1656428340,
1656428400,
1656428460,
1656428520,
1656428580,
1656428640,
1656428700,
1656428760,
1656428820,
1656428880
],
"DataSerial": [
0.016666666666666666,
0,
0.016666666666666666,
0,
0.016666666666666666,
0.016666666666666666,
0,
0.016666666666666666,
0,
0.016666666666666666,
0.016666666666666666,
0,
0.016666666666666666
]
}
],
"RequestId": "test-test-test"
}
}
示例2 查询1分钟聚合粒度的service_metric指标数据示例
该示例查询实例为apm-ylTJfTSbn,按照service.name(服务名)、span.kind(客户端/服务端视角)为维度过滤,以service.name(服务名)进行聚合,查找开始时间-终止时间内以一分钟为聚合粒度的service_request_count(总请求)、service_duration(平均响应时间)、service_error_req_rate(平均错误率)、service_slow_call_count(慢调用)、service_error_request_count(异常数量)的指标数据。
输入示例
POST / HTTP/1.1
Host: apm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeGeneralMetricData
<公共请求参数>
{
"Filters": [
{
"Key": "service.name",
"Value": "tapm-api-ap-beijing"
},
{
"Key": "span.kind",
"Value": "client"
}
],
"ViewName": "service_metric",
"InstanceId": "apm-ylTJfTSbn",
"Period": 60,
"Metrics": [
"service_request_count",
"service_duration",
"service_error_req_rate",
"service_slow_call_count",
"service_error_request_count"
],
"StartTime": "1652666416",
"EndTime": "1652667616",
"GroupBy": [
"service.name",
"span.kind"
]
}
输出示例
{
"Response": {
"Records": [
{
"Tags": [
{
"Key": "service.name",
"Value": "java-order-service"
},
{
"Key": "span.kind",
"Value": "client"
}
],
"MetricName": "service_request_count",
"MetricNameCN": "总请求数",
"TimeSerial": [
1656428160,
1656428220,
1656428280,
1656428340,
1656428400,
1656428460,
1656428520,
1656428580,
1656428640,
1656428700,
1656428760,
1656428820,
1656428880
],
"DataSerial": [
10372,
10578,
10430,
10486,
10393,
10509,
10556,
10443,
10560,
10491,
10417,
10507,
10447
]
},
{
"Tags": [
{
"Key": "service.name",
"Value": "java-order-service"
},
{
"Key": "span.kind",
"Value": "client"
}
],
"MetricName": "service_duration",
"MetricNameCN": "平均响应时间",
"TimeSerial": [
1656428160,
1656428220,
1656428280,
1656428340,
1656428400,
1656428460,
1656428520,
1656428580,
1656428640,
1656428700,
1656428760,
1656428820,
1656428880
],
"DataSerial": [
68.27933527571001,
75.1680976742024,
73.70498622754624,
74.37902912946632,
75.79610287066045,
77.2206395084234,
69.26122643544272,
69.63079755913704,
65.73752328654751,
76.56275573601707,
70.60296113316045,
71.30283125911086,
70.25328283510882
]
},
{
"Tags": [
{
"Key": "service.name",
"Value": "java-order-service"
},
{
"Key": "span.kind",
"Value": "client"
}
],
"MetricName": "service_error_req_rate",
"MetricNameCN": "平均错误率",
"TimeSerial": [
1656428160,
1656428220,
1656428280,
1656428340,
1656428400,
1656428460,
1656428520,
1656428580,
1656428640,
1656428700,
1656428760,
1656428820,
1656428880
],
"DataSerial": [
1.3594292325491708,
1.0115333711476648,
1.2655800575263663,
1.077627312607286,
1.1738670258828057,
1.1704253497002568,
1.1841606669192877,
1.0916403332375753,
1.0700757575757576,
0.9246020398436755,
1.12316405875012,
1.1040258875035691,
1.206087872116397
]
},
{
"Tags": [
{
"Key": "service.name",
"Value": "java-order-service"
},
{
"Key": "span.kind",
"Value": "client"
}
],
"MetricName": "service_slow_call_count",
"MetricNameCN": "慢调用",
"TimeSerial": [
1656428160,
1656428220,
1656428280,
1656428340,
1656428400,
1656428460,
1656428520,
1656428580,
1656428640,
1656428700,
1656428760,
1656428820,
1656428880
],
"DataSerial": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
},
{
"Tags": [
{
"Key": "service.name",
"Value": "java-order-service"
},
{
"Key": "span.kind",
"Value": "client"
}
],
"MetricName": "service_error_request_count",
"MetricNameCN": "错误数",
"TimeSerial": [
1656428160,
1656428220,
1656428280,
1656428340,
1656428400,
1656428460,
1656428520,
1656428580,
1656428640,
1656428700,
1656428760,
1656428820,
1656428880
],
"DataSerial": [
141,
107,
132,
113,
122,
123,
125,
114,
113,
97,
117,
116,
126
]
}
],
"RequestId": "test-test-test"
}
}
示例3 查询起始到终止时间内统计service_metric指标数据示例
该示例查询实例为apm-ylTJfTSbn,按照service.name(服务名)、span.kind(客户端/服务端视角)为维度过滤,以service.name(服务名)进行聚合,查找开始时间-终止时间内的service_request_count(总请求)、service_duration(平均响应时间)、service_error_req_rate(平均错误率)、service_slow_call_count(慢调用)、service_error_request_count(异常数量)的指标数据。
输入示例
POST / HTTP/1.1
Host: apm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeGeneralMetricData
<公共请求参数>
{
"Filters": [
{
"Key": "service.name",
"Value": "tapm-api-ap-beijing"
},
{
"Key": "span.kind",
"Value": "client"
}
],
"ViewName": "service_metric",
"InstanceId": "apm-ylTJfTSbn",
"Period": "0",
"Metrics": [
"service_request_count",
"service_duration",
"service_error_req_rate",
"service_slow_call_count",
"service_error_request_count"
],
"StartTime": "1652666416",
"EndTime": "1652667616",
"GroupBy": [
"service.name",
"span.kind"
]
}
输出示例
{
"Response": {
"Records": [
{
"Tags": [
{
"Key": "span.kind",
"Value": "client"
},
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "service_request_count",
"MetricNameCN": "总请求数",
"TimeSerial": null,
"DataSerial": [
630381
]
},
{
"Tags": [
{
"Key": "span.kind",
"Value": "client"
},
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "service_duration",
"MetricNameCN": "平均响应时间",
"TimeSerial": null,
"DataSerial": [
72.44506470564654
]
},
{
"Tags": [
{
"Key": "span.kind",
"Value": "client"
},
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "service_error_req_rate",
"MetricNameCN": "平均错误率",
"TimeSerial": null,
"DataSerial": [
1.1464495281425042
]
},
{
"Tags": [
{
"Key": "span.kind",
"Value": "client"
},
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "service_slow_call_count",
"MetricNameCN": "慢调用",
"TimeSerial": null,
"DataSerial": [
0
]
},
{
"Tags": [
{
"Key": "span.kind",
"Value": "client"
},
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "service_error_request_count",
"MetricNameCN": "错误数",
"TimeSerial": null,
"DataSerial": [
7227
]
}
],
"RequestId": "test-test-test"
}
}
示例4 查询1分钟聚合粒度的sql_metric的service_slow_sql_count(慢调用sql)指标数据示例
该示例查询实例为apm-ylTJfTSbn,按照service.name(服务名)为维度过滤,以service.name(服务名)进行聚合,查找开始时间-终止时间内以一分钟为聚合粒度的service_slow_sql_count(慢sql)的指标数据。
输入示例
POST / HTTP/1.1
Host: apm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeGeneralMetricData
<公共请求参数>
{
"Filters": [
{
"Key": "service.name",
"Value": "tapm-api-ap-beijing"
}
],
"ViewName": "sql_metric",
"InstanceId": "apm-ylTJfTSbn",
"Period": 60,
"Metrics": [
"service_slow_sql_count"
],
"StartTime": "1652666416",
"EndTime": "1652667616",
"GroupBy": [
"service.name"
]
}
输出示例
{
"Response": {
"Records": [
{
"Tags": [
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "service_slow_sql_count",
"MetricNameCN": "",
"TimeSerial": [
1656428160,
1656428220,
1656428280,
1656428340,
1656428400,
1656428460,
1656428520,
1656428580,
1656428640,
1656428700,
1656428760,
1656428820,
1656428880
],
"DataSerial": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
]
}
],
"RequestId": "test-test-test"
}
}
示例5 查询起始到终止时间内统计sql_metric的sql_duration_avg(耗时时间)指标数据示例
该示例查询实例为apm-ylTJfTSbn,按照db.instance(数据库名称)、(db.ip)数据库实例ip为维度过滤,以service.name(服务名)、db.statement(sql语句)为维度进行聚合,查找开始时间-终止时间内top5的sql_duration_avg(耗时(ms))的指标数据。
输入示例
POST / HTTP/1.1
Host: apm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeGeneralMetricData
<公共请求参数>
{
"Filters": [
{
"Key": "db.instance",
"Value": "mock_project_db"
},
{
"Key": "db.ip",
"Value": "9.147.18.42"
}
],
"ViewName": "sql_metric",
"InstanceId": "apm-ylTJfTSbn",
"Metrics": [
"sql_duration_avg"
],
"StartTime": "1652666416",
"EndTime": "1652667616",
"GroupBy": [
"service.name",
"db.statement"
],
"OrderBy": {
"Key": "sql_duration_avg",
"Value": "desc"
},
"PageSize": 5
}
输出示例
{
"Response": {
"Records": [
{
"Tags": [
{
"Key": "db.statement",
"Value": "select * om un_exist_table limit 1"
},
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "sql_duration_avg",
"MetricNameCN": "平均响应时间",
"TimeSerial": null,
"DataSerial": [
29.883333333333333
]
},
{
"Tags": [
{
"Key": "db.statement",
"Value": "select * om un_exist_table limit 1"
},
{
"Key": "service.name",
"Value": "java-user-service"
}
],
"MetricName": "sql_duration_avg",
"MetricNameCN": "平均响应时间",
"TimeSerial": null,
"DataSerial": [
26.170082239670673
]
},
{
"Tags": [
{
"Key": "db.statement",
"Value": "select * from un_exist_table limit 1"
},
{
"Key": "service.name",
"Value": "java-market-service"
}
],
"MetricName": "sql_duration_avg",
"MetricNameCN": "平均响应时间",
"TimeSerial": null,
"DataSerial": [
25.654237574773983
]
},
{
"Tags": [
{
"Key": "db.statement",
"Value": "select * from mock_project_userinfo where id = ? limit 1"
},
{
"Key": "service.name",
"Value": "java-order-service"
}
],
"MetricName": "sql_duration_avg",
"MetricNameCN": "平均响应时间",
"TimeSerial": null,
"DataSerial": [
24.333649579223025
]
},
{
"Tags": [
{
"Key": "db.statement",
"Value": "select * from un_exist_table limit 1"
},
{
"Key": "service.name",
"Value": "java-user-service"
}
],
"MetricName": "sql_duration_avg",
"MetricNameCN": "平均响应时间",
"TimeSerial": null,
"DataSerial": [
22.785741520925463
]
}
],
"RequestId": "test-test-test"
}
}
5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
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 | 查询时间不支持,最多只能查询最近2天、最多一个小时的数据。 |
InvalidParameter.ViewNameNotExistOrIllegal | 视图名称不存在或非法。 |