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 기준을 사용해야 합니다. 본 API에는 호출 에지 페이징 또는 파일 다운로드 기능이 없습니다.
응답 필드¶
| 필드 | 설명 |
|---|---|
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가 포함되어 있습니다. 필드가 누락되었다고 해서 0값을 의미하지는 않습니다.
에지 엔드포인트가 services에 나타나지 않을 수 있습니다. 이 경우 maps의 엔드포인트 정보를 유지하고 호출 에지를 버리지 마십시오.
HTTP 및 비즈니스 상태가 모두 성공이고 구조가 정상인 경우, 빈 services와 maps는 해당 시간 범위에 토폴로지 데이터가 없음을 의미합니다. 실패 또는 구조 누락은 빈 결과로 간주할 수 없습니다.
여러 워크스페이스를 집계할 때는 원본 JSON, 실패한 워크스페이스 및 traceId를 유지하십시오. 동일한 호출 에지가 중복으로 나타날 수 있으므로, 중복된 에지의 요청 수를 단순 합산하거나 P99를 평균내지 마십시오.
필터 조건¶
filters 예시는 다음과 같습니다.
{
"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: <최종 요청 경로를 기준으로 계산된 서명>'
응답¶
{
"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"
}