Azure Data Explorer 输出插件

此插件将指标写入 Azure Data Explorer、Azure Synapse Data Explorer 和 Fabric 中的实时分析 服务。

Azure Data Explorer 是一个分布式、面向列的存储，专为任何类型的日志、指标和时间序列数据而构建。

引入于： Telegraf v1.20.0 标签： cloud, datastore 操作系统支持： all

先决条件

• 创建 Azure Data Explorer 群集和数据库
• 托管 Telegraf 的虚拟机/计算或容器 - 它可以托管在部署了要监控的应用/服务的本地，也可以托管在专用的远程监控计算/容器上。

全局配置选项

插件支持其他全局和插件配置设置，用于修改指标、标签和字段，创建别名以及配置插件顺序等任务。更多详情请参阅 CONFIGURATION.md。

配置

# Sends metrics to Azure Data Explorer
[[outputs.azure_data_explorer]]
  ## The URI property of the Azure Data Explorer resource on Azure
  ## ex: endpoint_url = 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
  # timeout = "20s"

  ## Type of metrics grouping used when pushing to Azure Data Explorer.
  ## Default is "TablePerMetric" for one table per different metric.
  ## For more information, please check the plugin README.
  # 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 lowest possible permissions (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"

指标分组

指标可以通过两种方式分组以发送到 Azure Data Explorer。要指定插件应使用哪种指标分组类型，应将相应的值赋给配置文件中的 metrics_grouping_type。如果未给 metrics_grouping_type 赋值，则默认情况下，指标将使用 TablePerMetric 进行分组。

TablePerMetric

该插件将按指标名称对指标进行分组，并将每组指标发送到一个 Azure Data Explorer 表。如果表不存在，插件将创建该表；如果表已存在，插件将尝试将 Telegraf 指标架构合并到现有表中。有关合并过程的更多信息，请参阅 .create-merge 文档。

表名将匹配指标的 name 属性，这意味着指标的名称应符合 Azure Data Explorer 表的命名约束，以防您计划为指标名称添加前缀。

SingleTable

该插件会将接收到的所有指标发送到一个 Azure Data Explorer 表。表名必须通过配置文件中的 table_name 提供。如果表不存在，插件将创建该表；如果表已存在，插件将尝试将 Telegraf 指标架构合并到现有表中。有关合并过程的更多信息，请参阅 .create-merge 文档。

表架构

Azure Data Explorer 表的架构将匹配 Telegraf Metric 对象 的结构。插件生成的相应 Azure Data Explorer 命令将如下所示

.create-merge table ['table-name']  (['fields']:dynamic, ['name']:string, ['tags']:dynamic, ['timestamp']:datetime)

相应的表映射将如下所示

.create-or-alter table ['table-name'] ingestion json mapping 'table-name_mapping' '[{"column":"fields", "Properties":{"Path":"$[\'fields\']"}},{"column":"name", "Properties":{"Path":"$[\'name\']"}},{"column":"tags", "Properties":{"Path":"$[\'tags\']"}},{"column":"timestamp", "Properties":{"Path":"$[\'timestamp\']"}}]'

注意：本插件将根据上述命令自动创建 Azure Data Explorer 表和相应的表映射。

提取类型

注意：如果使用 managed 选项，则必须在 ADX 中启用 流式提取 [配置 ADX 群集]。参考以下查询以检查流式提取是否已启用

.show database <DB-Name> policy streamingingestion

身份验证

支持的身份验证方法

本插件提供多种身份验证类型。插件将检查几种特定环境变量是否存在，并据此选择正确的方法。

这些方法包括

1. AAD 应用程序令牌（带密钥或证书的服务主体）。

   有关如何在 Azure Active Directory 中创建和注册应用程序的指导，请参阅 本文，有关服务主体的更多信息，请参阅 本文。

2. AAD 用户令牌

   • 允许 Telegraf 像用户一样进行身份验证。此方法主要仅用于开发目的。

3. 托管服务标识 (MSI) 令牌

   • 如果您从 Azure VM 或基础架构运行 Telegraf，那么这是首选的身份验证方法。

无论采用哪种方法，指定的 Principal 都需要在 Azure Data Explorer 的数据库级别被分配 Database User 角色。此角色将允许插件创建所需的表并从中提取数据。如果 create_tables=false，则指定的 Principal 至少需要 Database Ingestor 角色。

所选身份验证方法的配置

插件将使用以下配置中第一个可用的配置进行身份验证，重要的是要理解，评估（以及因此选择身份验证方法）将按以下顺序进行

1. 客户端凭据：Azure AD 应用程序 ID 和密钥。

   设置以下环境变量

   • AZURE_TENANT_ID：指定要进行身份验证的租户。
   • AZURE_CLIENT_ID：指定要使用的应用程序客户端 ID。
   • AZURE_CLIENT_SECRET：指定要使用的应用程序密钥。

2. 客户端证书：Azure AD 应用程序 ID 和 X.509 证书。

   • AZURE_TENANT_ID：指定要进行身份验证的租户。
   • AZURE_CLIENT_ID：指定要使用的应用程序客户端 ID。
   • AZURE_CERTIFICATE_PATH：指定要使用的证书路径。
   • AZURE_CERTIFICATE_PASSWORD：指定要使用的证书密码。

3. 资源所有者密码：Azure AD 用户和密码。此授权类型不推荐使用，如果需要交互式登录，请改用设备登录。

   • AZURE_TENANT_ID：指定要进行身份验证的租户。
   • AZURE_CLIENT_ID：指定要使用的应用程序客户端 ID。
   • AZURE_USERNAME：指定要使用的用户名。
   • AZURE_PASSWORD：指定要使用的密码。

4. Azure 托管服务标识：将凭据管理委托给平台。要求代码在 Azure 中运行，例如在 VM 上。所有配置均由 Azure 处理。有关详细信息，请参阅 Azure 托管服务标识。仅在使用 Azure 资源管理器时可用。

查询 Azure Data Explorer 中收集的数据

有用的数据转换和查询示例，可用于获取见解 -

使用 SQL 输入插件

SQL 指标数据示例 -

由于收集的指标对象是复杂类型，因此“fields”和“tags”存储为动态数据类型，有多种方法可以查询这些数据 -

1. 直接查询 JSON 属性：Azure Data Explorer 提供了一种在不解析的情况下直接查询 JSON 数据格式的能力，因此可以按以下方式直接查询 JSON 属性

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

Tablename
| distinct tostring(tags.database_name)

注意 - 对于大量数据，此方法可能会产生性能影响，请在这些情况下使用下面提到的方法。

1. 使用 更新策略**：使用更新策略转换动态数据类型列。这是比直接查询 JSON 属性更高效的查询大量数据的推荐方法。

// 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() | limit 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 数据示例 -

有多种方法可以使用“extend”或“bag_unpack”运算符来展平动态列。您可以在上面提到的更新策略函数“Transform_TargetTableName()”中使用这些方法中的任何一种。

• 使用 extend 运算符 - 这是与“bag_unpack”相比推荐的方法，因为它更快、更健壮。即使架构发生变化，也不会破坏查询或仪表板。

  Tablenmae
  | 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')