service map¶

GET /api/v1/tracing/service_map_v2

Overview¶

Returns the service nodes, call relationships, and statistics for the specified workspace and time range. The response is in JSON.

For bulk export, first retrieve workspaces via pagination, then query each workspace and consolidate the returned results. See Export Service Map via External API.

Query Request Parameters¶

Parameter	Type	Required	Description
workspaceUUID	string	Y	Workspace ID
start	integer	Y	Start time, in ms
end	integer	Y	End time, in ms
search	string		Filter by service name
filters	string		Tag filtering; consistent with search and the ES querydata API
isServiceSub	boolean		Legacy compatibility parameter; when groupBy/group_by is not passed, true adds env and version as two grouping dimensions and can be combined with the legacy Project and Cluster switches
serviceMapList	boolean		Legacy compatibility parameter; the current implementation does not use this parameter to generate extra lists. For export, read maps and services from the response
showOnlyMatches	boolean		Whether to display only services matching the current search or filter conditions
showFullChain	boolean		Whether to return the full connected component containing the services matched by the filter; forwarded independently of showOnlyMatches. When both are true, the Full Chain semantics take precedence
groupBy	commaArray		Array of grouping dimensions for the service topology, supporting any combination of project, cluster_name_k8s, env, and version; service_sub is expanded for compatibility into env and version; multiple values are separated by English commas. If not passed or no valid values, services are grouped by service only
group_by	commaArray		Compatibility parameter name for groupBy
groupByProject	boolean		Legacy compatibility parameter; when groupBy/group_by is not passed, true adds project as a grouping dimension
group_by_project	boolean		Compatibility parameter name for groupByProject
groupByClusterNameK8s	boolean		Legacy compatibility parameter; when groupBy/group_by is not passed, true adds cluster_name_k8s as a grouping dimension
groupByClusterNameK8S	boolean		Compatibility parameter name for groupByClusterNameK8s
group_by_cluster_name_k8s	boolean		Compatibility parameter name for groupByClusterNameK8s
centralService	string		Central service name; leading and trailing whitespace is trimmed
centralProject	string		Central service project; if not passed, it does not participate in matching. Passing an explicitly empty or all-whitespace value matches services without project set
centralClusterNameK8s	string		Central service cluster_name_k8s; if not passed, it does not participate in matching. Passing an explicitly empty or all-whitespace value matches services without a cluster set
centralWorkspaceUUID	string		Workspace to which the central service belongs; leading and trailing whitespace is trimmed
centralEnv	string		Central service env; if not passed, it does not participate in matching. Passing an explicitly empty or all-whitespace value matches services without env set
centralVersion	string		Central service version; if not passed, it does not participate in matching. Passing an explicitly empty or all-whitespace value matches services without version set

Additional Parameter Notes¶

Query and Authentication¶

workspaceUUID specifies one workspace per request; using * or multiple UUIDs in place of a single workspace ID is not supported.

start and end are millisecond timestamps; the signature header X-Df-Timestamp is the current timestamp in seconds.

Use External API AK/SK signing. The request can be invoked by an account with read permission; the workspace OpenAPI DF-API-KEY cannot be used instead.

The signature version is X-Df-SVersion: v20240417, and the signature is regenerated for every request according to the final path and query string.

When querying the entire workspace, omit centralService, search, or restrictive filters; the console's single-service upstream/downstream view cannot be treated directly as the full-workspace topology.

For multiple workspaces, use the same time range and groupBy convention. This API does not provide call-edge pagination or file download functionality.

Response Fields¶

Field	Description
`content.services`	List of service nodes; node statistics are in `data`
`content.maps`	List of directed call edges; `source` calls `target`
`services[].workspace_uuid`	Workspace to which the node belongs; keep it when returning
`maps[].source_workspace_uuid` / `target_workspace_uuid`	Workspaces to which the two endpoints of the call edge belong; do not distinguish nodes by service name alone
`services[].id`、`maps[].source_id` / `target_id`	Correlation identifiers for nodes and edge endpoints; keep the workspace identity and grouping dimensions when correlating and deduplicating
`maps[].total_count`	Request count of this call edge within the selected time range; not the same statistical scope as the service node total request count
`maps[].avg_per_second`、`error_count`、`error_rate`	Average requests per second, error count, and error rate; `error_rate=0.01` means 1%
`maps[].avg_resp_time`、`p50`、`p75`、`p90`、`p95`、`p99`	Average latency and latency percentiles of the call edge; the response example retains the original values

The response example below comes from a successful response in a test environment and contains two connected nodes and one call edge. Selected record fields and statistics are retained; the workspace, service, node IDs, and traceId have been masked.

Fields vary by version, service type, and grouping mode. For example, only the first node in the example contains data.apdex. A missing field does not mean a zero value.

Edge endpoints may not appear in services. In that case, keep the endpoint information in maps and do not discard the call edge.

When both the HTTP and business statuses are successful and the structure is valid, empty services and maps mean there is no topology data for the time range. Failures or missing structures cannot be treated as empty results.

When consolidating multiple workspaces, keep the original JSON, failed workspaces, and traceId. The same call edge may appear multiple times; do not directly sum the request counts of duplicate edges or average the P99 values.

Filter Conditions¶

Example of filters:

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

Example Request¶

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: <按最终请求路径计算的签名>'

Replace the Endpoint, workspace, and time range, and generate a valid signature; the placeholders cannot be executed directly.

Response¶

{
    "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"
}