service map¶

GET /api/v1/tracing/service_map_v2

概述¶

返回指定工作空间、时间范围内的服务节点、调用关系和统计数据，响应为 JSON。批量导出需先分页获取工作空间，再逐空间查询并整理返回结果，参见通过 External API 导出服务拓扑。

Query 请求参数¶

参数名	类型	必选	说明
workspaceUUID	string	Y	空间ID
start	integer	Y	开始时间, 单位 ms
end	integer	Y	结束时间, 单位 ms
search	string		服务名过滤
filters	string		tag 过滤跟搜索跟es querydata 接口一致
isServiceSub	boolean		兼容旧参数；未传 groupBy/group_by 时，true 增加 env、version 两个分组维度，并可与旧 Project、Cluster 开关组合
serviceMapList	boolean		历史兼容参数；当前实现不使用该参数生成额外列表，导出请读取响应中的 maps 和 services
showOnlyMatches	boolean		是否仅显示匹配当前搜索或筛选条件的服务
showFullChain	boolean		是否返回过滤命中服务所在的完整连通分量；与 showOnlyMatches 独立转发，两者同时为 true 时以 Full Chain 语义为准
groupBy	commaArray		服务拓扑分组维度数组，支持 project、cluster_name_k8s、env、version 任意组合；service_sub 兼容展开为 env 和 version；多个值使用英文逗号分隔，未传或无有效值仅按 service 分组
group_by	commaArray		groupBy 的兼容参数名
groupByProject	boolean		兼容旧参数；未传 groupBy/group_by 时，true 增加 project 分组维度
group_by_project	boolean		groupByProject 的兼容参数名
groupByClusterNameK8s	boolean		兼容旧参数；未传 groupBy/group_by 时，true 增加 cluster_name_k8s 分组维度
groupByClusterNameK8S	boolean		groupByClusterNameK8s 的兼容参数名
group_by_cluster_name_k8s	boolean		groupByClusterNameK8s 的兼容参数名
centralService	string		中心服务名；会去除首尾空白
centralProject	string		中心服务 project；不传则不参与匹配，显式传空或全空白则精确匹配未设置 project
centralClusterNameK8s	string		中心服务 cluster_name_k8s；不传则不参与匹配，显式传空或全空白则精确匹配未设置集群
centralWorkspaceUUID	string		中心服务所属工作空间；会去除首尾空白
centralEnv	string		中心服务 env；不传则不参与匹配，显式传空或全空白则精确匹配未设置 env
centralVersion	string		中心服务 version；不传则不参与匹配，显式传空或全空白则精确匹配未设置 version

参数补充说明¶

查询与鉴权¶

workspaceUUID 每次指定一个工作空间，不支持以 * 或多个 UUID 代替单个空间 ID。 start、end 为毫秒时间戳；签名头 X-Df-Timestamp 为当前秒时间戳。使用 External API AK/SK 签名，可由具备读取权限的账号调用；不能用工作空间 OpenAPI 的 DF-API-KEY 替代。签名版本为 X-Df-SVersion: v20240417，每次请求按最终路径、查询字符串重新生成签名。

查询整个空间时不传 centralService、search 或限制性 filters；控制台单服务上下游视图不能直接当作全空间拓扑。多个空间应使用相同时间范围及 groupBy 口径。本接口没有调用边分页或文件下载功能。

响应字段¶

字段	说明
`content.services`	服务节点列表，节点统计数据位于 `data` 中
`content.maps`	有向调用边列表，`source` 调用 `target`
`services[].workspace_uuid`	节点所属工作空间，返回时应保留
`maps[].source_workspace_uuid` / `target_workspace_uuid`	调用边两端所属空间，不能仅按服务名区分节点
`services[].id`、`maps[].source_id` / `target_id`	节点与边端点的关联标识；关联和去重时保留空间身份及分组维度
`maps[].total_count`	所选时间范围内该调用边的请求数，与服务节点总请求数不是同一统计范围
`maps[].avg_per_second`、`error_count`、`error_rate`	每秒平均请求数、错误数和错误比例；`error_rate=0.01` 表示 1%
`maps[].avg_resp_time`、`p50`、`p75`、`p90`、`p95`、`p99`	调用边平均耗时和耗时分位数，响应示例保留原始数值

下方响应示例来自测试环境成功响应中的两个相连节点和一条调用边，保留所选记录字段与统计值，空间、服务、节点 ID 和 traceId 已脱敏。字段随版本、服务类型和分组方式变化，例如示例中只有第一个节点包含 data.apdex。字段缺失不代表零值。边端点可能未出现在 services 中，此时保留 maps 中端点信息，不要丢弃调用边。 HTTP 和业务状态均成功且结构正常时，空的 services、maps 表示该时间范围无拓扑数据；失败或结构缺失不能当作空结果。汇总多个空间时保留原始 JSON、失败空间和 traceId；同一调用边可能重复出现，不要直接累加重复边请求数或平均 P99。

筛选条件¶

filters 示例如下:

name="__codelineno-0-1">{ "tags": [ { "name": "__tags.__isError.keyword", "value": [ "true" ], "operation": "=", "condition": "and" }, { "condition": "and", "name": "__tags.__serviceName", "operation": "=~", "value": [ ".*04.*" ] } ] }

请求例子¶

curl 'https://external-api.guance.com/api/v1/tracing/service_map_v2?workspaceUUID=wksp_example&start=1789430400000&end=1789516800000' \
  -H 'X-Df-Access-Key: <AK>' \
  -H 'X-Df-SVersion: v20240417' \
  -H 'X-Df-Timestamp: <当前秒时间戳>' \
  -H 'X-Df-Nonce: <本次随机临时码>' \
  -H 'X-Df-Signature: <按最终请求路径计算的签名>'

请替换 Endpoint、空间和时间范围，并生成有效签名；占位符不能直接执行。

响应¶

{
    "code": 200,
    "content": {
        "services": [
            {
                "alias": "demo-web",
                "cluster_name_k8s": "",
                "data": {
                    "apdex": 0.9994428969359331,
                    "avg_per_second": 0.7255555555555555,
                    "avg_resp_time": 104885.94027565084,
                    "cluster_name_k8s": "",
                    "env": "",
                    "error_count": 13,
                    "error_rate": 0.0049770290964777945,
                    "key": "demo-web",
                    "language": "",
                    "max_duration": 3819430,
                    "p50": 108049,
                    "p75": 134638,
                    "p90": 174617,
                    "p95": 245331,
                    "p99": 680374,
                    "project": "",
                    "service": "demo-web",
                    "source_type": "web",
                    "sum_resp_time": 273962076,
                    "total_count": 2612,
                    "version": "",
                    "workspace_uuid": "wksp_example_1"
                },
                "filter_matched": true,
                "id": "node_demo_web",
                "name": "demo-web",
                "project": "",
                "type": "web",
                "workspace_name": "示例空间",
                "workspace_uuid": "wksp_example_1"
            },
            {
                "alias": "demo-db",
                "cluster_name_k8s": "",
                "data": {
                    "avg_per_second": 3.873611111111111,
                    "avg_resp_time": 34123.73811401936,
                    "cluster_name_k8s": "",
                    "env": "",
                    "error_count": 3,
                    "error_rate": 0.00021513087128002868,
                    "key": "demo-db",
                    "language": "",
                    "max_duration": 5601590,
                    "p50": 1086,
                    "p75": 1686,
                    "p90": 18220,
                    "p95": 185415,
                    "p99": 591486,
                    "project": "",
                    "service": "demo-db",
                    "source_type": "db",
                    "sum_resp_time": 475855528,
                    "total_count": 13945,
                    "version": "",
                    "workspace_uuid": "wksp_example_1"
                },
                "filter_matched": true,
                "id": "node_demo_db",
                "name": "demo-db",
                "project": "",
                "type": "db",
                "workspace_name": "示例空间",
                "workspace_uuid": "wksp_example_1"
            }
        ],
        "maps": [
            {
                "avg_per_second": 0.0725,
                "avg_resp_time": 1134.478927203065,
                "error_count": 0,
                "error_rate": 0,
                "p50": 267.77212581584365,
                "p75": 1064.416823688738,
                "p90": 1901.1261103999313,
                "p95": 6064.699952926481,
                "p99": 10831.996616037464,
                "source": "demo-web",
                "source_alias": "demo-web",
                "source_cluster_name_k8s": "",
                "source_id": "node_demo_web",
                "source_project": "",
                "source_workspace_name": "示例空间",
                "source_workspace_uuid": "wksp_example_1",
                "sum_resp_time": 296099,
                "target": "demo-db",
                "target_alias": "demo-db",
                "target_cluster_name_k8s": "",
                "target_id": "node_demo_db",
                "target_project": "",
                "target_workspace_name": "示例空间",
                "target_workspace_uuid": "wksp_example_1",
                "total_count": 261
            }
        ]
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-EXAMPLE"
}