Terraform으로 트레이스 상관관계(trace correlation) 구성

Terraform으로 트레이스 상관관계(trace correlation) 구성

Knowledge Graph의 트레이스 구성(trace configurations)을 사용하면 트레이스 데이터를 어떻게 쿼리하고 엔티티와 상관시키는지 정의할 수 있어요. 분산 추적을 위한 데이터 소스, 엔티티 매칭 규칙, 라벨 매핑을 지정할 수 있어요.

Knowledge Graph UI에서 트레이스 상관관계를 구성하는 방법에 대한 자세한 내용은 트레이스 상관관계 구성 문서를 참고하세요.

출처: 문서

본문

기본 트레이스 구성

trace-configs.tf라는 파일을 만들고 다음 내용을 추가하세요:

# Basic trace configuration for services
resource "grafana_asserts_trace_config" "production" {
  provider = grafana.asserts

  name            = "production"
  priority        = 1000
  default_config  = false
  data_source_uid = "grafanacloud-traces"

  match {
    property = "asserts_entity_type"
    op       = "="
    values   = ["Service"]
  }

  match {
    property = "deployment_environment"
    op       = "="
    values   = ["production", "staging"]
  }

  entity_property_to_trace_label_mapping = {
    "cluster"        = "resource.k8s.cluster.name"
    "namespace"      = "resource.k8s.namespace"
    "container"      = "resource.container.name"
    "otel_service"   = "resource.service.name"
    "otel_namespace" = "resource.service.namespace"
  }
}

여러 매치 규칙이 있는 트레이스 구성

여러 엔티티 매칭 기준으로 트레이스 상관관계를 구성하세요:

# Development environment trace configuration
resource "grafana_asserts_trace_config" "development" {
  provider = grafana.asserts

  name            = "development"
  priority        = 2000
  default_config  = false
  data_source_uid = "tempo-dev"

  match {
    property = "asserts_entity_type"
    op       = "="
    values   = ["Service"]
  }

  match {
    property = "deployment_environment"
    op       = "="
    values   = ["development", "testing"]
  }

  match {
    property = "asserts_site"
    op       = "="
    values   = ["us-east-1"]
  }

  match {
    property = "service"
    op       = "="
    values   = ["api"]
  }

  entity_property_to_trace_label_mapping = {
    "cluster"        = "resource.k8s.cluster.name"
    "namespace"      = "resource.k8s.namespace"
    "container"      = "resource.container.name"
    "otel_service"   = "resource.service.name"
    "otel_namespace" = "resource.service.namespace"
    "pod"            = "span.k8s.pod.name"
  }
}

최소 트레이스 구성

모든 엔티티에 대한 최소 구성 만들기:

# Minimal configuration for all entities
resource "grafana_asserts_trace_config" "minimal" {
  provider = grafana.asserts

  name            = "minimal"
  priority        = 3000
  default_config  = false
  data_source_uid = "tempo-minimal"

  match {
    property = "asserts_entity_type"
    op       = "IS NOT NULL"
    values   = []
  }

  entity_property_to_trace_label_mapping = {
    "cluster"        = "resource.k8s.cluster.name"
    "otel_service"   = "resource.service.name"
    "otel_namespace" = "resource.service.namespace"
  }
}

복잡한 매치 규칙이 있는 고급 트레이스 구성

여러 연산과 고급 매치 규칙으로 트레이스를 구성하세요:

# Advanced configuration with multiple operations
resource "grafana_asserts_trace_config" "advanced" {
  provider = grafana.asserts

  name            = "advanced"
  priority        = 1500
  default_config  = false
  data_source_uid = "tempo-advanced"

  match {
    property = "service_type"
    op       = "CONTAINS"
    values   = ["web", "api"]
  }

  match {
    property = "deployment_environment"
    op       = "<>"
    values   = ["test"]
  }

  match {
    property = "team"
    op       = "IS NOT NULL"
    values   = []
  }

  match {
    property = "priority_level"
    op       = ">="
    values   = ["5"]
  }

  entity_property_to_trace_label_mapping = {
    "service_type"   = "resource.service.type"
    "team"           = "resource.team.owner"
    "environment"    = "resource.deployment.environment"
    "version"        = "resource.service.version"
    "region"         = "resource.cloud.region"
  }
}

리소스 참조

grafana_asserts_trace_config

Grafana API를 통해 Knowledge Graph 트레이스 구성을 관리해요.

인자(Arguments)

Match 블록

각 match 블록은 다음을 지원해요:

예시

resource "grafana_asserts_trace_config" "example" {
  provider = grafana.asserts

  name            = "example-traces"
  priority        = 1000
  default_config  = false
  data_source_uid = "tempo-prod"

  match {
    property = "asserts_entity_type"
    op       = "="
    values   = ["Service", "Pod"]
  }

  match {
    property = "deployment_environment"
    op       = "STARTS WITH"
    values   = ["prod"]
  }

  entity_property_to_trace_label_mapping = {
    "service"     = "resource.service.name"
    "namespace"   = "resource.k8s.namespace"
    "environment" = "resource.deployment.environment"
    "cluster"     = "resource.k8s.cluster.name"
  }
}

모범 사례

Terraform으로 트레이스 상관관계를 구성할 때 다음 모범 사례를 고려하세요.

우선순위 관리

• 더 구체적인 구성에 더 낮은 우선순위 번호를 할당하세요.
• 우선순위 번호가 낮을수록 우선순위가 높아요(구성은 오름차순 우선순위 순서로 평가됨).
• 서로 다른 구성 유형에 대해 일관된 우선순위 범위를 사용하세요.
• 우선순위 할당의 근거를 문서화하세요.

데이터 소스 구성

• 데이터 소스 UID가 실제 Tempo 또는 트레이스 집계 시스템과 일치하는지 확인하세요.
• 구성을 적용하기 전에 데이터 소스 연결을 테스트하세요.
• 트레이스 구성의 목적을 나타내는 설명적인 이름을 사용하세요.
• 환경마다 별도의 데이터 소스를 사용하는 것을 고려하세요.

라벨 매핑 전략

• 모든 트레이스 구성에서 엔티티 속성을 일관되게 매핑하세요.
• 트레이스 라벨 이름에 OpenTelemetry 시맨틱 규약을 사용하세요(예: resource.service.name, resource.k8s.namespace).
• 구성 주석에 매핑 관계를 문서화하세요.
• 매핑된 라벨이 트레이스 데이터에 존재하는지 확인하세요.

매치 규칙 설계

• 광범위한 매치 규칙으로 시작하고 필요에 따라 다듬으세요.
• 엔티티 모델에 존재하는 구체적인 속성 이름을 사용하세요.
• 배포 전에 샘플 데이터로 매치 규칙을 테스트하세요.
• 정밀한 엔티티 타기팅을 위해 여러 매치 규칙을 결합하세요.
• 숫자 또는 버전 기반 필터링을 위해 비교 연산자(>, >=)를 활용하세요.

분산 추적 통합

• 트레이스가 OpenTelemetry 시맨틱 규약을 따르는지 확인하세요.
• 추적 인프라 전반에 걸쳐 리소스 속성에 일관된 라벨 이름을 사용하세요.
• 포괄적인 상관관계를 위해 서비스 수준과 인프라 수준 속성을 모두 매핑하세요.
• 예상대로 작동하는지 트레이스 상관관계를 테스트하세요.

검증

Terraform 구성을 적용한 후 다음을 확인하세요:

• 트레이스 구성이 Knowledge Graph 인스턴스에 생성되었는지.
• 구성이 Knowledge Graph UI의 Observability > Configuration > Traces 아래에 나타나는지.
• 엔티티에서 드릴다운할 때 트레이스 상관관계가 작동하는지.
• 라벨 매핑이 엔티티 속성을 트레이스 리소스 속성으로 올바르게 변환하는지.
• 매치 규칙이 엔티티를 올바르게 필터링하는지.
• 트레이스 쿼리가 Knowledge Graph UI에서 예상 결과를 반환하는지.

관련 문서

• Knowledge Graph에서 트레이스 상관관계 구성
• Knowledge Graph용 Terraform 시작하기
• Tempo 문서
• OpenTelemetry 시맨틱 규약

더 알아보기 (Learn more)

• Knowledge Graph용 Terraform
• Knowledge Graph 트레이스 상관관계