通过本次最佳实践内容，您可以看到ARMS OpenAPI可以灵活的被集成到客户链路监控场景，并对其进行可视化图形展示监控信息。
1. 背景信息
应用实时监控服务ARMS（Application Real-Time Monitoring Service）是一款应用性能管理产品，能帮助你实现全栈式的性能监控和端到端的全链路追踪诊断，让应用运维更加高效。
本次最佳实践是基于调用ARMS OpenAPI的形式来实现客户应用场景链路监控的可视化图形展示，使用环境为专有云V3.10版本ASCM控制台，调用ARMS OpenAPI接口通过工具Postman进行测试，在第二章节详细介绍了测试环境及测试工具。第三章节通过一个查询所有应用ARMS OpenAPI接口描述调用过程，并且包含该接口需要请求传入的参数接口列表。最后一章节将对一个复杂应用场景，获取链路监控信息使用到ARMSOpenAPI接口，对每个接口列表字段、调用过程及返回结果详细介绍。
最佳实践价值
通过调用ARMS OpenAPI在应用场景的使用，直观给阅读者了解到ARMS产品的能力，及ARMS提供一套OpenAPI可以容易的集成到客户应用中，快速实现复杂的微服务链路监控能力，由ARMS监控服务能力涵盖范围能力比较广，包含浏览器、小程序、APP、分布式应用和容器环境，因此完整的监控能力，开发过程中不需要集成多开源组件的形式，使微服务程序监控功能开发简单，让应用运维变得容易。
2. 环境
在使用ARMS前您需要按照以下内容对当前的系统环境进行检查。
本次最佳实践基于专有云企业版V3.10.0版本ARMS。
说明：ARMS OpenAPI各个版本变化不大，使用方式保持一致，所以此文档也适用于公共云产品或专有云V3.7.0以上版本。专有云V3.10.0控制台称为ASCM，V3.10.0之前版本为Apsara Stack。
1.登录ASCM控制台。
2.将鼠标指向页面上方导航栏中的产品，单击企业级分布式应用服务EDAS。
图1：ASCM
说明：由于ARMS监控应用数据，需要EDAS产品配合。本次测试先通过EDAS部署一个标准的Spring Boot应用，开通ARMS监控并得到监控数据。
图 2：EDAS控制台
图 3：ARMS控制台
3.测试工具检查。
本实践将会在专有云环境中创建win64虚拟机，然后在虚拟机中安装Postman进行测试。
图4：Postman测试
3. Open API使用
调用URL确认
OpenAPI接口均为REST服务，首先确认服务的URL。
每个专有云环境域名不同，会导致URL不同。请根据具体环境信息修改URL信息，前缀及端口不变。http://arms.console.example.com:8099/
| 名称 | 接口 |
| 数据集API | /dataset/GeneralQuery.json |
| 关键应用性能指标 | /metric/Metric.json |
| 报警信息 | 无 |
| 应用监控-应用拓扑 | /trace/Dependecies.json |
| 事件集 | /eventset/EventList.json |
调用示例-查看所有应用：
API说明
URL：http://arms.console.example.com:8099/trace/Services.json
参数列表
| 字段名称 | 字段类型 | 字段含义 | 是否必选 | 备注 |
| _userId | String | 用户id | 是 | 用户名称(如arms_admin) |
返回格式示例
{
"code": 200,
"data": {
"details": [
{
"pid": "string", //应用对应的pid
"regionId": "string",
"serviceName": "string" //应用名称
}
],
"services":[ //应用名称列表
"string",
"string"
]
},
"success": true
}
Postman调用结果
参数设置：_userId= 121827433423****
图5：Postman调用结果
4. 应用描述
从ARMS中取得应用拓扑数据、曲线图、应用监控指标数据，将通过大屏DataV展示。
图6：DataV展示
5. 查询接口调用次数
通过/metric/Metric.json接口获得应用相关性能数据，查询接口调用次数。
API说明
| 字段名称 | 字段类型 | 字段含义 | 是否必选 | 备注 |
| startTime | Long | 查询数据的起始时间 | 是 | 无 |
| endTime | Long | 查询数据的截止时间 | 是 | 无 |
| intervalInSec | Integer | 时间间隔 | 否 | 建议填写 |
| metric | String | metric字段 | 是 | 详细填写参考参数填写示范 |
| filters | List[String] | 过滤字段 | 是 | 详细填写参考参数填写示范 |
| measures | List[String] | 指标 | 是 | 详细填写参考参数填写示范 |
| dimensions | List[String] | 维度 | 是 | 详细填写参考参数填写示范 |
| orderBy | String | 排序字段 | 否 | 无 |
| sortOrder | String | 排序 | 否 | 默认不排序(ASC或者DESC) |
| limit | Integer | 返回条数 | 否 | 无 |
| _userId | String | 用户id | 是 | 用户名称(如arms_admin) |
调用示例
查询指定应用过往7天的接口调用次数
参数填写示范：
| 字段名称 | 字段类型 | 字段含义 | 必选 | 示例值 | 值来源 |
| startTime | Long | 查询数据的起始时间 | 是 | 1578199319898 | 系统时间 |
| endTime | Long | 查询数据的截止时间 | 是 | 1578804119898 | 系统时间 |
| intervalInSec | Integer | 时间间隔 | 否 | 默认3600秒，即1小时 | 人工设置 |
| metric | String | metric字段，查询的指标 | 是 | APPSTAT.DETAIL | 人工设置 |
| filters | List[String] | 过滤字段,严格按照格式，否则调用出错 | 是 | [{key=pid,value=1218274334230390@db61f75c2f******},{key=regionId,value=cn-******-d01}] | Pid、regionid来自于专有云环境 |
| measures | List[String] | 指标 | 是 | [rt,count,error,errrate] | API文档 |
| dimensions | List[String] | 维度 | 是 | [pid,rpcType,rootIp] | API文档 |
| orderBy | String | 排序字段 | 否 | 无 | 无 |
| sortOrder | String | 排序 | 否 | 默认不排序(ASC或者DESC) | 无 |
| limit | Integer | 返回条数 | 否 | 无 | 无 |
| _userId | String | 用户id | 是 | 121827433423**** | 无 |
查询结果
参数设置：
图7：参数设置
结果说明：
- 返回结果为JSON数据集。
- 数据集会标示查询状态，成功返回200，如果失败会返回相应的错误码和错误原因。典型错误例如缺少必要参数、身份认证错误等（是因为filters参数没按格式要求写好）。
- OpenAPI返回的结果集组织形式与查询数据的开始时间、结束时间、数据间隔时间有关。本次查询是查询了过往7天，数据间隔时间设置成了24小时，所以这个结果集里返回了7个”data”的集合。
- 每个data里包括在“measure”和”dimension”里指定的查询，以本结果集为例，就包括：Count:0.0
PID:
rpcDesc: HTTP入口
rpcType:0（HTTP调用） - 调整查询的开始、结束、间隔时间，会影响data数据的条数，调整接口查询参数会影响每条data里的数据。
- 如果需要计算一些聚合值，比如过往7天总的HTTP调用次数，需要自行把多条data数据进行计算相加后得出结果。
6. 查询异常数量
通过/metric/Metric.json 接口获得应用相关性能数据，查询异常数量。
API说明
| 字段名称 | 字段类型 | 字段含义 | 是否必选 | 备注 |
| startTime | Long | 查询数据的起始时间 | 是 | 无 |
| endTime | Long | 查询数据的截止时间 | 是 | 无 |
| intervalInSec | Integer | 时间间隔 | 否 | 建议填写 |
| metric | String | metric字段 | 是 | 详细填写参考下文 |
| filters | List[String] | 过滤字段 | 是 | 详细填写参考下文 |
| measures | List[String] | 指标 | 是 | 详细填写参考下文 |
| dimensions | List[String] | 维度 | 是 | 详细填写参考下文 |
| orderBy | String | 排序字段 | 否 | 无 |
| sortOrder | String | 排序 | 否 | 默认不排序(ASC或者DESC) |
| limit | Integer | 返回条数 | 否 | 无 |
| _userId | String | 用户id | 是 | 用户名称(如arms_admin) |
调用示例
查询指定应用过往7天的接口调用次数。
参数填写示范：
| 字段名称 | 字段类型 | 字段含义 | 必选 | 示例值 | 值来源 |
| startTime | Long | 查询数据的起始时间 | 是 | 1577980826988 | 系统时间 |
| endTime | Long | 查询数据的截止时间 | 是 | 1578585626989 | 系统时间 |
| intervalInSec | Integer | 时间间隔 | 否 | 默认3600秒，即1小时 | 人工设置 |
| metric | String | metric字段，查询的指标 | 是 | APPSTAT.EXCEPTION | 人工设置 |
| filters | List[String] | 过滤字段,严格按照格式，否则调用出错。 | 是 | [{key=pid,value=1218274334230390@db61f75c2f******},{key=regionId,value=cn-******-d01}] | Pid、regionid来自于专有云环境 |
| measures | List[String] | 指标 | 是 | [count] | API 文档 |
| dimensions | List[String] | 维度 | 是 | [pid,rpc,endpoint,exceptionInfo] | API文档 |
| orderBy | String | 排序字段 | 否 | 无 | 无 |
| sortOrder | String | 排序 | 否 | 默认不排序(ASC或者DESC) | 无 |
| limit | Integer | 返回条数 | 否 | 无 | 无 |
| _userId | String | 用户id | 是 | 1218274334230390 | 无 |
查询结果
参数设置：
图8：参数设置
查询结果：
图9：查询结果
结果说明：
- 返回结果为JSON数据集。
- 数据集会标示查询状态，成功返回200，如果失败会返回相应的错误码和错误原因。典型错误例如缺少必要参数、身份认证错误等（是因为filters参数没按格式要求写好）。
- 本次查询未查到相关数据，所以exception数量为0。
7. 查询当前应用实例数量
通过/metric/Metric.json接口获得应用相关性能数据，查询当前应用实例数量。
API说明
| 字段名称 | 字段类型 | 字段含义 | 是否必选 | 备注 |
| startTime | Long | 查询数据的起始时间 | 是 | 无 |
| endTime | Long | 查询数据的截止时间 | 是 | 无 |
| intervalInSec | Integer | 时间间隔 | 否 | 建议填写 |
| metric | String | metric字段 | 是 | 详细填写参考下文 |
| filters | List[String] | 过滤字段 | 是 | 详细填写参考下文 |
| measures | List[String] | 指标 | 是 | 详细填写参考下文 |
| dimensions | List[String] | 维度 | 是 | 详细填写参考下文 |
| orderBy | String | 排序字段 | 否 | 无 |
| sortOrder | String | 排序 | 否 | 默认不排序(ASC或者DESC) |
| limit | Integer | 返回条数 | 否 | 无 |
| _userId | String | 用户id | 是 | 用户名称(如arms_admin) |
调用示例
查询指定应用过往7天的接口调用次数。
参数填写示范：
| 字段名称 | 字段类型 | 字段含义 | 必选 | 示例值 | 值来源 |
| startTime | Long | 查询数据的起始时间 | 是 | 1577980826988 | 系统时间 |
| endTime | Long | 查询数据的截止时间 | 是 | 1578585626989 | 系统时间 |
| intervalInSec | Integer | 时间间隔 | 否 | 默认3600秒，即1小时 | 人工设置 |
| metric | String | metric字段，查询的指标 | 是 | APPSTAT.DETAIL | 人工设置 |
| filters | List[String] | 过滤字段,严格按照格式，否则调用出错。 | 是 | [{key=pid,value=1218274334230390@db61f75c2f28609},{key=regionId,value=******}] | Pid、regionid来自于专有云环境 |
| measures | List[String] | 指标 | 是 | [count] | API 文档 |
| dimensions | List[String] | 维度 | 是 | [pid,rootIp] | API文档 |
| orderBy | String | 排序字段 | 否 | 无 | 无 |
| sortOrder | String | 排序 | 否 | 默认不排序(ASC或者DESC) | 无 |
| limit | Integer | 返回条数 | 否 | 无 | 无 |
| _userId | String | 用户id | 是 | 12182743342****** | 无 |
查询结果
参数设置：
图10：参数设置
查询结果：
图11：查询结果
结果说明：
- 返回结果为JSON数据集。
- 数据集会标示查询状态，成功返回200，如果失败会返回相应的错误码和错误原因。典型错误例如缺少必要参数、身份认证错误等（是因为filters参数没按格式要求写好）。
- Openapi返回的结果集组织形式与查询数据的开始时间、结束时间、数据间隔时间有关。本次查询是查询了过往7天，数据间隔时间设置成了24小时，所以这个结果集里返回了7个”data”的集合。
- 每个data里包括在measure和dimension里指定的查询，以本结果集为例，就包括：Count:0.0
RootIP - 本次查询需求是要看此应用一共部署了多少实例，所以对结果中不同IP进行计算，即可以算出共有多少实例数量。另外一个方法是设置intervalInSec的值，让它等查询区间，这样出来的data集合的条数就是实例数量值，因为每个IP都会有条数据。
8. 查询当前应用拓扑图
通过/trace/Dependecies.json接口获得应用拓扑相关数据。
API说明
| 字段名称 | 字段类型 | 字段含义 | 是否必选 | 备注 |
| startTime | Long | 查询数据的起始时间 | 是 | 无 |
| endTime | Long | 查询数据的截止时间 | 是 | 无 |
| _userId | String | 用户id | 是 | 用户名称（如arms_admin） |
| type | String | 查询类型 | 是 | 查询全部关系使用ALL；单个应用的关系使用APP |
| pid | String | 应用对应的pid | 否 | 当type=APP时必须填写 |
调用示例
查询指定应用过往7天的接口调用次数。
参数填写示范：
本测试1月12日进行，查询过去7天的数据。
| 字段名称 | 字段类型 | 字段含义 | 必选 | 示例值 |
| startTime | Long | 查询数据的起始时间 | 是 | 1578199319898 （1月5日） |
| endTime | Long | 查询数据的截止时间 | 是 | 1578804119898 （1月12日） |
| _userId | String | 用户id | 是 | 1218274334****** |
| type | String | 查询类型 | 是 | APP |
| pid | String | 应用对应的pid | 否 | 1218274334230390@db61f75c****** |
查询结果
参数设置：
图12：参数设置
查询结果：
{
"code": 200,
"data": {
"link": [{
"code": 200,
"data": {
"link": [
{
"callCount": 26997.0,
"child": "Demo-Service",
"childNodeId": 731107445,
"childPid": "1218274334230390@db61f75c2******",
"elapsed": 16.2328,
"errorCount": 16.0,
"parent": "USER",
"parentNodeId": 812148234,
"parentPid": "1218274334230390@db61f75c2******",
"protocol": "HTTP"
},
{
"callCount": 8.0,
"child": "pdsa_lhh_rocketmq",
"childNodeId": -1762019072,
"childPid": "pdsa_lhh_rocketmq",
"elapsed": 11190.5,
"errorCount": 8.0,
"parent": "Demo-Service",
"parentNodeId": 731107445,
"parentPid": "1218274334230390@db61f75c2******",
"protocol": "AliWareMQ"
}
],
"nodes": [
{
"elapsed": 0.0,
"errorCount": 0.0,
"id": 812148234,
"name": "USER",
"pid": "1218274334230390@db61f75c2******",
"requestCount": 0.0,
"type": "USER"
},
{
"elapsed": 0.0,
"errorCount": 0.0,
"id": 731107445,
"name": "Demo-Service",
"pid": "1218274334230390@db61f75c2******",
"requestCount": 0.0,
"type": "MQ_PRODUCER"
},
{
"elapsed": 0.0,
"errorCount": 0.0,
"id": -1762019072,
"name": "pdsa_****_rocketmq",
"pid": "pdsa_****_rocketmq",
"requestCount": 0.0,
"type": "METAQ"
}
]
},
"success": true
}
实际拓扑图效果如下：
图13：拓扑图
结果说明：
- 返回结果为JSON数据集。
- 数据集会标示查询状态，成功返回200，如果失败会返回相应的错误码和错误原因。典型错误例如缺少必要参数、身份认证错误等（是因为filters参数没按格式要求写好）。
- 查询结果是一个点线图的节点数据和连接数据，需要使用者自行按照图表控件组装相应数据。
本文为阿里云原创内容，未经允许不得转载。