在数据 API 生成器中使用 Azure Log Analytics

Azure Log Analytics 是一个集中式日志记录平台，用于聚合来自应用、Azure 资源、VM、容器等的日志。 将其与数据 API 生成器（DAB）集成有助于企业满足合规性、治理和可观测性要求。 与 Application Insights（重点介绍 APM）不同，Log Analytics 通过 Kusto 查询语言（KQL）支持提供更广泛的日志聚合。

先决条件

• 现有的 DAB 配置文件。
• 有权创建 Log Analytics 资源的 Azure 订阅。
• Azure Log Analytics 工作区，其中包含：
  • 自定义表（以 _CL 结尾）
  • 数据收集规则 （DCR）
  • 数据收集端点 (DCE)
• 在您的 DAB 主机（例如 Azure 应用服务、容器应用、虚拟机等）上启用了托管标识。
• 数据 API 生成器 CLI。 安装 CLI

设置 Azure Log Analytics 资源

在配置 DAB 之前，请创建所需的 Azure 资源。

创建 Log Analytics 工作区

1. 导航到 Azure 门户>Log Analytics 工作区。
2. 选择+ 新建。
3. 选择订阅、资源组和区域。
4. 提供工作区名称。
5. 选择“审核 + 创建”>创建。

Azure CLI

az monitor log-analytics workspace create \
  --resource-group my-rg \
  --workspace-name my-workspace \
  --location eastus

创建自定义表

日志摄取 API 的自定义表必须以 _CL 结尾。

1. 在 Log Analytics 工作区中，导航到 “表”。
2. 选择“+>新建自定义日志”（基于 DCR）。
3. 输入表名称（例如， DabLogs_CL）。
4. 通过以下列定义架构：
   • Time （日期时间）
   • LogLevel（字符串）
   • Message（字符串）
   • Component（字符串）
   • Identifier（字符串）
5. 选择 创建。

创建数据收集终结点 （DCE）

1. 导航到 “监视>数据收集终结点”。
2. 选择+ 新建。
3. 选择订阅、资源组和区域。
4. 提供一个名称（例如， my-dce）。
5. 选择“审核 + 创建”>创建。
6. 复制 日志引入 终结点 URL（例如 https://my-dce.eastus-1.ingest.monitor.azure.com）。

Azure CLI

az monitor data-collection endpoint create \
  --name my-dce \
  --resource-group my-rg \
  --location eastus \
  --public-network-access Enabled

获取端点：

az monitor data-collection endpoint show \
  --name my-dce \
  --resource-group my-rg \
  --query logsIngestion.endpoint -o tsv

创建数据收集规则 （DCR）

1. 导航到 监控>数据收集规则。
2. 选择+ 新建。
3. 选择订阅、资源组、区域。
4. 提供一个名称（例如， my-dcr）。
5. 在 数据源中，选择 “自定义文本日志”。
6. 配置：
   • 数据收集端点：选择 DCE。
   • 目标：Log Analytics 工作区。
   • 表：自定义表（DabLogs_CL）。
7. 选择“审核 + 创建”>创建。
8. 复制不可变 ID（从dcr-开始）。

配置身份验证

DAB 使用 Azure 托管标识 向 Log Analytics 进行身份验证。 配置中未存储任何凭据。

启用托管标识

应用服务

az webapp identity assign \
  --name my-app \
  --resource-group my-rg

容器应用

az containerapp identity assign \
  --name my-app \
  --resource-group my-rg \
  --system-assigned

分配权限

在 DCR 上为您的托管标识授予 监控指标发布者 角色。

# Get Managed Identity principal ID
PRINCIPAL_ID=$(az webapp identity show \
  --name my-app \
  --resource-group my-rg \
  --query principalId -o tsv)

# Get DCR resource ID
DCR_ID=$(az monitor data-collection rule show \
  --name my-dcr \
  --resource-group my-rg \
  --query id -o tsv)

# Assign role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Monitoring Metrics Publisher" \
  --scope $DCR_ID

重要

如果没有此角色分配，DAB 即使配置正确，也不能将日志发送到 Log Analytics。

配置 Log Analytics

在配置文件的azure-log-analytics下添加一个runtime.telemetry部分。

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "my-dab-instance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

配置属性

资产	Description	违约	限制条件
enabled	启用或禁用 Log Analytics 集成。	false	布尔
dab-identifier	用于标识此 DAB 实例中的日志条目的唯一字符串。	DabLogs	任意字符串
flush-interval-seconds	日志刷新到 Log Analytics 的频率（以秒为单位）。	5	必须为 > 0
auth.custom-table-name	Log Analytics 工作区中的自定义表名称。	需要 ()	必须以 _CL 结束
auth.dcr-immutable-id	数据收集规则的不可变 ID。	需要 ()	以 dcr- 开头
auth.dce-endpoint	数据收集终结点 URL。	需要 ()	HTTPS URL

命令行

通过 dab configure 配置 Log Analytics。

启用 Log Analytics

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.enabled true

命令提示符

dab configure ^
  --runtime.telemetry.azure-log-analytics.enabled true

设置 DAB 标识符

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

命令提示符

dab configure ^
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

设置清除间隔

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

命令提示符

dab configure ^
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

设置自定义表名称

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

命令提示符

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

设置 DCR 不可更改 ID

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

命令提示符

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

设置 DCE 终结点

Bash

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

命令提示符

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

运行 DAB

使用配置文件启动 DAB：

dab start

检查 DAB 启动日志中是否有：

Azure Log Analytics is enabled.

工作原理

启用 Log Analytics 功能后，DAB：

1. 使用主机的托管标识向 Azure 进行身份验证。
2. 根据 flush-interval-seconds 批处理日志条目。
3. 将日志发送到数据收集终结点（DCE）。
4. DCE 通过数据收集规则（DCR）来路由和转换日志。
5. DCR 将日志引入到自定义 Log Analytics 表中。

数据流

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
Log Analytics Logger Provider
    ↓
Managed Identity Authentication
    ↓
Data Collection Endpoint (DCE)
    ↓
Data Collection Rule (DCR)
    ↓
Log Analytics Workspace (Custom Table)

捕获的内容

遥测类型	来源	例子
跟踪	ILogger DAB 中的调用	启动日志、查询执行日志、警告
Errors	异常处理	运行时错误、配置错误、数据库错误
组件信息	DAB 内部	哪个模块生成了日志
实例 ID	配置	dab-identifier 用于筛选的值

日志结构

发送到 Log Analytics 的每个日志条目都包含以下字段：

领域	类型	Description	Example
Time	日期/时间	时间戳 （ISO 8601）	2026-01-27T14:30:00Z
LogLevel	字符串	日志严重性	Information、Warning、Error
Message	字符串	日志消息	Request completed successfully
Component	字符串	生成日志的 DAB 组件	Azure.DataApiBuilder.Service.Startup
Identifier	字符串	dab-identifier配置值	my-dab-instance

注释

Log Analytics 中的自定义表列追加后缀：_s 字符串、_d 双精度数、_t 日期时间等。

在 Log Analytics 中查询日志

1. 在 Azure 门户中打开 Log Analytics 工作区。

2. 导航到 日志 并运行 KQL 查询：

   DabLogs_CL
   | where Identifier_s == "my-dab-instance"
   | where LogLevel_s in ("Warning", "Error")
   | where TimeGenerated > ago(1h)
   | project TimeGenerated, LogLevel_s, Message_s, Component_s
   | order by TimeGenerated desc
   

示例查询

按级别对日志进行计数：

DabLogs_CL
| where TimeGenerated > ago(24h)
| summarize Count=count() by LogLevel_s

查找特定组件中的错误：

DabLogs_CL
| where Component_s contains "SqlQueryExecutor"
| where LogLevel_s == "Error"
| project TimeGenerated, Message_s

性能和成本注意事项

批处理行为

DAB 对日志进行批处理，并每隔一次 flush-interval-seconds发送日志：

• 5 秒（默认值）：在大多数情况下，平衡良好。
• 1-2 秒：准实时日志记录（更高的 API 调用、更高的成本）。
• 10-60 秒：减少了 API 调用，但日志延迟。

成本优化

Log Analytics 定价基于：

1. 数据引入：每 GB 引入。
2. 数据保留期：免费层后每月每 GB。

降低成本：

• 增加 flush-interval-seconds 以批处理更多日志。
• 使用日志级别筛选器排除详细日志。 有关详细信息，请参阅 自定义日志详细程度。
• 在 Log Analytics 工作区中设置适当的数据保留期。

示例：筛选以减少音量

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Default": "Warning",
        "Microsoft": "Error"
      },
      "azure-log-analytics": {
        "enabled": true,
        "flush-interval-seconds": 30,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

只发送 警告 和 错误 日志，显著减少量。

数据保留期

Log Analytics 数据保留期可按工作区进行配置：

层	默认保留期	最大保留期
免费层	7 天	7 天
即用即付	30 天	730 天 （2 年）

配置保留期：Log Analytics 工作区→ 使用情况和估计成本 → 数据保留期。

小窍门

对于符合性要求，请考虑将旧日志存档到 Azure 存储，以便长期保留。

Troubleshooting

Log Analytics 中未显示的日志

症状：DAB 已成功启动，但 Log Analytics 工作区中未显示任何日志。

可能的原因：

• 不完整的配置：检查 DAB 启动日志是否存在错误，例如 Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. 验证所有必需的身份验证属性： custom-table-name、 dcr-immutable-id、 dce-endpoint。

• 未分配托管标识：请验证是否已启用托管标识 az webapp identity show --name my-app --resource-group my-rg。 使用 az role assignment list --assignee <principal-id> --scope <dcr-id> 检查角色分配。

• DCE 端点或 DCR ID 不正确：请验证 DCE 端点格式是否正确。https://<dce-name>.<region>-1.ingest.monitor.azure.com 验证 DCR 不可变 ID 是否以 dcr- 开头。

• 自定义表不存在：自定义表必须以 _CL 结尾。 表架构必须与日志结构匹配。

错误：刷新间隔必须为正

原因： flush-interval-seconds 设置为 0 或负值。

解决方案：设置为 flush-interval-seconds 正整数（最小值 1）。

DAB 日志显示“Azure Log Analytics 已禁用”

原因： enabled 是false或者缺失于配置中。

解决方案：在配置中设置 enabled: true 。

Log Analytics 与 Application Insights

能力	Application Insights	Log Analytics
焦点	应用程序性能监控（APM）	集中式日志聚合
查询语言	KQL	KQL
Scope	单个应用程序	应用、VM、容器、Azure 资源
用例	性能、异常、跟踪	合规性、治理、跨资源关联
Authentication	连接字符串	托管身份（通过 DCR/DCE）

如果需要 APM 功能（例如请求跟踪、依赖项映射和性能分析），请使用 Application Insights。 需要集中日志记录具有企业合规性要求的多个资源时，请使用 Log Analytics。

相关内容

• 使用 Application Insights
• 使用 OpenTelemetry
• 自定义日志详细程度
• 数据收集规则概述
• Azure 资源的托管标识