Terraform으로 로그 상관관계(log correlation) 구성

Terraform으로 로그 상관관계(log correlation) 구성

Knowledge Graph의 로그 구성(log configurations)을 사용하면 로그 데이터를 어떻게 쿼리하고 엔티티와 상관시키는지 정의할 수 있어요. span과 trace에 대한 데이터 소스, 엔티티 매칭 규칙, 라벨 매핑, 필터링 옵션을 지정할 수 있어요.

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

출처: 문서

본문

기본 로그 구성

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

# Basic log configuration for services
resource "grafana_asserts_log_config" "production" {
  provider = grafana.asserts

  name            = "production"
  priority        = 1000
  default_config  = false
  data_source_uid = "grafanacloud-logs"
  error_label     = "error"

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

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

  entity_property_to_log_label_mapping = {
    "otel_namespace" = "service_namespace"
    "otel_service"   = "service_name"
    "environment"    = "env"
    "site"           = "region"
  }

  filter_by_span_id  = true
  filter_by_trace_id = true
}

여러 매치 규칙이 있는 로그 구성

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

# Development environment log configuration
resource "grafana_asserts_log_config" "development" {
  provider = grafana.asserts

  name            = "development"
  priority        = 2000
  default_config  = true
  data_source_uid = "elasticsearch-dev"
  error_label     = "error"

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

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

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

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

  entity_property_to_log_label_mapping = {
    "otel_namespace" = "service_namespace"
    "otel_service"   = "service_name"
    "environment"    = "env"
    "site"           = "region"
    "service"        = "app"
  }

  filter_by_span_id  = true
  filter_by_trace_id = true
}

최소 로그 구성

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

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

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

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

복잡한 매치 규칙이 있는 고급 로그 구성

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

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

  name            = "advanced"
  priority        = 1500
  default_config  = false
  data_source_uid = "loki-advanced"
  error_label     = "level"

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

  match {
    property = "environment"
    op       = "NOT_EQUALS"
    values   = ["test"]
  }

  match {
    property = "team"
    op       = "IS_NOT_NULL"
    values   = []
  }

  entity_property_to_log_label_mapping = {
    "service_type"   = "type"
    "team"           = "owner"
    "environment"    = "env"
    "version"        = "app_version"
  }

  filter_by_span_id  = true
  filter_by_trace_id = false
}

리소스 참조

grafana_asserts_log_config

Grafana API를 통해 Knowledge Graph 로그 구성을 관리해요.

인자(Arguments)

Match 블록

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

예시

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

  name            = "example-logs"
  priority        = 1000
  default_config  = false
  data_source_uid = "loki-prod"
  error_label     = "level"

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

  entity_property_to_log_label_mapping = {
    "service"     = "app"
    "namespace"   = "k8s_namespace"
    "environment" = "env"
  }

  filter_by_span_id  = true
  filter_by_trace_id = true
}

모범 사례

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

우선순위 관리

• 더 구체적인 구성에 더 낮은 우선순위 번호를 할당하세요.
• 우선순위가 높은 구성이 먼저 평가돼요.
• 서로 다른 구성 유형에 대해 일관된 우선순위 범위를 사용하세요.
• 우선순위 할당의 근거를 문서화하세요.

데이터 소스 구성

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

라벨 매핑 전략

• 모든 로그 구성에서 엔티티 속성을 일관되게 매핑하세요.
• 로깅 표준과 일치하는 의미 있는 로그 라벨 이름을 사용하세요.
• 구성 주석에 매핑 관계를 문서화하세요.
• 매핑된 라벨이 로그 데이터에 존재하는지 확인하세요.

매치 규칙 설계

• 광범위한 매치 규칙으로 시작하고 필요에 따라 다듬으세요.
• 엔티티 모델에 존재하는 구체적인 속성 이름을 사용하세요.
• 배포 전에 샘플 데이터로 매치 규칙을 테스트하세요.
• 정밀한 엔티티 타기팅을 위해 여러 매치 규칙을 결합하세요.

분산 추적 통합

• OpenTelemetry를 사용할 때 filter_by_span_id와 filter_by_trace_id를 활성화하세요.
• 로그에 적절한 trace 및 span ID 라벨이 포함되어 있는지 확인하세요.
• 로깅 인프라 전반에 걸쳐 trace ID에 일관된 라벨 이름을 사용하세요.
• 예상대로 작동하는지 trace 상관관계를 테스트하세요.

검증

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

• 로그 구성이 Knowledge Graph 인스턴스에 생성되었는지.
• 구성이 Knowledge Graph UI의 Observability > Configuration > Logs 아래에 나타나는지.
• 엔티티에서 드릴다운할 때 로그 상관관계가 작동하는지.
• 라벨 매핑이 엔티티 속성을 로그 라벨로 올바르게 변환하는지.
• 매치 규칙이 엔티티를 올바르게 필터링하는지.
• 분산 추적에 대해 trace 및 span ID 필터링이 작동하는지.

관련 문서

• Knowledge Graph에서 로그 상관관계 구성
• Knowledge Graph용 Terraform 시작하기
• Loki 문서

더 알아보기 (Learn more)

• Knowledge Graph용 Terraform
• Knowledge Graph 로그 상관관계