서비스 맵¶
GET /api/v1/tracing/service_map_v2
개요¶
단일 워크스페이스의 지정된 시간 범위에 대한 서비스 노드, 호출 엣지 및 통계 데이터를 조회합니다.
호출 전 및 사용 단계¶
r 또는 w 권한의 External 서명을 사용합니다. 자세한 내용은 External API 서명 인증을 참고하세요. workspaceUUID는 매번 하나의 활성 워크스페이스만 지정하며, start/end는 밀리초를 사용하고 서명 시간은 별도로 현재 초 단위 값을 사용합니다. 여러 워크스페이스는 동일한 시간 범위와 groupBy 기준으로 하나씩 요청하고, 클라이언트에서 병합할 때 워크스페이스 ID를 유지해야 합니다. 전체 워크스페이스 토폴로지에서는 centralService, search 및 제한적인 filters를 생략합니다. 단일 서비스의 업스트림/다운스트림은 전체 워크스페이스로 내보낼 수 없습니다. groupBy 사용을 우선하며, 비어 있거나 유효하지 않은 groupBy도 기존 불리언 스위치를 재정의합니다. env/version으로 그룹화할 때는 실제 중심 차원을 사용해 동일 이름 서비스를 찾으며, 생략과 명시적 빈 문자열은 의미가 다릅니다. services/maps JSON을 읽으며, 호출 엣지 페이지네이션이나 파일 다운로드는 없습니다. 엣지 엔드포인트에 해당하는 노드가 반환되지 않을 수 있으므로 이러한 엣지를 버리지 않습니다. id+워크스페이스+그룹이 연관을 결정하므로, 중복 엣지의 값을 단순 합산하거나 P99를 평균하지 않도록 합니다. HTTP/비즈니스 상태가 모두 성공이고 두 배열 구조가 정상일 때만 []를 빈 토폴로지로 간주합니다. 소요 시간은 원래 마이크로초 값을 유지하며, 오류 비율 0.01은 1%입니다. 노드/엣지의 통계 범위가 다르므로 함께 합산할 수 없습니다. 일괄 내보내기는 External API를 통한 서비스 맵 내보내기를 참고하세요.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전입니다. 생략한 뒤 이 페이지의 알고리즘을 계속 사용할 수는 없습니다. 예: v20240417가져오기 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며 예시 서명 알고리즘과 함께 동작합니다. |
|
| X-Df-Access-Key | string | Y | 읽기 API는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 API는 w 자격 증명이 필요합니다. 예: <external-access-key>가져오기 또는 입력 방법: 사이트 관리자가 할당한 External API AK를 사용하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다. |
| X-Df-Nonce | string | Y | 임시 일련번호입니다. 실패 후 재전송할 때도 새 값을 생성하고 서명을 다시 계산합니다. 예: 97d275ee9f774315a7885ba7347acbd9가져오기 또는 입력 방법: 매 요청마다 uuid.uuid4().hex를 새로 생성합니다. |
| X-Df-Signature | string | Y | 대문자 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 후 HMAC-SHA256을 수행하고 hex 다이제스트를 사용합니다. 예: <hmac-sha256-hex>가져오기 또는 입력 방법: External API 서명 인증에 따라 대응하는 SK로 계산하며, 전체 실행 가능한 템플릿은 아래를 참고하세요. |
| X-Df-Timestamp | string | Y | 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며, 예시 시간을 재사용할 수 없습니다. 예: 1785427200가져오기 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초 문자열을 생성합니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| filters.tags | array | tags 객체를 포함하는 방식의 조건 목록이며, 이 배열을 filters JSON 루트로 직접 사용할 수도 있습니다. 예: [{"name": "service", "operation": "in", "value": ["checkout-api"], "condition": "and"}]가져오기 또는 입력 방법: 실제 APM 태그와 검증된 쿼리 조건으로 구성합니다. 이 경로는 filters 문자열을 디코딩한 구조를 나타냅니다. |
|
| filters.tags[*] | json | 리프 조건 또는 filters를 포함하는 재귀 그룹 객체입니다. 예: {"name": "service", "operation": "in", "value": ["checkout-api"], "condition": "and"}가져오기 또는 입력 방법: 실제 APM 태그와 검증된 쿼리 조건으로 구성합니다. 이 경로는 filters 문자열을 디코딩한 구조를 나타냅니다. |
|
| filters.tags[*].name | string | 리프 필드 이름으로 실제 수집 태그에서 가져오며, 비어 있으면 안 됩니다. 예: service가져오기 또는 입력 방법: 실제 APM 태그와 검증된 쿼리 조건으로 구성합니다. 이 경로는 filters 문자열을 디코딩한 구조를 나타냅니다. |
|
| filters.tags[*].operation | string | 리프 연산자입니다. 일반적으로 =, !=, in, notin, =~, wildcard, exists 등을 사용하며 다운스트림 지원에 따라 선택합니다. 호환되는 op를 사용할 수 있으며, 둘 다 생략하면 내부 오류가 발생합니다. 예: in가져오기 또는 입력 방법: 실제 APM 태그와 검증된 쿼리 조건으로 구성합니다. 이 경로는 filters 문자열을 디코딩한 구조를 나타냅니다. |
|
| filters.tags[*].value | array | 리프 일치 값 배열로 실제 필드 유형에 맞게 입력합니다. 필수로 제공해야 하며, 빈 배열은 와일드카드로 처리되지 않습니다. 예: ["checkout-api"]가져오기 또는 입력 방법: 실제 APM 태그와 검증된 쿼리 조건으로 구성합니다. 이 경로는 filters 문자열을 디코딩한 구조를 나타냅니다. |
|
| filters.tags[*].condition | string | 앞 항목과의 논리 연산이며 and/or이고 기본값은 and입니다. 호환되는 logic을 사용할 수 있습니다. 예: and가져오기 또는 입력 방법: 실제 APM 태그와 검증된 쿼리 조건으로 구성합니다. 이 경로는 filters 문자열을 디코딩한 구조를 나타냅니다. |
|
| filters.tags[*].filters | array | 그룹 하위 조건 배열이며 재귀 구조는 외부와 동일합니다. 비어 있지 않은 그룹은 condition으로 연결됩니다. 예: [{"name": "service", "operation": "in", "value": ["checkout-api"], "condition": "and"}]가져오기 또는 입력 방법: 실제 APM 태그와 검증된 쿼리 조건으로 구성합니다. 이 경로는 filters 문자열을 디코딩한 구조를 나타냅니다. |
|
| centralClusterNameK8s | string | 중심 ID 차원이며 생략하면 참여하지 않고, 명시적 공백은 미설정 값과 일치합니다. 그룹화와 중심 서비스가 있어야 합니다. 예: production-k8s가져오기 또는 입력 방법: 중심 노드의 cluster_name_k8s 값에서 가져옵니다. |
|
| centralEnv | string | 중심 환경 차원이며 생략하면 제한하지 않고, 명시적 공백은 미설정 값과 일치합니다. 그룹화와 중심 서비스가 있어야 합니다. 예: production가져오기 또는 입력 방법: 중심 노드의 data.env 또는 해당 환경 태그에서 값을 가져옵니다. |
|
| centralProject | string | 그룹화가 있고 centralService가 비어 있지 않을 때만 중심 ID에 참여합니다. 이 키를 생략하면 해당 차원을 제한하지 않으며, 명시적 빈 값/공백만 있는 값은 project가 설정되지 않은 경우와 정확히 일치합니다. 예: production가져오기 또는 입력 방법: 중심 노드의 project 수집 태그에서 값을 가져옵니다. |
|
| centralService | string | 선택적 중심 서비스이며 앞뒤 공백을 제거합니다. 생략하면 전체 워크스페이스입니다. 유효한 groupBy가 있으면 중심 객체 기준으로 일치시키고, 그룹화하지 않으면 서비스 이름으로 업스트림/다운스트림을 쿼리합니다. 예: checkout-api가져오기 또는 입력 방법: content.services[].data.service/name에서 실제 서비스 이름을 가져오며 노드 id가 아닙니다. |
|
| centralVersion | string | 중심 버전 차원이며 생략하면 제한하지 않고, 명시적 공백은 미설정 값과 일치합니다. 그룹화와 중심 서비스가 있어야 합니다. 예: v1가져오기 또는 입력 방법: 중심 노드의 data.version 또는 버전 태그에서 값을 가져옵니다. |
|
| centralWorkspaceUUID | string | 그룹화가 있고 centralService가 비어 있지 않을 때 적용됩니다. 생략/공백이면 workspaceUUID를 사용합니다. 공개 진입점은 하나의 워크스페이스로 쿼리하며, 이를 교차 워크스페이스 권한 부여 파라미터로 간주하지 않습니다. 예: wksp_example001가져오기 또는 입력 방법: 해당 중심 노드의 workspace_uuid를 사용합니다. |
|
| end | integer | Y | 필수 종료 밀리초 정수이며, 시간 범위에는 실제 트레이스 수집 데이터가 있어야 합니다. 예: 1785430800000가져오기 또는 입력 방법: 동일한 시간 기준의 실제 범위 종료 Unix 밀리초를 사용합니다. |
| filters | string | 선택적 JSON 문자열이며, tags 배열을 포함하는 객체 또는 조건 객체 배열을 사용할 수 있습니다. 생략하면 필터링하지 않고 []는 빈 조건입니다. fields 객체나 {}만 전달하지 마세요. 현재 정규화에서 객체가 남아 조건 배열로 처리되지 않을 수 있습니다. operation/op 및 condition/logic은 호환됩니다. 잘못된 JSON/객체 구조는 500이 발생할 수 있으며, 이는 요청 JSON 본문이 아닙니다. 예: {"tags":[{"name":"service","operation":"in","value":["checkout-api"],"condition":"and"}]}가져오기 또는 입력 방법: 이미 수집된 APM 서비스/태그 결과에서 service, env, version 등 실제 필드와 값을 선택합니다. 전체 JSON 문자열을 urlencode로 인코딩합니다. |
|
| groupBy | commaArray | 권장 그룹화 필드이며 영문 쉼표로 구분된 문자열입니다. project, cluster_name_k8s, env, version의 임의 조합이며 service_sub는 env+version으로 확장됩니다. 필드 이름은 공백/백틱을 제거하고 소문자로 변환한 뒤 중복 제거하여 고정 순서로 반환하며, 알 수 없는 값은 무시합니다. 이 키가 나타나면 우선 적용되고, 빈 문자열 또는 모두 유효하지 않은 값이면 service만 기준으로 하며 기존 스위치를 재정의합니다. 예: project,env,version가져오기 또는 입력 방법: 동일 이름 서비스를 구분해야 할 때 수집 태그에 따라 선택합니다. |
|
| groupByClusterNameK8S | boolean | 소문자 s 버전이 없을 때만 사용하며, 둘을 서로 다른 차원으로 간주해서는 안 됩니다. 예: false가져오기 또는 입력 방법: 기존 대소문자 동의어 이름이며 groupByClusterNameK8s 사용을 우선합니다. |
|
| groupByClusterNameK8s | boolean | groupBy/group_by가 없을 때만 cluster_name_k8s를 추가하며 기본값은 false입니다. 예: false가져오기 또는 입력 방법: 이전 클라이언트에서 K8s 클러스터 이름 기준으로 분리해야 할 때 true입니다. |
|
| groupByProject | boolean | groupBy/group_by가 없을 때만 project 차원을 추가하며 기본값은 false입니다. 예: false가져오기 또는 입력 방법: 이전 클라이언트에서 project 기준으로 노드를 분리할 때 true입니다. |
|
| group_by | commaArray | groupBy가 없을 때만 이 동의어 필드를 사용하며, 빈 문자열이 있어도 기존 스위치를 재정의합니다. 동시에 전달하지 마세요. 예: env,version가져오기 또는 입력 방법: 이전 클라이언트 호환 필드이며 groupBy 사용을 권장합니다. |
|
| group_by_cluster_name_k8s | boolean | 앞의 두 대소문자 필드가 모두 없을 때만 사용합니다. 예: false가져오기 또는 입력 방법: 이전 필드 이름과 호환되며 groupByClusterNameK8s를 권장합니다. |
|
| group_by_project | boolean | groupByProject가 없을 때만 사용하며, 추가 독립 차원이 아닙니다. 예: false가져오기 또는 입력 방법: 이전 필드 이름과 호환되며 groupByProject 사용을 우선합니다. |
|
| isServiceSub | boolean | 호환 불리언 스위치이며 groupBy/group_by가 없을 때만 적용됩니다. 기본값은 false입니다. 예: false가져오기 또는 입력 방법: 이전 연동에서 env+version 기준으로 서비스를 분리해야 할 때 true를 사용합니다. |
|
| search | string | 선택 사항이며 앞뒤 공백을 제거한 후 service 정규식.*입력.*으로 구성합니다. 단순 리터럴 값 검색이 아니므로 정규식 특수 문자는 비즈니스 요구에 맞게 이스케이프해야 하며, filters와 중첩 적용됩니다. 예: checkout가져오기 또는 입력 방법: 서비스 노드 name 또는 data.service에서 실제 이름 일부를 가져옵니다. |
|
| serviceMapList | boolean | 레거시 파라미터로 현재 컨트롤러에서는 사용하지 않으며, 추가 페이지 목록이나 파일을 반환하지 않습니다. 예: false가져오기 또는 입력 방법: 이전 클라이언트 호환성을 유지하며, 새로운 내보내기 로직은 services/maps를 직접 읽습니다. |
|
| showFullChain | boolean | 기본값은 false인 전체 체인 스위치입니다. showOnlyMatches와 동시에 존재할 수 있으며, 실제 토폴로지는 다운스트림 버전 구현에 따릅니다. 예: false가져오기 또는 입력 방법: 일치한 노드가 속한 전체 연결 컴포넌트가 필요할 때 true를 사용합니다. |
|
| showOnlyMatches | boolean | 기본값은 false인 일치 항목만 표시 모드 스위치입니다. showFullChain과 독립적으로 전달되며, 둘 다 true이면 Full Chain 의미로 해석됩니다. 예: false가져오기 또는 입력 방법: 검색/필터에 일치한 노드만 필요할 때 true를 사용합니다. |
|
| start | integer | Y | 필수 시작 밀리초 정수이며 end보다 작아야 합니다. 서명 timestamp는 별도로 현재 Unix 초를 사용합니다. 예: 1785427200000가져오기 또는 입력 방법: 실제 수집 데이터 범위의 시작점을 Unix 밀리초로 변환합니다. 예: JavaScript Date.getTime(). |
| workspaceUUID | string | Y | 필수 단일 워크스페이스 UUID이며 * 또는 쉼표로 여러 UUID를 연결하는 것은 지원하지 않습니다. 이 사이트의 External은 사이트 수준 자격 증명이며, 일반 멤버 OpenAPI Key로 대상 워크스페이스를 결정하지 않습니다. 예: wksp_example001가져오기 또는 입력 방법: 워크스페이스 목록의 content.data[].uuid에서 활성 워크스페이스를 가져옵니다. |
파라미터 추가 설명¶
쿼리 및 인증¶
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 | 노드와 엣지 엔드포인트의 연관 식별자이며, 연관 및 중복 제거 시 워크스페이스 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.*"
]
}
]
}
요청 예시¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/tracing/service_map_v2'
query = {'workspaceUUID': 'wksp_example001', 'start': 1785427200000, 'end': 1785430800000, 'groupBy': 'project,env,version'}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
응답¶
HTTP 200, application/json 표준 External 래퍼이며 데이터는 content에 있습니다. 이 모듈은 OpenAPI declaration을 자동으로 추가하지 않고 content.pageInfo를 최상위로 승격하지 않습니다. 응답 통계 필드는 실제 다운스트림 버전/데이터에 따라 달라집니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object | 토폴로지 JSON 객체이며 페이지네이션이 없고 OpenAPI 선언을 자동으로 추가하지 않습니다. |
| content.services | 객체 배열 | 서비스 노드이며 정상적으로 데이터가 없으면 []입니다. 모든 엣지 엔드포인트를 포함하지 않을 수 있습니다. |
| content.maps | 객체 배열 | 방향성 호출 엣지이며 source가 target을 호출합니다. 정상적으로 데이터가 없으면 []입니다. |
| content.services[].id | string | 노드 ID이며 워크스페이스 및 그룹 차원과 결합해 연관시키고, 서비스 이름만으로 중복 제거하지 않습니다. |
| content.services[].name | string | 노드 서비스 이름입니다. |
| content.services[].alias | string | 선택적 표시 별칭입니다. |
| content.services[].type | string | 선택적 서비스 유형 표시 값입니다. |
| content.services[].workspace_uuid | string | 노드가 속한 워크스페이스 UUID입니다. |
| content.services[].workspace_name | string | Studio가 UUID로 보완한 워크스페이스 이름이며, 찾을 수 없으면 비어 있을 수 있습니다. |
| content.services[].project | string | 그룹화/수집 project이며 비어 있거나 생략될 수 있습니다. |
| content.services[].cluster_name_k8s | string | 그룹화/수집 K8s 클러스터 이름이며 비어 있거나 생략될 수 있습니다. |
| content.services[].env | string | 선택적 환경 그룹 차원입니다. |
| content.services[].version | string | 선택적 버전 그룹 차원입니다. |
| content.services[].filter_matched | boolean | 선택적 필터 조건 일치 여부 표시입니다. |
| content.services[].data | object | 이 노드의 통계 및 원본 ID 태그이며 엔진/그룹화/서비스 유형에 따라 확장되므로 모든 키가 반드시 존재하지는 않습니다. |
| content.services[].data.key | string | 엔진 통계 그룹 키입니다. |
| content.services[].data.service | string | 실제 서비스 이름입니다. |
| content.services[].data.workspace_uuid | string | 통계가 속한 워크스페이스입니다. |
| content.services[].data.source_type | string | 수집 소스 유형이며 예: web/db 등입니다. |
| content.services[].data.language | string | 선택적 SDK 언어입니다. |
| content.services[].data.project | string | 선택적 project입니다. |
| content.services[].data.cluster_name_k8s | string | 선택적 클러스터 이름입니다. |
| content.services[].data.env | string | 선택적 환경입니다. |
| content.services[].data.version | string | 선택적 버전입니다. |
| content.services[].data.total_count | integer | 선택한 범위의 총 요청 수입니다. |
| content.services[].data.avg_per_second | number | 초당 평균 요청 수, req/s입니다. |
| content.services[].data.error_count | integer | 오류 요청 수입니다. |
| content.services[].data.error_rate | number | 오류 비율이며 0.01은 1%를 의미합니다. |
| content.services[].data.avg_resp_time | number | 평균 응답 시간, 마이크로초입니다. |
| content.services[].data.sum_resp_time | number | 누적 응답 시간, 마이크로초입니다. |
| content.services[].data.max_duration | number | 최대 응답 시간, 마이크로초입니다. |
| content.services[].data.apdex | number | 선택적 Apdex 지표이며 누락이 0을 의미하지 않습니다. |
| content.services[].data.p50 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.services[].data.p75 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.services[].data.p90 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.services[].data.p95 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.services[].data.p99 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.maps[].source | string | source 서비스 이름입니다. |
| content.maps[].source_id | string | source 노드 ID입니다. |
| content.maps[].source_alias | string | 선택적 표시 별칭입니다. |
| content.maps[].source_workspace_uuid | string | source가 속한 워크스페이스 UUID이며 엣지를 연결할 때 반드시 유지해야 합니다. |
| content.maps[].source_workspace_name | string | Studio가 보완한 워크스페이스 이름이며, 찾지 못하면 비어 있습니다. |
| content.maps[].source_project | string | 선택적 project 차원입니다. |
| content.maps[].source_cluster_name_k8s | string | 선택적 K8s 클러스터 차원입니다. |
| content.maps[].source_env | string | 선택적 환경 차원입니다. |
| content.maps[].source_version | string | 선택적 버전 차원입니다. |
| content.maps[].target | string | target 서비스 이름입니다. |
| content.maps[].target_id | string | target 노드 ID입니다. |
| content.maps[].target_alias | string | 선택적 표시 별칭입니다. |
| content.maps[].target_workspace_uuid | string | target이 속한 워크스페이스 UUID이며 엣지를 연결할 때 반드시 유지해야 합니다. |
| content.maps[].target_workspace_name | string | Studio가 보완한 워크스페이스 이름이며, 찾지 못하면 비어 있습니다. |
| content.maps[].target_project | string | 선택적 project 차원입니다. |
| content.maps[].target_cluster_name_k8s | string | 선택적 K8s 클러스터 차원입니다. |
| content.maps[].target_env | string | 선택적 환경 차원입니다. |
| content.maps[].target_version | string | 선택적 버전 차원입니다. |
| content.maps[].total_count | integer | 선택한 범위의 총 요청 수입니다. |
| content.maps[].avg_per_second | number | 초당 평균 요청 수, req/s입니다. |
| content.maps[].error_count | integer | 오류 요청 수입니다. |
| content.maps[].error_rate | number | 오류 비율이며 0.01은 1%를 의미합니다. |
| content.maps[].avg_resp_time | number | 평균 응답 시간, 마이크로초입니다. |
| content.maps[].sum_resp_time | number | 누적 응답 시간, 마이크로초입니다. |
| content.maps[].p50 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.maps[].p75 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.maps[].p90 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.maps[].p95 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.maps[].p99 | number | 소요 시간 백분위수, 마이크로초이며 워크스페이스/서비스 간 백분위 값을 직접 평균할 수 없습니다. |
| content.services[].기타 키 | JSON 값 | 다운스트림에서 버전/그룹화에 따라 확장되는 노드 정보이며 실제 키에 따라 해석합니다. 누락된 필드를 0으로 채우지 마세요. |
| content.maps[].기타 키 | JSON 값 | 다운스트림에서 확장된 엣지 정보이며 교차 워크스페이스 내보내기 검증을 위해 원본 JSON을 유지합니다. |
{
"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"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 422 | ft.KodoAPMSummaryRowBudgetExceeded | 서비스 통계 집계 스캔 예산 초과 | APM 서비스 요약 데이터 양이 처리 한도를 초과했습니다. 시간 범위를 줄인 후 다시 시도하세요. | 시간 범위를 축소합니다. pageSize를 줄여도 전체 서비스 집계 예산은 감소하지 않습니다. |
| 429 | ft.KodoServerOverloaded | 쿼리 서비스 과부하 또는 사용 중 | 현재 요청이 너무 빈번합니다. 잠시 후 다시 시도하세요. | 백오프 간격으로 재시도하고 동시 쿼리 수를 줄입니다. |
| 406 | ft.KodoRequestDeadlineExceeded | 쿼리 실행이 백엔드 허용 시간을 초과했습니다. | 데이터 쿼리가 시간 초과되었습니다. 원인은 다음과 같을 수 있습니다: 데이터 양 과다, 네트워크 지연, 서버 부하 과다. 다음 방법으로 이 문제를 해결할 수 있습니다: 1. 필터 조건을 추가하거나 시간 범위를 축소한 후 다시 쿼리합니다. 2. 잠시 기다린 후 다시 쿼리합니다. |
시간 범위를 축소하고 필터 조건을 추가한 후 재시도합니다. |
| 406 | ft.KodoTooManyRows | 쿼리 데이터 양이 백엔드 제한을 초과했습니다. | 쿼리 데이터 양이 최대 개수 제한을 초과했습니다. 필터 조건을 추가하거나 시간 범위를 줄인 후 다시 쿼리하세요. | 시간 범위를 축소하거나 일치하는 서비스를 줄인 후 재시도합니다. |
| 406 | ft.KodoInvalidRegexPattern | 사용한 정규식 필터 표현식이 유효하지 않습니다. | 제공된 정규식 패턴이 유효하지 않습니다. | 정규식을 수정하거나 명확한 서비스 이름 집합을 사용합니다. |
| 500 | ft.InternalServerError | filters JSON/조건 구조 오류, 토폴로지 다운스트림 타임아웃/일반 5xx, 또는 반환된 노드/엣지 ID 필드 불완전으로 인한 포맷 예외 | 내부 오류 | traceId 및 실제 필터를 보관하고, 범위를 축소한 후 제한적으로 재시도합니다. 실패하거나 구조가 누락된 결과를 빈 토폴로지로 간주해서는 안 됩니다. |