Zipkin 쿼리 편집기

Zipkin 쿼리 편집기 (Zipkin query editor)

Zipkin 쿼리 편집기로 트레이스를 조회하고 시각화하는 방법을 알려드릴게요. 트레이스 ID로 직접 조회하거나, 서비스·스팬 캐스케이딩 선택기로 탐색하거나, JSON 트레이스 파일을 업로드해서 볼 수 있어요. Grafana에서 데이터 소스를 쿼리하는 일반적인 방법은 쿼리와 데이터 변환 문서를 참고하세요.

출처: 문서

본문

트레이스 ID로 조회하기

특정 트레이스를 ID로 조회하려면 이렇게 해요.

TraceID 쿼리 유형을 선택하세요.
Trace ID 필드에 트레이스 ID를 입력하세요.
Shift+Enter를 눌러 쿼리를 실행하세요.

Zipkin 트레이스 ID는 16자 또는 32자의 16진수 문자열입니다. 예: efe9cb8857f68c8f 또는 463ac35c9f6413ad48485a3953bb6124.

트레이스 ID 필드에 템플릿 변수도 사용할 수 있어요. 예를 들어 ${traceId}는 쿼리 실행 시 변수의 현재 값으로 치환됩니다.

트레이스 선택기로 조회하기

트레이스 ID를 직접 입력하는 대신 Traces 캐스케이딩 선택기로 트레이스를 탐색하고 선택할 수 있어요. 특정 트레이스 ID를 모를 때 유용하죠. 트레이스 선택기는 세 단계로 이루어져 있어요.

Service: 관심 있는 서비스를 선택하세요. 예: frontend, api-gateway
Span: 선택한 서비스 안에서 특정 연산(operation)을 선택하세요. 예: GET /api/users
Trace: 선택한 연산이 발생한 특정 트레이스를 선택하세요. 루트 연산 이름과 트레이스 기간으로 표시됩니다. 예: get /api [23 ms]

3단계에서 트레이스를 선택하면 트레이스 ID가 자동으로 채워지고 쿼리가 실행됩니다.

참고: 트레이스 선택기는 현재 선택된 Explore 시간 범위 안의 트레이스만 나열합니다. 예상한 트레이스가 보이지 않으면 시간 범위를 넓혀 보세요.

JSON 트레이스 파일 업로드하기

단일 트레이스를 담은 JSON 파일을 업로드해서 시각화할 수 있어요. 파일에 트레이스가 여러 개 있으면 Grafana는 첫 번째 트레이스를 시각화해요.

Import trace를 클릭하세요.
JSON 파일을 드래그 앤 드롭하거나 클릭해서 파일을 찾아 선택하세요.

파일은 Zipkin v2 스팬 형식의 JSON 배열이어야 합니다.

단일 스팬 트레이스 예시

[
  {
    "traceId": "efe9cb8857f68c8f",
    "id": "efe9cb8857f68c8f",
    "kind": "SERVER",
    "name": "get /api",
    "timestamp": 1627975249601797,
    "duration": 23457,
    "localEndpoint": { "serviceName": "backend", "ipv4": "127.0.0.1", "port": 9000 },
    "tags": {
      "http.method": "GET",
      "http.path": "/api"
    }
  }
]

다중 스팬 트레이스 예시

프론트엔드 서비스가 백엔드 서비스를 호출하는, 부모 스팬과 자식 스팬으로 이루어진 트레이스 예시입니다.

[
  {
    "traceId": "efe9cb8857f68c8f",
    "id": "efe9cb8857f68c8f",
    "kind": "SERVER",
    "name": "get /api",
    "timestamp": 1627975249601797,
    "duration": 23457,
    "localEndpoint": { "serviceName": "frontend", "ipv4": "127.0.0.1", "port": 8080 },
    "tags": {
      "http.method": "GET",
      "http.path": "/api",
      "http.status_code": "200"
    }
  },
  {
    "traceId": "efe9cb8857f68c8f",
    "parentId": "efe9cb8857f68c8f",
    "id": "8608dc6ce5cafe8e",
    "kind": "CLIENT",
    "name": "get /api/data",
    "timestamp": 1627975249602000,
    "duration": 18200,
    "localEndpoint": { "serviceName": "backend", "ipv4": "127.0.0.1", "port": 9000 },
    "tags": {
      "http.method": "GET",
      "http.path": "/api/data",
      "http.status_code": "200"
    }
  }
]

트레이스 UI에서 데이터 매핑 보기

Zipkin 어노테이션은 트레이스 뷰에서 로그로 표시되며, 어노테이션 키 아래에 어노테이션 값이 표시됩니다. 이를 통해 스팬 중 발생한 타임스탬프 이벤트(예: 재시도 시도, 캐시 미스)를 볼 수 있어요.

스팬 필터

트레이스 타임라인 뷰에서 스팬 필터를 사용해 스팬을 필터링할 수 있어요. 필터를 많이 추가할수록 필터링된 스팬이 더 구체적이 됩니다. 다음 필터를 하나 이상 추가할 수 있어요.

필터	설명	예시
Service name	스팬을 생성한 서비스로 필터링	`frontend`
Span name	연산(operation) 이름으로 필터링	`GET /api/users`
Duration	스팬 기간의 최소/최대값으로 필터링	Min: `10ms`, Max: `500ms`
Tags	스팬 태그, 프로세스 태그 또는 로그 필드로 필터링	`http.status_code=500`

매칭된 스팬만 표시하려면 Show matches only를 켜세요.

스팬 필터 예시

느린 데이터베이스 호출 찾기: Service name을 데이터베이스 서비스로 설정하고 Duration 최소값을 100ms로 설정하세요.
오류 찾기: error=true 또는 http.status_code=500에 대한 Tags 필터를 추가하세요.
특정 서비스 격리: Service name을 설정하고 Show matches only를 켜면 다른 스팬을 모두 숨길 수 있어요.

로그에서 트레이스 ID로 연결하기

내부 링크(internal link)를 구성해 Loki, Elasticsearch, Splunk 등 로그 데이터 소스의 로그에서 Zipkin 트레이스로 연결할 수 있어요. 구성 방법은 Loki 데이터 소스의 Derived fields 또는 Elasticsearch/Splunk 데이터 소스의 Data links 문서를 참고하세요.

메트릭에서 트레이스 ID로 연결하기

Prometheus 데이터 소스의 메트릭에서 exemplar를 구성해 Zipkin 트레이스로 연결할 수 있어요. 자세한 내용은 exemplar 소개 문서를 참고하세요.

쿼리 문제 해결

쿼리에서 문제가 발생하면 Zipkin 데이터 소스 문제 해결 문서를 참고하세요.

Zipkin 쿼리 편집기