트레이스 상관 관계

트레이스 상관 관계 (Trace correlations)

Grafana 상관 관계(correlations)를 사용해 트레이스 뷰에 인터랙티브 상관 링크를 임베드해, 스팬에서 관련 로그·메트릭·프로파일·외부 시스템으로 이동할 수 있어요. 이 안내서는 Grafana에서 Trace correlations를 구성·관리하는 방법을 설명해요.

출처: 문서

본문

트레이스 상관 관계란?

Trace correlations는 트레이스 스팬에 맥락에 민감한 링크를 주입하는 규칙을 정의하게 해줘요. Explore나 Traces 패널에서 트레이스를 볼 때 사용자는 이 링크를 클릭해 관련 쿼리나 URL로 바로 이동할 수 있어요. 상관 관계는 Tempo 데이터 소스에 구성할 수 있는 trace to logs·metrics·profiles 링크와 비슷하지만 더 유연해요.

시작하기 전에

  • Grafana 12 이상
  • Grafana에 구성된 Tempo 데이터 소스
  • Grafana의 설정 또는 프로비저닝 파일에 대한 관리자 접근 권한

트레이스 상관 관계 설정

  1. 관리자 계정으로 Grafana에 로그인.
  2. Configuration > Plugins & data > Correlations로 이동.
  3. Add correlation 또는 Add new 선택.
  4. 1단계: 상관 관계의 레이블과 선택적 설명 제공.
  5. 2단계: 상관 관계 대상을 구성. Type 드롭다운에서 Query(다른 데이터 소스 연결) 또는 External(커스텀 URL) 선택. Query 대상은 target 드롭다운에서 링크 클릭 시 쿼리할 데이터 소스를 선택하고 대상 쿼리를 정의. External 대상은 External URL 입력. 쿼리와 외부 대상 모두 트레이스 데이터 기반의 다음 변수를 쓸 수 있어요.
변수 유형 설명
traceId String 트레이스 식별자
spanID String 스팬 식별자
parentSpanID String 부모 스팬 식별자
serviceName String 서비스 이름
serviceTags Object 리소스 속성
tags Object 스팬 속성
logs Object 트레이스 이벤트
references Object 트레이스 링크

객체 변수는 정규식 변환으로 값 변수에 파싱해야 해요.

  1. 3단계: 상관 관계 데이터 소스 구성. Source 드롭다운에서 Tempo 데이터 소스 선택. Results 필드에 상관 관계에 쓰는 트레이스 데이터 변수를 입력. 선택적으로 하나 이상의 Transformations를 추가해 트레이스 데이터를 추가 변수로 파싱. 이 변수들로 상관 관계 Target을 구성.
  2. Save를 클릭해 상관 관계 저장.

Explore에서 상관 관계 검증

  • Explore를 열고 Tempo 트레이싱 소스 선택.
  • 스팬을 로드하는 쿼리를 실행.
  • 스팬 링크 메뉴에 마우스를 올리거나 스팬 세부 정보를 열어 상관 링크 버튼을 표시.
  • 상관 링크를 클릭해 분할 뷰를 열거나 대상 시스템·쿼리로 이동.

예제

예제 1: 서비스 이름과 트레이스 ID로 trace to logs

1단계에서 레이블이 Logs for this service and trace인 상관 관계와 선택적 설명을 추가해요. 2단계에서 대상 유형 Query를 선택하고 Target으로 Loki 데이터 소스를 선택해요. 스팬 데이터에서 파생된 serviceName과 traceID 변수를 사용하는 Loki 쿼리를 정의해요:

{service_name="$serviceName"} | trace_id=`$traceID` |= ``

이 쿼리에서 service_name은 {} 안의 유일한 스트림 라벨이에요. 스트림 라벨은 로그 소스를 설명하는 저카디널리티 값이어야 해요. trace_id 필드는 | 파이프 뒤에 파이프라인 필터로 나타나며, 추가 스트림을 만들지 않고 로그 콘텐츠나 구조화 메타데이터를 검색해요. 트레이스 ID 같은 고카디널리티 값을 스트림 라벨로 쓰지 마세요 — 각 고유 값이 별도 스트림을 만들어 Loki 성능을 저하시켜요. Label best practices와 Cardinality를 참고하세요. 3단계에서 Source로 Tempo를 선택하고 Results 필드에 traceID를 사용해요. span serviceTags에서 serviceName을 추출하는 변환을 이 정규식으로 추가해요:

{(?=[^\}]*\bkey":"service.name")[^\}]*\bvalue":"(.*?)".*}

예제 2: 커스텀 URL로 상관 관계

1단계에서 레이블이 Open custom URL인 상관 관계를 추가해요. 2단계에서 대상 유형 External을 선택하고, 스팬 데이터에서 파생된 변수(serviceName, traceID)를 사용하는 대상 URL을 정의해요:

https://my-server.example.com/service=$serviceName&trace=$traceID

3단계에서 Source로 Tempo를 선택하고 traceID를 사용하며, 예제 1과 같은 정규식 변환으로 serviceName을 추출해요.

모범 사례

  • 명확히 이름 짓기: 소스와 대상을 나타내는 설명적인 이름을 사용하세요. 예: Trace to errors in logs.
  • 저카디널리티 스트림 라벨 사용: Loki를 대상으로 할 때 스트림 선택자 {} 안에는 service_name, namespace, cluster 같은 저카디널리티 값만 사용하세요. 트레이스 ID 같은 고카디널리티 값은 파이프라인 필터(| 뒤)에 두거나 구조화 메타데이터로 저장하세요. 스트림 라벨로 쓰면 과도한 스트림을 만들어 Loki 성능을 저하시켜요. Cardinality와 Label best practices를 참고하세요.
  • 현명하게 템플릿: 여러 필드를 주입해야 하면 여러 $variable 토큰을 사용하세요.

다음 단계

  • Configure trace to logs correlation — 태그 매핑과 카디널리티 안내로 스팬을 Loki의 로그 쿼리에 연결.
  • Configure trace to metrics correlation — 스팬을 Prometheus의 메트릭 쿼리에 연결.
  • Configure trace to profiles correlation — 스팬을 Grafana Pyroscope의 프로파일링 데이터에 연결.

더 알아보기 (Learn more)