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

  • Статья

Важно!

Этот соединитель можно использовать в аналитике в режиме реального времени в Microsoft Fabric. Используйте инструкции в этой статье со следующими исключениями:

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

Предварительные требования

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

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

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

  • Microsoft Entra маркеры пользователей

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

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

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

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

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

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

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

  • Учетные данные клиента (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. Обратите внимание, что учетные записи с включенной многофакторной проверкой подлинности не поддерживаются.

  • Управляемое удостоверение службы 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:

name tags TIMESTAMP fields
sqlserver_database_io {"database_name":"azure-sql-db2","file_type":"DATA","host":"adx-vm","logical_filename":"tempdev","measurement_db_type":"AzureSQLDB","physical_filename":"tempdb.mdf","replica_updateability":"READ_WRITE","sql_instance":"adx-sql-server"} 2021-09-09T13:51:20Z {"current_size_mb":16,"database_id":2,"file_id":1,"read_bytes":2965504,"read_latency_ms":68,"reads":47,"rg_read_stall_ms":42,"rg_write_stall_ms":0,"space_used_mb":0,"write_bytes":1220608,"write_latency_ms":103,"writes":149}
sqlserver_waitstats {"database_name":"azure-sql-db2","host":"adx-vm","measurement_db_type":"AzureSQLDB","replica_updateability":"READ_WRITE","sql_instance":"adx-sql-server","wait_category":"Worker Thread","wait_type":"THREADPOOL"} 2021-09-09T13:51:20Z {"max_wait_time_ms":15,"resource_wait_ms":4469,"signal_wait_time_ms":0,"wait_time_ms":4469,"waiting_tasks_count":1464}

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

  • Запрашивайте атрибуты 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)

    Примечание

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

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

    // 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:

name tags TIMESTAMP fields
syslog {"appname":"azsecmond","facility":"user","host":"adx-linux-vm","hostname":"adx-linux-vm","severity":"info"} 2021-09-20T14:36:44Z {"facility_code":1,"message":" 2021/09/20 14:36:44.890110 Failed to connect to mdsd: dial unix /var/run/mdsd/default_djson.socket: connect: no such file or directory","procid":"2184","severity_code":6,"timestamp":"1632148604890477000","version":1}
syslog {"appname":"CRON","facility":"authpriv","host":"adx-linux-vm","hostname":"adx-linux-vm","severity":"info"} 2021-09-20T14:37:01Z {"facility_code":10,"message":" pam_unix(cron:session): session opened for user root by (uid=0)","procid":"26446","severity_code":6,"timestamp":"1632148621120781000","version":1}

Есть несколько способов преобразования в плоскую структуру динамических столбцов с помощью оператора extend или подключаемого модуля 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')