Trace to metrics 상관관계 구성

Trace to metrics 상관관계 구성 (Configure trace to metrics correlation)

Trace to metrics 기능은 트레이스(trace)의 스팬(span)에서 Prometheus 또는 다른 메트릭 데이터 소스의 메트릭으로 이동하게 해줘요. 구성하면 트레이스 뷰에 "Metrics for this span" 링크가 나타나죠. 이 기능은 모든 Prometheus 호환 데이터 소스와 함께 동작하며 Tempo 메트릭 생성기(metrics generator)가 필요 없어요 — metrics generator는 트레이스 데이터에서 새 메트릭을 만드는 반면, trace to metrics는 메트릭 데이터 소스에 이미 존재하는 메트릭으로 링크해요.

출처: 문서

본문

시작하기 전에

  • Grafana에 Tempo 데이터 소스가 구성되어 있어야 해요.
  • Grafana에 Prometheus 호환 메트릭 데이터 소스가 구성되어 있어야 해요.
  • 트레이스된 서비스에 대응하는 메트릭(예: requests_total, request_duration_seconds)이 있어야 해요.
  • Grafana에서 Editor 또는 Admin 권한이 있어야 해요.

Note: 프로비저닝된 데이터 소스는 Grafana UI에서 수정할 수 없어요. Grafana Cloud Traces(사전 구성된 추적 데이터 소스)를 쓰는 경우 설정은 읽기 전용이에요. trace to metrics를 구성하려면 데이터 소스를 복제해 편집 가능한 사본을 만들거나, 자체 관리 인스턴스의 프로비저닝 파일을 업데이트하세요.

trace to metrics 기능을 구성하는 방법은 두 가지예요:

  • 기본 쿼리를 사용하는 기본 구성.
  • 트레이스나 스팬의 변수를 보간(interpolation)하는 템플릿 언어를 쓸 수 있는 하나 이상의 커스텀 쿼리 구성.

기본 구성 설정

  1. Data source 드롭다운에서 메트릭 데이터 소스를 선택해요.
  2. 선택: Span start time shift와 Span end time shift를 변경해요. 플레이스홀더는 -2m(시작)과 2m(끝)을 보여주며, 필드를 비워두면 적용돼요.
  3. 선택: 쿼리에 사용할 태그를 골라요. Add tag를 클릭해 태그 매핑을 추가해요. 구성한 태그는 trace-to-metrics 스팬 링크가 나타나려면 스팬 속성이나 리소스에 존재해야 해요. 태그에 새 이름을 구성할 수도 있는데, 태그 이름에 점이 있고 대상 데이터 소스가 라벨에 점을 허용하지 않을 때 유용해요. 예: service.name을 service_name으로 재매핑.
  4. Add query를 선택하지 마세요.
  5. Save and Test를 선택해요.

커스텀 쿼리 설정

커스텀 쿼리를 쓰려면 연결된 쿼리에 포함할 태그를 구성해야 해요. 각 태그의 key는 스팬 속성 이름이에요. 속성 이름이 유효하지 않은 메트릭 쿼리를 만들거나 원하는 라벨 이름과 정확히 일치하지 않는 경우에는 두 번째 값으로 라벨 이름을 입력할 수 있어요. 예를 들어 속성 k8s.pod를 라벨 pod로 매핑할 수 있어요.

구성된 태그는 $__tags 키워드로 보간할 수 있어요. 예를 들어 태그 k8s.pod=pod와 cluster로 requests_total{$__tags} 쿼리를 구성하면 결과가 requests_total{pod="nginx-554b9", cluster="us-east-1"}처럼 나와요. 라벨 값은 스팬 속성의 값에 따라 동적으로 삽입돼요. 서비스나 스팬으로 필터링된 스팬 지속 시간·개수·오류 메트릭에 링크하는 것이 좋은 출발점이에요.

구성과 함께 커스텀 쿼리를 사용하려면:

  1. Data source 드롭다운에서 메트릭 데이터 소스를 선택해요.
  2. 선택: 쿼리에 사용할 태그를 골라요. Add tag를 클릭해 태그 매핑을 추가해요. 이 태그들은 ${__tags} 변수로 커스텀 쿼리에서 쓸 수 있어요. 이 변수는 매핑된 태그를 데이터 소스에 적합한 문법의 목록으로 보간하며, 스팬에 있던 태그만 포함하고 없던 건 생략해요. 선택적으로 태그에 새 이름을 구성할 수 있어요(점 포함 이름 제한 등). 태그를 매핑하지 않아도 method="${__span.tags.method}"처럼 쿼리에서 어떤 태그든 쓸 수 있어요. 사용 가능한 변수 전체 목록은 "Custom query variables" 문서를 참고하세요.
  3. Add query를 클릭해 커스텀 쿼리를 추가해요.
  4. 메트릭 데이터를 쿼리하는 데 쓸 커스텀 쿼리를 지정해요.

각 연결된 쿼리는 다음으로 구성돼요:

  • Link Label: (선택) 연결된 쿼리에 대한 설명 라벨.
  • Query: 트레이스에서 메트릭 데이터 소스로 이동할 때 실행되는 쿼리. $__tags 키워드로 태그를 보간해요. 예: 태그 k8s.pod=pod와 cluster로 requests_total{$__tags} 쿼리를 구성하면 requests_total{pod="nginx-554b9", cluster="us-east-1"}처럼 나와요.
  1. Save and Test를 선택해요.

구성 옵션

Setting name Description
Data source 대상 데이터 소스를 정의해요.
Span start time shift 스팬 시작 시간을 기준으로 메트릭 쿼리의 시작 시간을 이동해요. 5s, 1m, 3h 같은 시간 단위를 사용할 수 있어요. 과거로 확장하려면 음수 값을 써요. 기본: -2m.
Span end time shift 스팬 종료 시간을 기준으로 메트릭 쿼리의 종료 시간을 이동해요. 시간 단위를 사용할 수 있어요. 기본: 2m.
Tags 연결된 쿼리에 사용되는 태그를 정의해요. key는 스팬 속성 이름을, 선택적 value는 대응하는 메트릭 라벨 이름을 설정해요. 예: k8s.pod를 pod로. 이 태그를 쿼리에 보간하려면 $__tags 키워드를 써요.
Link Label (선택) 연결된 쿼리에 대한 설명 라벨.
Query 커스텀 쿼리를 작성하는 입력. 스팬의 변수로 커스터마이즈하려면 변수 보간을 사용해요.

프로비저닝

데이터 소스 YAML 파일의 tracesToMetrics 블록으로 trace to metrics 구성을 프로비저닝할 수 있어요. 모든 Tempo 설정을 포함한 전체 프로비저닝 YAML 예제는 "Provision the Tempo data source" 문서를 참고하세요.

메트릭에서 트레이스로 링크하기

반대 방향(메트릭에서 연결된 트레이스로)으로 이동하려면 Prometheus 데이터 소스에서 exemplars(엑스플러)를 구성하세요. 설정 방법은 "Exemplars" 문서를 참고해요.

문제 해결

trace to metrics 링크가 나타나지 않거나 데이터가 없으면 트러블슈팅 가이드의 "Trace to logs/metrics/profiles issues"를 참고하세요. 구성 필드가 회색으로 표시되면 데이터 소스가 프로비저닝된 것이므로 YAML로 구성을 업데이트하려면 Provisioning 섹션을 참고해요.

다음 단계

더 알아보기 (Learn more)