External API로 서비스 토폴로지 내보내기¶

이 문서에서는 Guance External API를 사용하여 서비스 노드와 호출 관계를 가져오고, 워크스페이스별로 쿼리하여 지정한 사이트 내의 서비스 토폴로지 데이터를 집계하는 방법을 설명합니다.

API는 JSON을 반환합니다. CSV, Excel 또는 애플리케이션 의존성 목록을 생성하려면 호출 측에서 반환 결과를 정리해야 합니다.

적용 범위¶

지정된 시간 범위 내에 수집된 APM 서비스 토폴로지를 조회하여 서비스 간 호출 관계를 파악하는 데 사용합니다.
단일 워크스페이스는 서비스 토폴로지 API를 사용하고, 사이트 내 전체 워크스페이스는 "워크스페이스 페이징 조회 → 워크스페이스별 토폴로지 조회 → 결과 집계" 방식으로 사용합니다.
내보내기 결과는 수집 완전성, 데이터 보존 기간, 배포 플랜의 영향을 받으므로 모든 과거 의존 관계나 수집되지 않은 호출 관계를 의미하지는 않습니다.
이 문서에서는 매번 workspaceUUID 하나를 지정하는 방식을 사용합니다. 콘솔의 워크스페이스 간 선택기는 이 절차와 다르므로 여러 UUID나 *를 workspaceUUID에 조합하지 마세요.

서로 다른 워크스페이스 간 호출 관계를 분석해야 한다면 현장에 해당 수집 및 워크스페이스 간 토폴로지 기능이 이미 갖춰져 있는지 확인해야 합니다. APM 서비스 토폴로지 워크스페이스 간 구성 설명을 참조하세요. 워크스페이스별 집계는 원본 데이터에 존재하지 않는 워크스페이스 간 호출 엣지를 보완하지 않습니다.

사전 준비¶

현재 사이트의 External API Endpoint를 확인합니다. 일반적으로 https://external-api.guance.com이며 실제 배포 주소를 기준으로 합니다. 콘솔 front나 OpenAPI Endpoint로 대체하지 마세요.
External API의 AK/SK를 준비하고 API 서명 인증에 따라 요청 헤더를 생성합니다. 워크스페이스 OpenAPI의 DF-API-KEY로 서명을 대체하지 마세요.
External 읽기 전용 계정을 지원하는 버전에서는 읽기 전용 계정으로 이 문서의 두 조회 API를 호출할 수 있습니다. 계정은 사이트 관리자가 구성합니다.
start, end 한 세트를 고정합니다. 둘 다 밀리초 타임스탬프이며 start < end여야 합니다. 모든 워크스페이스에 동일한 시간 범위를 사용합니다. 서명 헤더의 X-Df-Timestamp는 각 요청 시점의 초 타임스탬프입니다.
먼저 워크스페이스 하나를 선택해 콘솔과 동일한 시간 범위 및 필터 조건으로 반환 결과를 검증한 후 일괄 내보내기를 시작합니다. 배포 플랜에서 그룹화 등 새로 추가된 파라미터의 지원 여부는 현장 버전을 기준으로 합니다.

1단계: 워크스페이스 목록 페이징 조회¶

워크스페이스 목록 API를 호출합니다:

GET /api/v1/workspace/list?pageIndex=1&pageSize=100

pageIndex는 1부터 시작하며 pageSize는 최대 100입니다. 사이트 내 전체 워크스페이스를 내보낼 때는 search를 전달하지 않습니다.

응답에서 다음을 읽습니다:

필드	용도
`content.data[].uuid`	이후 토폴로지 요청의 `workspaceUUID`
`content.data[].name`	내보내기 데이터에 조회 워크스페이스 이름을 추가
`content.pageInfo.totalCount`	조건에 해당하는 워크스페이스 수로, 계속 페이지를 넘길지 판단

페이지가 끝날 때까지 pageIndex를 1씩 증가시킵니다. UUID 기준으로 중복을 제거하고 이번에 실제로 조회한 워크스페이스 목록을 저장합니다. 총 수에 도달하지 않았는데 빈 페이지가 반환되면 예외를 기록하고 다시 확인해야 하며, 전체 워크스페이스 내보내기 성공을 단정하면 안 됩니다. 내보내기 중 워크스페이스가 추가되거나 삭제되면 페이징 결과도 달라질 수 있습니다.

2단계: 워크스페이스별 서비스 토폴로지 조회¶

service map API를 호출합니다:

GET /api/v1/tracing/service_map_v2?workspaceUUID=wksp_example&start=1789430400000&end=1789516800000

예시 시간 범위는 베이징 시간 2026-09-15 08:00부터 2026-09-16 08:00까지이며, 실제로 필요하고 데이터 보존 기간 내에 있는 범위로 교체하세요.

아래 요청은 전달해야 하는 서명 헤더를 보여주며, 플레이스홀더를 그대로 사용해 실행할 수 없습니다:

curl '<Endpoint>/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: <根据最终请求路径计算的签名>'

요청할 때마다 임시 코드, 타임스탬프, 서명을 다시 생성해야 합니다. 서명은 최종 전송하는 원본 경로와 쿼리 문자열을 사용합니다. groupBy 등의 파라미터를 추가하거나 URL 인코딩한 경우 최종 경로 기준으로 다시 서명해야 합니다.

조회 범위 선택¶

목표	파라미터 설정
워크스페이스 하나에서 선택한 시간 범위의 전체 토폴로지 조회	`workspaceUUID`, `start`, `end`만 전달하고 `centralService`, `search`, 제한적 `filters`는 전달하지 않음
지정한 중심 서비스의 토폴로지 조회	`centralService` 추가, 예: `centralService=demo-web`
환경과 버전 구분	해당 파라미터를 지원하는 버전에서 `groupBy=env,version` 추가
프로젝트 또는 K8s 클러스터 구분	실제 필요에 따라 `groupBy=project`, `groupBy=cluster_name_k8s` 또는 조합으로 설정

groupBy는 노드 식별에 영향을 주므로 모든 워크스페이스에 동일한 그룹화 기준을 사용해야 합니다. 중심 서비스를 지정하고 그룹화를 활성화한 경우 centralWorkspaceUUID, centralEnv 등의 필드로 중심 노드를 추가로 특정할 수 있습니다. 자세한 내용은 API 파라미터 설명을 참조하세요.

콘솔의 단일 서비스 "업스트림/다운스트림" 뷰에는 중심 서비스 제한이 포함되므로 전체 워크스페이스 토폴로지로 간주할 수 없습니다. 페이지와 API를 대조할 때는 시간, 워크스페이스, 그룹화, 필터 조건을 동시에 맞춰야 합니다. 그래프 레이아웃, 노드 색상 등 표시 속성은 내보내야 하는 비즈니스 관계에 포함되지 않습니다.

내보내기 시 content.services와 content.maps를 직접 읽습니다. serviceMapList=true로 추가 목록을 생성하거나 파일을 다운로드하는 방식에 의존하지 마세요.

3단계: 노드, 호출 엣지, 실행 결과 저장¶

각 요청은 먼저 HTTP 상태와 응답의 code, success, errorCode를 확인합니다. 성공하면 전체 JSON을 저장하고, 이번 조회의 워크스페이스 UUID, 시간 범위, 그룹화 파라미터를 함께 기록합니다.

필드	의미
`content.services`	서비스 노드 목록. 노드 이름, 워크스페이스 식별 정보, 노드 ID(있는 경우), `data`를 보존
`content.maps`	방향이 있는 호출 엣지. `source`는 호출자, `target`은 피호출자
`maps[].source_workspace_uuid` / `target_workspace_uuid`	엣지 양쪽 끝이 속한 워크스페이스(반환 시 보존해야 함)
`maps[].source_id` / `target_id`	엣지 양쪽 끝의 노드 ID(반환 시 보존해야 함). 동일 이름 노드 구분에 사용 가능
`maps[].avg_per_second`, `error_count`, `error_rate`, `p99`	호출 엣지가 반환할 수 있는 통계 필드. 실제 버전의 반환 기준 적용

테스트 환경에서 실제로 측정한 응답의 비식별화 발췌는 service map 응답 예시를 참조하세요. 예시는 선택한 노드와 호출 엣지의 필드 및 통계 값을 보존하지만 현장 응답 검증을 대체할 수 없습니다.

다음 두 가지 유형의 파일을 출력하는 것이 좋습니다:

원본 JSON: 조회 워크스페이스별로 각각 저장하고 노드, 엣지, 통계 값, 응답 traceId를 보존하여 재확인에 대비합니다.
호출 관계 테이블: 각 행에 방향이 있는 호출 관계 하나를 기록하며, 최소한 조회 워크스페이스, 소스 워크스페이스, 소스 서비스, 대상 워크스페이스, 대상 서비스, 시작 시간, 종료 시간을 포함합니다. 실제 응답에 따라 노드 ID와 그룹화 차원을 추가합니다.

집계 규칙:

A → B와 B → A는 서로 다른 관계입니다.
서로 다른 워크스페이스의 동일 이름 서비스는 이름만으로 병합할 수 없습니다. "워크스페이스 식별 정보 + 노드 ID"를 우선 사용하고, ID가 없으면 "워크스페이스 식별 정보 + 서비스 이름 + 선택한 그룹화 차원"을 사용합니다. 워크스페이스 식별 정보를 확인할 수 없으면 검토 대상으로 표시하고, 조회 워크스페이스를 기준으로 엣지 반대쪽의 소속 워크스페이스를 추측하지 마세요.
동일한 호출 엣지가 여러 워크스페이스의 조회 결과에 나타날 수 있습니다. 관계 목록은 위의 노드 식별 정보로 구성된 방향 엣지를 기준으로 중복을 제거하고 소스 조회 워크스페이스를 함께 보존할 수 있습니다. 원본 JSON은 중복을 제거하지 않습니다.
중복 엣지의 요청 수를 직접 합산하거나 요청 속도, 오류율, P99를 직접 평균 내지 마세요. 전체 통계 값이 필요하면 별도로 집계 기준을 정해야 합니다.
services와 maps는 각각 저장합니다. 호출 엣지에서만 노드를 추출하면 호출 엣지가 없는 서비스가 누락될 수 있습니다.
필드 누락을 0으로 처리하면 안 됩니다. 특히 통계 필드는 "반환되지 않음"과 "0 값 반환"을 구분해야 합니다.

일괄 실행 절차¶

다음은 프로세스 의사 코드입니다. 서명 클라이언트 구현은 API 서명 인증의 Python 예시를 재사용할 수 있습니다.

start, end, groupBy 고정
workspace/list를 페이징으로 읽고 uuid 기준 중복 제거 후 워크스페이스 목록 저장
워크스페이스 목록 읽기 실패 시: 중지하고 이번 내보내기를 불완전으로 표시

워크스페이스 목록의 각 워크스페이스에 대해 직렬로 실행:
    서명을 다시 생성하고 service_map_v2 조회
    HTTP 또는 비즈니스 상태 실패 시:
        실패 워크스페이스, 오류 코드, traceId를 기록하고 다른 워크스페이스 계속
    성공했지만 services/maps 구조가 비정상인 경우:
        원본 응답 저장, 구조 비정상으로 표시, 빈 토폴로지로 취급하지 않음
    성공하고 구조가 정상인 경우:
        원본 JSON 저장
        services와 maps가 모두 비어 있으면 "해당 시간 범위에 토폴로지 데이터 없음" 기록
        그렇지 않으면 노드 식별 정보 기준으로 호출 관계 테이블 정리

워크스페이스 총 수, 성공 수, 데이터 없음 수, 실패 수 및 실패 워크스페이스 목록 출력
실패 또는 구조 비정상이 있는 경우: 결과를 부분 완료로 표시
실패 워크스페이스를 동일한 시간 범위에서 다시 시도한 후 집계 결과 업데이트

먼저 직렬로 조회하고 합리적인 요청 타임아웃을 설정하는 것이 좋습니다. 워크스페이스가 많을 경우 현장 부하에 따라 동시성을 제어합니다. 서비스 토폴로지 API는 pageIndex/pageSize 방식의 페이징 파라미터를 제공하지 않으므로 워크스페이스 목록의 페이지 넘김 방식을 적용해 더 많은 호출 엣지를 가져올 수 없습니다. 데이터 양이 많을 때는 현장 조회 제한과 반환 완전성을 확인해야 합니다.

검증 및 문제 해결¶

현상	확인 방법
서명 실패	Endpoint, AK/SK, `v20240417`, 시스템 시간, 서명 경로가 최종 URL 인코딩 및 파라미터 순서와 일치하는지 확인
한 서비스 주변의 관계만 내보내짐	페이지 요청에서 `centralService`, 검색 또는 필터 조건을 복사했는지 확인
페이지의 서비스 수와 일치하지 않음	워크스페이스, 시간, 그룹화, 필터, 업스트림/다운스트림·전체 토폴로지 뷰를 맞춰 확인. 페이지 표시는 노드와 엣지를 추가 처리함
워크스페이스 간 호출 엣지가 보이지 않음	수집, 현장 버전, 워크스페이스 간 토폴로지 구성을 확인. 워크스페이스별 집계만으로는 워크스페이스 간 관계가 완전하다고 단정할 수 없음
동일 이름 서비스가 병합됨	워크스페이스 식별 정보, 노드 ID, `groupBy` 차원이 중복 제거에 포함되는지 확인
빈 결과	먼저 요청 성공과 구조 정상 여부를 확인한 후 시간 범위, 보존 기간, 해당 워크스페이스에 APM 데이터가 있는지 확인
일부 워크스페이스 요청 실패	실패 목록과 `traceId`를 보존하고 재시도한 후 내보내기 완료 여부를 확인

고객 환경에 배포하기 전에 최소한 다음을 검증하는 것이 좋습니다: 호출 관계가 있는 워크스페이스 하나, 토폴로지 데이터가 없는 워크스페이스 하나, 워크스페이스 목록 페이징, 실패 워크스페이스 기록, 서로 다른 워크스페이스의 동일 이름 서비스 구분.