Grafana 的 Azure Data Explorer 数据源

Azure Data Explorer 是一个日志分析云平台，针对即席大数据查询进行了优化。

安装

此插件有以下最低要求

• v4.0.0+：Grafana 8.0.0
• v3.0.0+：Grafana 7.1.0
• < v3.0.0 需要 Grafana 6.3.6。

有关如何在 Grafana Cloud 或本地安装插件的详细说明，请查看插件安装文档。

强制执行可信 Azure Data Explorer 端点

为增加安全性，可以强制执行一个可信 ADX 端点列表，集群 URL 将对照此列表进行验证。这可以防止请求被重定向到第三方端点。

在 Grafana 配置文件的 `[plugin.grafana-azure-data-explorer-datasource]` 部分设置 `enforce_trusted_endpoints` 可以启用此功能。

[plugin.grafana-azure-data-explorer-datasource]
enforce_trusted_endpoints = true

配置 Azure Data Explorer 数据源

配置 ADX 以使用此数据源：

1. 创建 Azure Active Directory (AAD) 应用程序和 AAD 服务主体。
2. 在 Azure Data Explorer WebExplorer 中，将 AAD 应用程序连接到 Azure Data Explorer 数据库用户。
3. 使用 AAD 应用程序在 Grafana 中配置数据源连接。
4. (可选) 若要在创建查询时使用下拉集群选择器，请向包含集群的订阅授予读取者访问权限。

创建 Azure Active Directory 服务主体

有关如何设置可以访问资源的 Microsoft Entra 应用程序和服务主体的详细说明，请遵循 Microsoft 的此指南：创建可以访问资源的 Microsoft Entra 应用程序和服务主体

创建 AAD 应用程序的另一种方法是使用 Azure CLI。有关 Azure CLI 命令的更多信息，请参阅az ad sp create-for-rbac

az ad sp create-for-rbac -n "http://url.to.your.grafana:3000"

这应该返回以下内容：

{
  "appId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "displayName": "azure-cli-2018-09-20-13-42-58",
  "name": "http://url.to.your.grafana:3000",
  "password": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "tenant": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

将读取者角色分配给服务主体并移除贡献者角色

az role assignment create --assignee <your appId> --role Reader
az role assignment delete --assignee <your appId> --role Contributor

将 AAD 连接到 Azure Data Explorer 用户

上面创建的 AAD 应用程序需要被授予对您的 Azure Data Explorer 数据库的查看者访问权限（在本例中数据库名为 Grafana）。这可以通过使用点命令 `add` 来完成。`.add` 的参数包含由分号分隔的客户端 ID 和租户 ID。

.add database Grafana viewers ('aadapp=<your client id>;<your tenantid>')

包含客户端/应用程序 ID 和租户 ID 的实际示例：

.add database Grafana viewers ('aadapp=377a87d4-2cd3-44c0-b35a-8887a12fxxx;e7f3f661-a933-4b3f-8176-51c4f982exxx')

如果命令成功，您应该会看到类似这样的结果：

配置 Grafana

通过填写以下字段添加数据源：

附加设置

附加设置是可选设置，可以配置以更好地控制您的数据源。通过展开数据源配置页面底部的附加设置部分可以访问附加设置。

配置 On-Behalf-Of 身份验证（Beta 版）

{{% admonition type="caution" */%}} 此功能为 Beta 版，可能存在破坏性变更 {{%/* /admonition %}}

有关设置和使用 OBO 流程的信息，请参阅on-behalf-of 文档

查询数据源

在查询数据源之前，选择查询头部选项：集群、数据库和格式。您可以使用查询构建器、KQL 或 OpenAI 创建查询。

查询头部

集群

选择要查询的集群。如果数据源设置中设置了默认集群，则会自动填充集群选择器。如果没有集群可供选择，请参阅配置 Azure Data Explorer 数据源

数据库

选择要查询的数据库。如果数据源设置中设置了默认数据库，则会自动填充数据库选择器。

格式化为

使用“格式化为”下拉选择器，查询可以格式化为表格 (Table)、时间序列 (Time Series)、追踪 (Trace) 或 ADX 时间序列 (ADX time series) 数据。

• 表格 (Table) 查询主要用于表格面板 (Table panel)，显示为列和行的列表。此示例查询返回具有六个指定列的行：

  AzureActivity
  | where $__timeFilter()
  | project TimeGenerated, ResourceGroup, Category, OperationName, ActivityStatus, Caller
  | order by TimeGenerated desc
  

• 时间序列 (Time series) 查询用于图形面板 (Graph Panel)（以及像单一状态面板 (Single Stat panel) 这样的其他面板）。查询必须精确包含一个 datetime 列、一个或多个数值列，并且可选包含一个或多个字符串列作为标签。时间列也应按升序排列。这是一个示例查询，它返回按 Category 列和小时分组的聚合计数：

  AzureActivity
  | where $__timeFilter(TimeGenerated)
  | summarize count() by Category, bin(TimeGenerated, 1h)
  | order by TimeGenerated asc
  

  数值列被视为指标，可选字符串列被视为标签。对于每个值列 + 一组唯一的字符串列值，都会返回一个时间序列。每个序列的名称格式为 valueColumnName {stringColumnName=columnValue, ... }。

  例如，以下查询将生成类似 `AvgDirectDeaths {EventType=Excessive Heat, State=DELAWARE}``EventCount {EventType=Excessive Heat, State=NEW JERSEY}` 的序列。

  StormEvents
  | where $__timeFilter(StartTime)
  | summarize EventCount=count(), AvgDirectDeaths=avg(DeathsDirect) by EventType, State, bin(StartTime, $__timeInterval)
  | order by StartTime asc
  

• 追踪 (Trace) 格式选项可用于使用内置的追踪可视化功能显示适当格式的数据。要使用此可视化功能，数据必须按照此处定义的 schema 呈现。该 schema 包含 `logs`、`serviceTags` 和 `tags` 字段，它们应为 JSON 对象。如果 ADX 中的 schema 与以下内容匹配，这些字段将被转换为期望的数据结构：

  • `logs` - 具有一个数值 `timestamp` 字段和一个键值对象 `fields` 字段的 JSON 对象数组。
  • `serviceTags` 和 `tags` - 没有嵌套对象的典型键值 JSON 对象。

  键的值应为基本类型而非复杂类型。为空时传递的正确值应为 `null`，或者对于 `serviceTags` 和 `tags` 为空 JSON 对象，对于 `logs` 为空数组。

• ADX 时间序列 (ADX time series) 用于使用 Kusto `make-series` 运算符的查询。查询必须精确包含一个名为 `Timestamp` 的 datetime 列，以及至少一个值列。还可以选择包含作为标签的字符串列。

  示例

  let T = range Timestamp from $__timeFrom to ($__timeTo + -30m) step 1m
    | extend   Person = dynamic(["Torkel", "Daniel", "Kyle", "Sofia"])
    | extend   Place  = dynamic(["EU",     "EU",     "US",   "EU"])
    | mvexpand Person, Place
    | extend   HatInventory = rand(5)
    | project  Timestamp, tostring(Person), tostring(Place), HatInventory;
  T | make-series AvgHatInventory=avg(HatInventory) default=double(null) on Timestamp from $__timeFrom to $__timeTo step 1m by Person, Place
  | extend series_decompose_forecast(AvgHatInventory, 30) | project-away *residual, *baseline, *seasonal
  

查询构建器

查询构建器中支持 `dynamic` 类型的列。这包括数组、JSON 对象以及数组中的嵌套对象。一个限制是仅查询前 50,000 行的数据，因此构建器选择器中只会列出包含在前 50,000 行中的属性作为选项。如果默认不显示其他值，可以手动写入不同的选择器中。此外，由于这些查询使用了 `mv-expand`，它们可能会消耗大量资源。

有关通过 KQL 编辑器正确处理动态列的更多详细信息，请参阅以下文档。

Kusto 数据类型 - 有关 Kusto 支持的数据类型的文档。

Dynamic 数据类型 - 有关 dynamic 数据类型的详细文档。

使用 Kusto 查询语言 (KQL) 查询

查询使用 Kusto 查询语言编写；有关更多信息，请参阅Kusto 查询语言 (KQL) 概述。

OpenAI 查询生成器

{{% admonition type="note" */%}} 您必须启用 LLM 插件才能使用此功能。{{%/* /admonition %}}

LLM 插件可以在LLM 应用中安装。安装插件后，请启用它。

要使用查询生成器，请键入关于您想查看的数据的语句或问题，然后点击生成查询 (Generate query)。在生成的查询 (Generated query) 字段中查看和编辑生成的 KQL 查询。对查询满意后，点击运行查询 (Run query) 运行查询。

时间宏

为了更轻松地编写查询，可以在查询的 `where` 子句中使用一些 Grafana 宏：

• `$__timeFilter()` - 展开为 `TimeGenerated ≥ datetime(2018-06-05T18:09:58.907Z) and TimeGenerated ≤ datetime(2018-06-05T20:09:58.907Z)`，其中起始和结束时间取自 Grafana 时间选择器。
• `$__timeFilter(datetimeColumn)` - 展开为 `datetimeColumn ≥ datetime(2018-06-05T18:09:58.907Z) and datetimeColumn ≤ datetime(2018-06-05T20:09:58.907Z)`，其中起始和结束时间取自 Grafana 时间选择器。
• `$__timeFrom` - 展开为 `datetime(2018-06-05T18:09:58.907Z)`，即查询的开始时间。
• `$__timeTo` - 展开为 `datetime(2018-06-05T20:09:58.907Z)`，即查询的结束时间。
• `$__timeInterval` - 展开为 `5000ms`，这是 Grafana 根据查询的时间范围推荐的 bin size（以毫秒为单位）。在告警中，这将始终为 `1000ms`，建议不要在告警查询中使用此宏。

模板宏

• `$__escapeMulti($myVar)` - 用于包含非法字符的多值模板变量。如果 $myVar 的值为 `'\\grafana-vm\Network(eth0)\Total','\\hello!'`，它会展开为：`@'\\grafana-vm\Network(eth0)\Total', @'\\hello!'`。如果使用单值变量，则无需此宏，只需直接在行内转义变量即可 - `@'\$myVar'`。

• `$__contains(colName, $myVar)` - 用于多值模板变量。如果 $myVar 的值为 `'value1','value2'`，它会展开为：`colName in ('value1','value2')`。

  如果使用“全部”(`All`) 选项，请勾选“包含全部选项”(`Include All Option`) 复选框，并在“自定义全部值”(`Custom all value`) 字段中键入以下值：`all`。如果 $myVar 的值为 `all`，则宏将展开为 `1 == 1`。对于有很多选项的模板变量，这可以通过不构建一个大的 where..in 子句来提高查询性能。

使用变量进行模板化

您可以在指标查询中使用变量，而不是硬编码服务器、应用程序和传感器名称等内容。变量在仪表盘顶部显示为下拉选择框。这些下拉菜单可以轻松更改仪表盘中显示的数据。

在仪表盘设置中创建变量。通常，您需要编写 KQL 查询来获取下拉列表的值列表。不过，也可以使用硬编码的值列表。

1. 为您的变量填写名称。`Name` 字段是变量的名称。还有一个 `Label` 字段用于友好名称。

2. 在查询选项 (Query Options) 部分，在数据源 (Data source) 下拉列表中选择 `Azure Data Explorer` 数据源。

3. 在查询 (Query) 字段中编写查询。使用 `project` 指定一个列 - 结果应为字符串值列表。

   

4. 在底部，您将看到查询返回值的预览：

   

5. 在查询中使用变量（在本例中变量名为 `level`）：

   MyLogs | where Level == '$level'
   

   对于允许多个值的变量，请使用 `in` 运算符代替：

   MyLogs | where Level in ($level)
   

在Grafana 文档中阅读更多关于模板化和变量的信息。

数据库变量

无法使用 Kusto 查询语言获取数据库列表。在按使用变量进行模板化部分所述创建模板变量时，请在查询 (Query) 字段中使用以下函数返回数据库列表：

databases()

此变量可以在数据库下拉菜单中使用。这使您无需编辑面板中的查询即可切换数据库。

要使用变量，请在下拉菜单中键入变量的名称。例如，如果变量名称为 `database`，则键入 `$database`。

注解

注解是叠加在图表上方的事件。查询每行最多可以有三列，其中 datetime 列是必需的。注解渲染成本较高，因此限制返回的行数非常重要。

• datetime 类型的列。
• 带有别名 Text 或 text 的列，用于注解文本。
• 带有别名 Tags 或 tags 的列，用于注解标签。这应该返回一个逗号分隔的标签字符串，例如 'tag1,tag2'。

示例查询

MyLogs
| where $__timeFilter(Timestamp)
| project Timestamp, Text=Message , Tags="tag1,tag2"

了解更多

• 添加注解。
• 配置和使用模板和变量。
• 添加转换。
• 设置告警；请参阅告警概述。