콘텐츠로 이동

APM 서비스 목록



GET /api/v1/tracing/list

개요

지정된 시간 창 내 워크스페이스의 APM 서비스 통계를 페이지 단위로 나열하고, 등록된 서비스 목록과 모니터링 상태를 보완합니다.

호출 전 및 사용 단계

r 또는 w 권한이 있는 사이트 External 자격 증명을 사용하며, 인증은 External API 서명 인증을 참조하세요. 먼저 활성 workspaceUUID와 실제 밀리초 창을 가져옵니다. 이 API는 한 번에 하나의 워크스페이스만 처리하므로 여러 워크스페이스는 동일한 창으로 하나씩 요청합니다. 기본값은 pageIndex=1, pageSize=50(1~100)이며, p99 내림차순으로 정렬하고, order를 명시하면 첫 번째 정렬 객체만 사용합니다. content.buckets와 content.pageInfo를 읽습니다. max_*는 동일 시간 창의 전체 서비스에 대한 비교 상한이며, filters/serviceTypes를 추가해도 분모는 다시 계산되지 않습니다. 통계에 인덱스가 없으면 비어 있을 수 있으며, 실패를 빈 데이터로 간주하지 않습니다. External에는 개인 creator가 없으므로 즐겨찾기 필드는 호출자의 개인 즐겨찾기를 의미하지 않습니다. loading=true는 등록된 서비스의 추가 상태 캐시가 아직 로드 중임을 의미하며, 잠시 후 다시 조회할 수 있습니다. 읽기 요청은 상태 새로 고침 작업을 전달할 수 있으므로 dfStatus=ok/빈 checkerInfo가 전체 알림 검증을 대신할 수 없습니다. 서비스 등록 정보 uuid와 서비스 이름 service는 다릅니다. 성능 소요 시간의 원시 값은 마이크로초이며, 밀리초로 변환하려면 1000으로 나눕니다. 이 API는 CSV 파일을 내보내지 않습니다.

요청 헤더

매개변수 이름 타입 필수 설명
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>
가져오기 또는 입력 방법: 함께 제공되는 SK로 External API 서명 인증에 따라 계산하며, 전체 실행 가능한 템플릿은 아래에서 확인할 수 있습니다.
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 문자열을 디코딩한 후의 구조를 나타냅니다.
end integer Y 필수 종료 밀리초 정수이며, 창에는 실제 트레이스 수집 데이터가 있어야 합니다.
예시: 1785430800000
가져오기 또는 입력 방법: 동일한 시간 기준의 실제 창 종료 Unix 밀리초를 사용합니다.
filters json 선택적 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로 인코딩합니다.
order string 선택적 정렬 JSON 배열 문자열이며 기본값은 p99 내림차순입니다. 현재 배열의 첫 번째 객체만 읽습니다. 일반적으로 key, total_count, avg_resp_time, avg_per_second, error_count, error_rate, sum_resp_time, max_duration, p50/p75/p90/p95/p99를 사용하며 방향은 asc/desc입니다. 유효하지 않은 JSON, 빈 배열 또는 잘못된 구조는 500을 유발할 수 있으며 자동으로 대체되지 않습니다.
예시: [{"p99":"desc"}]
가져오기 또는 입력 방법: 허용된 필드 중 하나를 선택하고 필요에 따라 asc 또는 desc를 선택합니다. 단일 요소 JSON 배열 문자열을 전달합니다.
pageIndex integer 페이지 번호, 기본값 1.
null 허용: False
$minValue: 1
예시: 1
가져오기 또는 입력 방법: 1부터 시작하며, 후속 요청에서는 페이지 번호를 증가시키고 필터와 시간 창을 일관되게 유지합니다.
pageSize integer 페이지당 수량, 기본값 50.
null 허용: False
$maxValue: 100
$minValue: 1
예시: 50
가져오기 또는 입력 방법: 필요에 따라 1~100 사이의 정수를 입력합니다.
serviceTypes array 선택적 JSON 배열 문자열이며 source_type으로 서비스를 필터링합니다. 생략하면 필터링하지 않습니다. 쉼표로 구분된 문자열이 아니며 동일한 이름의 매개변수를 반복 전달하지 않습니다. 잘못된 JSON 또는 배열이 아닌 값은 다운스트림/내부 실패를 유발할 수 있습니다.
예시: ["web","db"]
가져오기 또는 입력 방법: 서비스 목록 content.buckets[].source_type/type에서 실제 타입을 읽은 후 문자열 배열로 직렬화합니다.
start integer Y 필수 시작 밀리초 정수이며 end보다 작아야 합니다. 서명 timestamp는 별도로 현재 Unix 초를 사용합니다.
예시: 1785427200000
가져오기 또는 입력 방법: 실제 수집 데이터 창의 시작점을 Unix 밀리초로 변환합니다. 예: JavaScript Date.getTime().
workspaceUUID string Y 필수 단일 워크스페이스 UUID이며, * 또는 쉼표로 여러 UUID를 연결하는 것을 지원하지 않습니다. 이 사이트의 External은 사이트 수준 자격 증명이며, 일반 멤버 OpenAPI Key로 대상 워크스페이스를 결정하지 않습니다.
예시: wksp_example001
가져오기 또는 입력 방법: 워크스페이스 목록 content.data[].uuid에서 활성 워크스페이스를 가져옵니다.

매개변수 추가 설명

JSON 필터 문자열은 전체 URL 인코딩을 사용하며 서명에 포함됩니다. 정상적인 빈 결과에서는 content.buckets=[], pageInfo.totalCount=0, loading=false일 수 있고 max_* 키는 생략될 수 있습니다. 서비스 목록 구성 필드와 실제 수집 통계는 동일한 리소스가 아닙니다.

요청 예시

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/list'
query = {'workspaceUUID': 'wksp_example001', 'start': 1785427200000, 'end': 1785430800000, 'pageIndex': 1, 'pageSize': 50}
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"))

응답

HTTP200, application/json 표준 External 응답 래퍼이며 데이터는 content에 있습니다. 이 모듈은 OpenAPI declaration을 자동으로 추가하지 않고 content.pageInfo를 최상위로 승격하지도 않습니다. 응답 통계 필드는 실제 다운스트림 버전/데이터에 따라 달라집니다.

필드 타입 설명
content.max_duration number 모든 서비스의 최대 응답 소요 시간 상한, 마이크로초.
content.max_total_count integer 모든 서비스 중 가장 큰 총 요청 수.
content.max_per_second number 모든 서비스 중 가장 큰 초당 요청 수, req/s.
content.max_avg_duration number 모든 서비스 중 가장 큰 평균 응답 소요 시간, 마이크로초.
content.max_sum_duration number 모든 서비스 중 가장 큰 누적 응답 소요 시간, 마이크로초.
content.max_p50 number 모든 서비스 중 가장 큰 P50 응답 소요 시간, 마이크로초.
content.max_p75 number 모든 서비스 중 가장 큰 P75 응답 소요 시간, 마이크로초.
content.max_p90 number 모든 서비스 중 가장 큰 P90 응답 소요 시간, 마이크로초.
content.max_p95 number 모든 서비스 중 가장 큰 P95 응답 소요 시간, 마이크로초.
content.max_p99 number 모든 서비스 중 가장 큰 P99 응답 소요 시간, 마이크로초.
content.buckets array<object> 현재 페이지의 서비스 통계입니다. 통계 필드는 기존 데이터에 따라 제공됩니다.
content.buckets[].key string 그룹화된 서비스 이름이며 일반적으로 service와 동일합니다.
content.buckets[].service string 수집 데이터의 서비스 이름이며, 단일 서비스 조회의 serviceName이기도 합니다.
content.buckets[].source_type string 수집된 서비스 소스 유형입니다.
content.buckets[].type string 호환 필드이며 source_type과 동일합니다.
content.buckets[].version string 서비스 버전이며, 해당 통계 차원이 존재할 때 반환됩니다.
content.buckets[].env string 서비스 환경이며, 해당 통계 차원이 존재할 때 반환됩니다.
content.buckets[].total_count integer 통계 창의 요청 수입니다.
content.buckets[].avg_per_second number 평균 초당 요청 수, 단위 req/s.
content.buckets[].avg_resp_time number 평균 응답 시간, 단위 마이크로초이며 밀리초로 변환할 때 1000으로 나눕니다.
content.buckets[].sum_resp_time number 누적 요청 응답 소요 시간, 단위 마이크로초.
content.buckets[].max_duration number 최대 요청 응답 소요 시간, 단위 마이크로초.
content.buckets[].p50 number 응답 시간의 50번째 백분위수, 단위 마이크로초.
content.buckets[].p75 number 응답 시간의 75번째 백분위수, 단위 마이크로초.
content.buckets[].p90 number 응답 시간의 90번째 백분위수, 단위 마이크로초.
content.buckets[].p95 number 응답 시간의 95번째 백분위수, 단위 마이크로초.
content.buckets[].p99 number 응답 시간의 99번째 백분위수, 단위 마이크로초.
content.buckets[].error_count integer 오류 요청 수입니다.
content.buckets[].error_rate number 오류율, 0~1이며 백분율로 표시할 때 100을 곱합니다.
content.buckets[].apdex number 또는 string 백엔드에서 제공하는 경우 반환되는 Apdex 만족도입니다.
content.buckets[].serviceCatelog object 해당 등록된 서비스의 TOML 구성 파싱 객체이며, 구성이 없으면 {}입니다. 현재 트레이스 목록은 originStr 전환을 제공하지 않습니다. 나열되지 않은 사용자 지정/기존 키는 원래 구성대로 반환됩니다.
content.buckets[].checkerInfo array<object> 연결된 모니터 목록입니다.
content.buckets[].checkerInfo[].name string 모니터 이름입니다.
content.buckets[].checkerInfo[].uuid string 모니터 UUID입니다.
content.buckets[].checkerInfo[].type string 모니터 유형입니다.
content.buckets[].dfStatus string 서비스의 현재 이벤트 상태(예: ok, critical)입니다. 상태 기록이 없으면 ok입니다.
content.buckets[].__docid string 서비스 상태에 대응하는 이벤트 문서 ID이며, 대응하는 이벤트가 없으면 빈 문자열입니다.
content.buckets[].isFavorite integer 또는 null 즐겨찾기 표시 0/1 또는 null입니다. External은 개인 creator를 전달하지 않으므로 현재 특정 실제 계정의 즐겨찾기 상태로 사용할 수 없습니다.
content.buckets[].uuid string 등록된 서비스 구성 UUID입니다. 등록되지 않은 서비스는 빈 문자열일 수 있습니다.
content.buckets[].language string 등록된 수집 SDK 언어이며, 등록되지 않은 경우 비어 있을 수 있습니다.
content.pageInfo object 페이지 정보는 content 내에 있습니다.
content.pageInfo.pageIndex integer 현재 페이지 번호입니다.
content.pageInfo.pageSize integer 페이지당 수량입니다.
content.pageInfo.count integer 현재 페이지의 실제 수량입니다.
content.pageInfo.totalCount integer 일치하는 서비스의 총수입니다.
content.loading boolean 추가 상태가 아직 비동기로 로드 중인지 여부입니다.
content.buckets[].serviceCatelog.Team object 서비스 및 팀 구성입니다.
content.buckets[].serviceCatelog.Team.service string 서비스 이름입니다.
content.buckets[].serviceCatelog.Team.type string 서비스 분류입니다. 작성 시 API 규칙에 따라 유효하지 않은 분류를 처리합니다.
content.buckets[].serviceCatelog.Team.colour string 서비스 표시 색상입니다.
content.buckets[].serviceCatelog.Team.team string 소속 팀 이름입니다.
content.buckets[].serviceCatelog.Team.oncall array<object> 연락처입니다.
content.buckets[].serviceCatelog.Team.oncall[].name string 연락처 표시 이름입니다.
content.buckets[].serviceCatelog.Team.oncall[].type string email, mobile 또는 slack입니다.
content.buckets[].serviceCatelog.Team.oncall[].emails array<string> email 연락처의 이메일 주소입니다.
content.buckets[].serviceCatelog.Team.oncall[].mobiles array<string> mobile 연락처의 전화번호입니다.
content.buckets[].serviceCatelog.Team.oncall[].slack string Slack 채널 주소입니다.
content.buckets[].serviceCatelog.Repos array<object> 코드 저장소 목록입니다.
content.buckets[].serviceCatelog.Repos[].name string 저장소 표시 이름입니다.
content.buckets[].serviceCatelog.Repos[].link string 저장소 URL입니다.
content.buckets[].serviceCatelog.Repos[].provider string 제공자 표시 이름입니다.
content.buckets[].serviceCatelog.Docs array<object> 운영 문서 목록입니다.
content.buckets[].serviceCatelog.Docs[].name string 문서 표시 이름입니다.
content.buckets[].serviceCatelog.Docs[].link string 문서 URL입니다.
content.buckets[].serviceCatelog.Docs[].provider string 문서 제공자 표시 이름입니다.
content.buckets[].serviceCatelog.Related object 연결된 애플리케이션, 내장 뷰 및 시나리오 태그입니다.
content.buckets[].serviceCatelog.Related.AppId string 실제 사용자 모니터링(RUM) 애플리케이션 ID이며 비어 있을 수 있습니다.
content.buckets[].serviceCatelog.Related.DashboardUUIDs array<string> 연결된 내장 뷰 UUID입니다.
content.buckets[].serviceCatelog.Related.Tags array<string> 시나리오 태그 이름입니다.
content.buckets[].serviceCatelog.기타 구성 키 JSON 값 원본 TOML이 지원하는 기타 기존/확장 내용이며, 예시 필드 집합으로 고정되지 않습니다.
{
  "code": 200,
  "content": {
    "max_total_count": 250,
    "max_per_second": 0.07,
    "max_avg_duration": 12000,
    "max_duration": 50000,
    "buckets": [
      {
        "key": "checkout-api",
        "service": "checkout-api",
        "source_type": "web",
        "type": "web",
        "version": "",
        "env": "",
        "total_count": 250,
        "avg_per_second": 0.06944444444444445,
        "avg_resp_time": 12000,
        "sum_resp_time": 3000000,
        "max_duration": 50000,
        "p50": 10000,
        "p75": 14000,
        "p90": 22000,
        "p95": 30000,
        "p99": 45000,
        "error_count": 2,
        "error_rate": 0.008,
        "apdex": 0.98,
        "serviceCatelog": {},
        "checkerInfo": [],
        "dfStatus": "ok",
        "__docid": "",
        "isFavorite": null,
        "uuid": "",
        "language": ""
      }
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 50,
      "count": 1,
      "totalCount": 1
    },
    "loading": false
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 매개변수 구문 분석 실패 매개변수 위치, 필드 이름, 타입 및 값을 확인합니다.
422 ft.KodoAPMSummaryRowBudgetExceeded 서비스 통계 집계 스캔 예산 초과 APM 서비스 요약 데이터 양이 처리 상한을 초과했습니다. 시간 범위를 줄인 후 다시 시도하세요. 시간 창을 줄입니다. pageSize를 줄여도 전체 서비스 집계 예산은 감소하지 않습니다.
429 ft.KodoServerOverloaded 조회 서비스 과부하 또는 사용 중 현재 요청이 너무 빈번합니다. 잠시 후 다시 시도하세요. 백오프 간격으로 재시도하고 동시 조회 수를 줄입니다.
500 ft.InternalServerError filters/serviceTypes/order 형식 오류, 서비스 목록 TOML 파싱 불가, 캐시 새로 고침 전달 실패 또는 통계 다운스트림 사용 불가/일반 5xx 내부 오류 예시에 따라 JSON 문자열과 유효한 구성을 사용하고 traceId를 보존하며, 먼저 시간 창을 줄인 후 제한적으로 재시도합니다. 읽기는 서비스 상태 캐시 새로 고침 작업을 트리거할 수 있지만 서비스 목록은 수정하지 않습니다.
406 ft.KodoRequestDeadlineExceeded 조회 실행이 백엔드에서 허용된 시간을 초과함 데이터 조회 시간 초과. 다음과 같은 원인일 수 있습니다: 데이터 양이 너무 많음, 네트워크 지연, 서버 부하 과다. 다음 방법으로 문제를 해결할 수 있습니다:
1. 필터 조건을 추가하거나 시간 범위를 줄인 후 다시 조회합니다.
2. 잠시 기다린 후 다시 조회를 시도합니다.
시간 범위를 줄이고 필터 조건을 추가한 후 재시도합니다.
406 ft.KodoTooManyRows 조회 데이터 양이 백엔드 제한을 초과함 조회한 데이터 양이 최대 수량 제한을 초과했습니다. 필터 조건을 추가하거나 시간 범위를 줄인 후 다시 조회하세요. 시간 범위를 줄이거나 일치하는 서비스를 줄인 후 재시도합니다.
406 ft.KodoInvalidRegexPattern 사용한 정규식 필터 표현식이 유효하지 않음 제공된 정규식 패턴이 유효하지 않습니다 정규식을 수정하거나 명확한 서비스 이름 집합으로 변경합니다.

문서 평가

이 페이지가 도움이 되었나요?