Прием данных из Telegraf в Azure Data Explorer

Azure Data Explorer (ADX) поддерживает прием данных из Telegraf. Telegraf — это агент печати с открытым исходным кодом, упрощенным и минимальным объемом памяти. Telegraf используется для сбора, обработки и записи данных телеметрии, включая журналы, метрики и данные Интернета вещей.

Telegraf поддерживает сотни подключаемых модулей ввода и вывода. Она широко используется, и сообщество с открытым исходным кодом поддерживает его.

Коннектор ADX Azure Data Explorer служит коннектором для Telegraf и поддерживает передачу данных из многих типов входных модулей в Azure Data Explorer.

Prerequisites

• Подписка Azure. Создайте бесплатную учетную запись Azure.
• Кластер и база данных Azure Data Explorer. Создайте кластер и базу данных.
• Telegraf. Разместите Telegraf в виртуальной машине или контейнере. Telegraf можно размещать локально, где развертывается приложение или служба, либо удаленно в выделенном контейнере или вычислительном ресурсе мониторинга.

Поддерживаемые методы проверки подлинности

Подключаемый модуль поддерживает следующие методы проверки подлинности:

• Приложения Microsoft Entra с ключами приложений или сертификатами.

  • Сведения о создании и регистрации приложения в идентификаторе Microsoft Entra см. в разделе "Регистрация приложения".
  • Сведения о субъектах-службах см. в разделе "Объекты приложения и субъекта-службы" в идентификаторе Microsoft Entra.

• Токены пользователей Microsoft Entra

  • Позволяет подключаемому модулю проходить проверку подлинности, как пользователь. Используйте этот метод только для разработки.

• Маркер Управляемого удостоверения службы (MSI)

  • Предпочтительный метод проверки подлинности, если вы используете Telegraf в поддерживаемой среде Azure, например виртуальные машины Azure.

Независимо от используемого метода назначенный субъект должен быть назначен роли пользователя базы данных в Azure Data Explorer. Эта роль позволяет подключаемому модулю создавать таблицы, необходимые для приема данных. Если подключаемый модуль настроен с create_tables=falseпомощью, назначенный субъект должен иметь по крайней мере роль Ingestor базы данных .

Настройка метода проверки подлинности

Подключаемый модуль проверяет конкретные конфигурации переменных среды, чтобы определить, какой метод проверки подлинности следует использовать. Конфигурации оцениваются в указанном порядке. Используется первая обнаруженная конфигурация. Если допустимая конфигурация не обнаружена, подключаемый модуль не проходит проверку подлинности.

Чтобы настроить проверку подлинности для подключаемого модуля, задайте соответствующие переменные среды для выбранного метода проверки подлинности:

• Учетные данные клиента (токены приложений Microsoft Entra) — идентификатор приложения Microsoft Entra и секрет.

  • AZURE_TENANT_ID: идентификатор клиента Microsoft Entra, используемый для проверки подлинности.
  • AZURE_CLIENT_ID: идентификатор клиента для регистрации приложения в арендаторе.
  • AZURE_CLIENT_SECRET: секрет клиента, созданный для регистрации приложения.

• Сертификат клиента (токены приложения Microsoft Entra): идентификатор приложения Microsoft Entra и сертификат X.509.

  • AZURE_TENANT_ID: идентификатор клиента Microsoft Entra, используемый для проверки подлинности.
  • AZURE_CERTIFICATE_PATH: путь к сертификату и паре закрытых ключей в формате PEM или PFX для проверки подлинности регистрации приложения.
  • AZURE_CERTIFICATE_PASSWORD: пароль, заданный для сертификата.

• Пароль владельца ресурса (токены пользователей Microsoft Entra) — пользователь и пароль Microsoft Entra. Рекомендуем использовать этот тип предоставления разрешения. Если требуется интерактивный вход, используйте имя для входа устройства.

  • AZURE_TENANT_ID: идентификатор клиента Microsoft Entra, используемый для проверки подлинности.
  • AZURE_CLIENT_ID: идентификатор клиента для регистрации приложения в арендаторе.
  • AZURE_USERNAME: имя пользователя, также известное как upn, учетной записи пользователя Microsoft Entra.
  • AZURE_PASSWORD: пароль учетной записи пользователя Microsoft Entra. Примечание. Эта функция не поддерживает учетные записи с поддержкой многофакторной проверки подлинности (MFA).

• Управляемое удостоверение службы Azure: делегирование управления учетными данными платформе. Запустите код в Azure, например на виртуальной машине. Azure обрабатывает всю конфигурацию. Дополнительные сведения см. в статье Управляемое удостоверение службы Azure. Этот способ доступен только при использовании Azure Resource Manager.

Настройка Telegraf

Telergraf — это управляемый конфигурацией агент. Чтобы приступить к работе, необходимо установить Telegraf и настроить необходимые подключаемые модули ввода и вывода. Расположение файла конфигурации по умолчанию выглядит так:

• Для Windows: C:\Program Files\Telegraf\telegraf.conf
• Для Linux: etc/telegraf/telegraf.conf

Чтобы включить подключаемый модуль вывода Azure Data Explorer, необходимо раскомментировать следующий раздел в автоматически созданном файле конфигурации:

[[outputs.azure_data_explorer]]
  ## The URI property of the Azure Data Explorer resource on Azure
  ## ex: https://myadxresource.australiasoutheast.kusto.windows.net
  # endpoint_url = ""

  ## The Azure Data Explorer database that the metrics will be ingested into.
  ## The plugin will NOT generate this database automatically, it's expected that this database already exists before ingestion.
  ## ex: "exampledatabase"
  # database = ""

  ## Timeout for Azure Data Explorer operations, default value is 20 seconds
  # timeout = "20s"

  ## Type of metrics grouping used when ingesting to Azure Data Explorer
  ## Default value is "TablePerMetric" which means there will be one table for each metric
  # metrics_grouping_type = "TablePerMetric"

  ## Name of the single table to store all the metrics (Only needed if metrics_grouping_type is "SingleTable").
  # table_name = ""

  ## Creates tables and relevant mapping if set to true(default).
  ## Skips table and mapping creation if set to false, this is useful for running telegraf with the least possible access permissions i.e. table ingestor role.
  # create_tables = true

Поддерживаемые типы приема

Подключаемый модуль поддерживает прием управляемых (потоковой передачи) и очередей (пакетной обработки). Тип приема по умолчанию помещается в очередь.

Чтобы настроить тип приема для подключаемого модуля, измените автоматически созданный файл конфигурации, как показано ниже.

  ##  Ingestion method to use.
  ##  Available options are
  ##    - managed  --  streaming ingestion with fallback to batched ingestion or the "queued" method below
  ##    - queued   --  queue up metrics data and process sequentially
  # ingestion_type = "queued"

Запрашивание принятых данных

Ниже приведены примеры данных, собираемых с помощью подключаемых модулей ввода SQL и Syslog, а также подключаемого модуля вывода Azure Data Explorer. Для каждого метода ввода есть пример использования преобразований данных и запросов в Azure Data Explorer.

Подключаемый модуль ввода SQL

В следующей таблице показаны примеры данных метрик, собранных подключаемым модулем ввода SQL:

Так как собранный объект метрик является сложным типом, столбцы полей и тегов хранятся в виде динамических типов данных. Есть разные способы запрашивания этих данных, например:

• Запрашивайте атрибуты JSON напрямую: вы можете запрашивать данные JSON в необработанном формате, не анализируя их.

  Пример 1

  Tablename
  | where name == "sqlserver_azure_db_resource_stats" and todouble(fields.avg_cpu_percent) > 7
  

  Пример 2

  Tablename
  | distinct tostring(tags.database_name)
  

  Note

  Такой подход может повлиять на производительность с большими объемами данных. В этих случаях используйте подход политики обновления.

• Используйте политику обновления: преобразуйте столбцы динамического типа данных с помощью политики обновления. Мы рекомендуем использовать этот подход для запроса больших объемов данных.

  // Function to transform data
  .create-or-alter function Transform_TargetTableName() {
    SourceTableName
    | mv-apply fields on (extend key = tostring(bag_keys(fields)[0]))
    | project fieldname=key, value=todouble(fields[key]), name, tags, timestamp
  }
  
  // Create destination table with above query's results schema (if it doesn't exist already)
  .set-or-append TargetTableName <| Transform_TargetTableName() | take 0
  
  // Apply update policy on destination table
  .alter table TargetTableName policy update
  @'[{"IsEnabled": true, "Source": "SourceTableName", "Query": "Transform_TargetTableName()", "IsTransactional": true, "PropagateIngestionProperties": false}]'
  

Подключаемый модуль ввода Syslog

В следующей таблице показаны примеры данных метрик, собранных подключаемым модулем ввода Syslog:

Существует несколько способов сглаживания динамических столбцов с помощью расширенного оператора или подключаемого модуля bag_unpack(). Вы можете использовать любой из них в функции политики обновления Transform_TargetTableName().

• Используйте оператор расширения: используйте этот подход, так как он быстрее и надежн. Даже если схема изменяется, она не прерывает запросы или панели мониторинга.

  Tablename
  
  | extend facility_code=toint(fields.facility_code), message=tostring(fields.message), procid= tolong(fields.procid), severity_code=toint(fields.severity_code),
  SysLogTimestamp=unixtime_nanoseconds_todatetime(tolong(fields.timestamp)), version= todouble(fields.version),
  appname= tostring(tags.appname), facility= tostring(tags.facility),host= tostring(tags.host), hostname=tostring(tags.hostname), severity=tostring(tags.severity)
  | project-away fields, tags
  

• Используйте подключаемый модуль bag_unpack(): этот подход позволяет автоматически распаковать столбцы динамического типа. Изменение исходной схемы может привести к проблемам при динамическом расширении столбцов.

  Tablename
  | evaluate bag_unpack(tags, columnsConflict='replace_source')
  | evaluate bag_unpack(fields, columnsConflict='replace_source')