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

Создание пользовательских правил модели с помощью Terraform

Пользовательские правила модели в Knowledge Graph позволяют определить, как сущности обнаруживаются и моделируются на основе запросов Prometheus. Эти правила дают возможность создавать собственные типы сущностей, задавать их взаимосвязи и указывать, как они должны обогащаться дополнительными данными.

Сведения об управлении сущностями и связями в интерфейсе Knowledge Graph см. в разделе Manage entities and relations.

Базовые пользовательские правила модели

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

terraform 
# Basic custom model rule for services
resource "grafana_asserts_custom_model_rules" "basic_service" {
  provider = grafana.asserts

  name = "basic-service-model"

  rules {
    entity {
      type = "Service"
      name = "service"

      defined_by {
        query = "up{job!=''}"
        label_values = {
          service = "job"
        }
        literals = {
          _source = "up_query"
        }
      }
    }
  }
}

Расширенная модель сервиса с областью действия и поиском

Определите сущности сервисов с ограничением по среде и сопоставлениями связей:

terraform 
# Advanced service model with environment scoping
resource "grafana_asserts_custom_model_rules" "advanced_service" {
  provider = grafana.asserts

  name = "advanced-service-model"

  rules {
    entity {
      type = "Service"
      name = "workload | service | job"

      scope = {
        namespace = "namespace"
        env       = "asserts_env"
        site      = "asserts_site"
      }

      lookup = {
        workload  = "workload | deployment | statefulset | daemonset | replicaset"
        service   = "service"
        job       = "job"
        proxy_job = "job"
      }

      defined_by {
        query = "up{job!='', asserts_env!=''}"
        label_values = {
          service     = "service"
          job         = "job"
          workload    = "workload"
          namespace   = "namespace"
        }
        literals = {
          _source = "up_with_workload"
        }
      }

      defined_by {
        query    = "up{job='maintenance'}"
        disabled = true
      }
    }
  }
}

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

Определите несколько типов сущностей в одной конфигурации:

terraform 
# Multiple entity types in a single model
resource "grafana_asserts_custom_model_rules" "multi_entity" {
  provider = grafana.asserts

  name = "kubernetes-entities"

  rules {
    # Service entity
    entity {
      type = "Service"
      name = "service"

      scope = {
        namespace = "namespace"
        cluster   = "cluster"
      }

      defined_by {
        query = "up{service!=''}"
        label_values = {
          service   = "service"
          namespace = "namespace"
          cluster   = "cluster"
        }
      }
    }

    # Pod entity
    entity {
      type = "Pod"
      name = "Pod"

      scope = {
        namespace = "namespace"
        cluster   = "cluster"
      }

      lookup = {
        service   = "service"
        workload  = "workload"
      }

      defined_by {
        query = "kube_pod_info{pod!=''}"
        label_values = {
          Pod       = "pod"
          namespace = "namespace"
          cluster   = "cluster"
          service   = "service"
        }
        literals = {
          _entity_type = "Pod"
        }
      }
    }

    # Namespace entity
    entity {
      type = "Namespace"
      name = "namespace"

      scope = {
        cluster = "cluster"
      }

      defined_by {
        query = "kube_namespace_status_phase{namespace!=''}"
        label_values = {
          namespace = "namespace"
          cluster   = "cluster"
        }
      }
    }
  }
}

Сложная сущность с обогащением

Создайте сущности сервисов с несколькими источниками данных и обогащением:

terraform 
# Service entity with enrichment from multiple sources
resource "grafana_asserts_custom_model_rules" "enriched_service" {
  provider = grafana.asserts

  name = "enriched-service-model"

  rules {
    entity {
      type = "Service"
      name = "service"

      enriched_by = [
        "prometheus_metrics",
        "kubernetes_metadata",
        "application_logs"
      ]

      scope = {
        environment = "asserts_env"
        region      = "asserts_site"
        team        = "team"
      }

      lookup = {
        deployment = "workload"
        Pod        = "pod"
        container  = "container"
      }

      # Primary definition from service up metrics
      defined_by {
        query = "up{service!='', asserts_env!=''}"
        label_values = {
          service     = "service"
          environment = "asserts_env"
          region      = "asserts_site"
          team        = "team"
        }
        literals = {
          _primary_source = "service_up"
        }
      }

      # Secondary definition from application metrics
      defined_by {
        query = "http_requests_total{service!=''}"
        label_values = {
          service     = "service"
          environment = "environment"
          version     = "version"
        }
        literals = {
          _secondary_source = "http_metrics"
        }
      }

      # Disabled definition for testing
      defined_by {
        query    = "test_metric{service!=''}"
        disabled = true
      }
    }
  }
}

Сущности баз данных и инфраструктуры

Определите модели сущностей баз данных и инфраструктуры:

terraform 
# Database and infrastructure entity models
resource "grafana_asserts_custom_model_rules" "infrastructure" {
  provider = grafana.asserts

  name = "infrastructure-entities"

  rules {
    # Database entity
    entity {
      type = "Database"
      name = "database_instance"

      scope = {
        environment = "env"
        region      = "region"
      }

      lookup = {
        host     = "instance"
        port     = "port"
        db_name  = "database"
      }

      defined_by {
        query = "mysql_up{instance!=''}"
        label_values = {
          database_instance = "instance"
          database         = "database"
          env             = "environment"
          region          = "region"
        }
        literals = {
          _db_type = "mysql"
        }
        metric_value = "1"
      }

      defined_by {
        query = "postgres_up{instance!=''}"
        label_values = {
          database_instance = "instance"
          database         = "datname"
          env             = "environment"
        }
        literals = {
          _db_type = "postgresql"
        }
      }
    }

    # Load balancer entity
    entity {
      type = "LoadBalancer"
      name = "lb_instance"

      scope = {
        environment = "env"
      }

      defined_by {
        query = "haproxy_up{proxy!=''}"
        label_values = {
          lb_instance = "instance"
          proxy      = "proxy"
          env        = "environment"
        }
        literals = {
          _lb_type = "haproxy"
        }
      }
    }
  }
}

Справочник по ресурсам

grafana_asserts_custom_model_rules

Управление пользовательскими правилами модели Knowledge Graph через API Grafana. Этот ресурс позволяет определять собственные модели сущностей на основе запросов Prometheus с расширенными возможностями сопоставления и обогащения.

Аргументы

Имя Тип Обязательный Описание
name string Да Имя пользовательских правил модели. Это поле неизменяемо и при изменении приводит к пересозданию ресурса.
rules list(object) Да Конфигурация правил, содержащая определения сущностей. Подробнее см. в разделе блок rules.

Блок rules

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

Имя Тип Обязательный Описание
entity list(object) Да Список определений сущностей. Подробнее см. в разделе блок entity.

Блок entity

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

Имя Тип Обязательный Описание
type string Да Тип сущности (например, Service, Pod, Namespace).
name string Да Шаблон имени сущности. Может включать альтернативы, разделённые вертикальной чертой.
defined_by list(object) Да Список запросов, определяющих эту сущность. Подробнее см. в разделе блок defined_by.
disabled bool Нет Отключена ли эта сущность. По умолчанию false.
enriched_by list(string) Нет Список источников обогащения для сущности.
lookup map(string) Нет Сопоставления поиска для связи различных имён меток сущности.
scope map(string) Нет Метки области действия, определяющие границы этого типа сущности.

Блок defined_by

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

Имя Тип Обязательный Описание
query string Да Запрос Prometheus, определяющий эту сущность.
disabled bool Нет Отключён ли этот запрос. По умолчанию false.
label_values map(string) Нет Сопоставления значений меток для извлечения атрибутов сущности из результатов запроса.
literals map(string) Нет Сопоставления литеральных значений для добавления статических атрибутов сущностям.
metric_value string Нет Значение метрики, которое следует использовать из результата запроса.

Note

Когда для запроса defined_by задано disabled = true, для сопоставления используется только поле query. Все остальные поля блока игнорируются.

Рекомендации

При создании пользовательских правил модели с помощью Terraform учитывайте следующие рекомендации.

Модели сущностей

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

Проектирование запросов и производительность

  • Пишите эффективные запросы Prometheus, которые не перегружают вашу систему мониторинга
  • Тестируйте запросы Prometheus отдельно, прежде чем использовать их в правилах модели
  • Используйте конкретные фильтры по меткам, чтобы по возможности сократить область действия запросов
  • Учитывайте влияние кардинальности ваших определений сущностей
  • Используйте флаг disabled, чтобы временно отключить проблемные запросы во время отладки

Связи и обогащение

  • Используйте сопоставления lookup для установления связей между различными типами сущностей
  • Задействуйте enriched_by, чтобы указать дополнительные источники данных для обогащения сущностей
  • Сопоставляйте метки Prometheus с атрибутами сущностей, используя понятные и описательные имена
  • Используйте осмысленные literals для добавления статических метаданных, помогающих идентифицировать сущности

Управление метками и атрибутами

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

Проверка

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

  • Пользовательские правила модели применены в вашем экземпляре Knowledge Graph
  • Сущности обнаруживаются в соответствии с заданными запросами
  • Связи сущностей и обогащение работают должным образом
  • Графы сущностей отображают правильные типы сущностей и связи
  • Запросы выполняются эффективно и не создают чрезмерной нагрузки

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