Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Как кодbreadcrumb arrow Инфраструктура как кодbreadcrumb arrow Terraformbreadcrumb arrow Управление Knowledge Graph в Grafana Cloud с помощью Terraformbreadcrumb arrow Trace configurations

Настройка корреляции трассировок с помощью Terraform

Конфигурации трассировок в Knowledge Graph позволяют определить, как данные трассировок запрашиваются и сопоставляются с сущностями. Вы можете указать источники данных, правила сопоставления сущностей и сопоставления меток для распределённой трассировки.

Информацию о настройке корреляции трассировок в интерфейсе Knowledge Graph см. в разделе Configure traces correlation.

Базовая конфигурация трассировок

Создайте файл с именем trace-configs.tf и добавьте следующее:

terraform 
# 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"
  }
}

Конфигурация трассировок с несколькими правилами сопоставления

Настройте корреляцию трассировок с несколькими критериями сопоставления сущностей:

terraform 
# 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"
  }
}

Минимальная конфигурация трассировок

Создайте минимальную конфигурацию для всех сущностей:

terraform 
# 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"
  }
}

Расширенная конфигурация трассировок со сложными правилами сопоставления

Настройте трассировки с несколькими операциями и расширенными правилами сопоставления:

terraform 
# 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

Управляйте конфигурациями трассировок Knowledge Graph через Grafana API.

Аргументы

Имя Тип Обязательный Описание
name string Да Имя конфигурации трассировок. Это поле неизменяемо и вызывает пересоздание ресурса при изменении.
priority number Да Приоритет конфигурации трассировок. Меньшее число означает более высокий приоритет.
default_config bool Да Является ли эта конфигурация конфигурацией по умолчанию. Конфигурации по умолчанию нельзя удалить.
data_source_uid string Да UID источника данных для запроса (например, экземпляр Tempo).
match list(object) Нет Список правил сопоставления для свойств сущностей. Подробнее см. блок match.
entity_property_to_trace_label_mapping map(string) Нет Сопоставление свойств сущностей с метками трассировок для корреляции.

Блок match

Каждый блок match поддерживает следующее:

Имя Тип Обязательный Описание
property string Да Свойство сущности, с которым выполняется сопоставление.
op string Да Операция, используемая для сопоставления. Одна из: =, <>, <, >, <=, >=, IS NULL, IS NOT NULL, STARTS WITH, CONTAINS.
values list(string) Да Значения для сопоставления. Может быть пустым для операций IS NULL и IS NOT NULL.

Пример

terraform 
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 в разделе Observability > Configuration > Traces
  • Корреляция трассировок работает при детализации от сущностей
  • Сопоставления меток корректно преобразуют свойства сущностей в атрибуты ресурсов трассировок
  • Правила сопоставления правильно фильтруют сущности
  • Запросы трассировок возвращают ожидаемые результаты в интерфейсе Knowledge Graph

Связанная документация