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

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

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

Сведения о настройке корреляции логов в интерфейсе Knowledge Graph см. в разделе Configure logs correlation.

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

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

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

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

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

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

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

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

terraform 
# 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   = []
  }
}

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

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

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

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

Аргументы

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

Блок match

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

Имя Тип Обязательный Описание
property string Да Свойство сущности, с которым выполняется сопоставление.
op string Да Операция, используемая для сопоставления. Одна из: EQUALS, NOT_EQUALS, CONTAINS, DOES_NOT_CONTAIN, IS_NULL, IS_NOT_NULL.
values list(string) Да Значения, с которыми выполняется сопоставление. Может быть пустым для операций IS_NULL и IS_NOT_NULL.

Пример

terraform 
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 или системе агрегации логов
  • Проверьте подключение к источнику данных перед применением конфигураций
  • Используйте описательные имена для конфигураций логов, отражающие их назначение
  • Рассмотрите использование отдельных источников данных для разных сред

Стратегия сопоставления меток

  • Сопоставляйте свойства сущностей единообразно во всех конфигурациях логов
  • Используйте осмысленные имена меток логов, соответствующие вашим стандартам логирования
  • Документируйте связи сопоставления в комментариях к конфигурации
  • Убедитесь, что сопоставленные метки присутствуют в ваших данных логов

Проектирование правил сопоставления

  • Начинайте с широких правил сопоставления и уточняйте их по мере необходимости
  • Используйте конкретные имена свойств, которые есть в вашей модели сущностей
  • Проверяйте правила сопоставления на образцах данных перед развёртыванием
  • Комбинируйте несколько правил сопоставления для точного нацеливания на сущности

Интеграция с распределённой трассировкой

  • Включайте filter_by_span_id и filter_by_trace_id при использовании OpenTelemetry
  • Убедитесь, что ваши логи содержат соответствующие метки ID трейса и спана
  • Используйте согласованные имена меток для ID трейсов во всей инфраструктуре логирования
  • Проверяйте корреляцию трейсов, чтобы убедиться, что она работает как ожидается

Проверка

После применения конфигурации Terraform убедитесь, что:

  • Конфигурации логов созданы в вашем экземпляре Knowledge Graph
  • Конфигурации отображаются в интерфейсе Knowledge Graph в разделе Observability > Configuration > Logs
  • Корреляция логов работает при детализации от сущностей
  • Сопоставления меток корректно преобразуют свойства сущностей в метки логов
  • Правила сопоставления правильно фильтруют сущности
  • Фильтрация по ID трейса и спана работает для распределённой трассировки

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