在 Data API 建構器中使用 Azure Log Analytics

Azure Log Analytics 是一個集中式日誌平台，彙整來自應用程式、Azure 資源、虛擬機、容器等的日誌。將其與 Data API 建構器（DAB）整合，有助於企業達成合規、治理及可觀察性要求。與專注於 APM 的 Application Insights 不同，Log Analytics 提供更廣泛的日誌彙整，並支援 Kusto 查詢語言（KQL）。

Log Analytics 遙測流程的示意圖。

先決條件

現有的 DAB 設定檔。
Azure 訂閱，並有建立 Log Analytics 資源的權限。
Azure Log Analytics workspace 包含：
- 自訂資料表（結尾為 _CL）
- 資料收集規則（DCR）
- 資料收集端點（DCE）
在您的 DAB 主機（Azure App Service、Container Apps、VM 等）啟用管理身份（Managed Identity）。
數據 API 產生器 CLI。安裝 CLI

設置 Azure Log Analytics 資源

在設定 DAB 之前，先建立所需的 Azure 資源。

前往 Azure Portal>Log Analytics 工作區。
選取 + Create。
選擇你的訂閱、資源群組和地區。
提供工作區名稱。
選取 [檢閱+建立]>[建立]。

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

建立自訂資料表

用於日誌擷取 API 的自訂資料表必須以 _CL 結尾。

在你的 Log Analytics 工作區，進入 「表格」。
選擇 + 建立>新自訂日誌（基於 DCR）。
輸入表格名稱（例如， DabLogs_CL）。
用以下欄位定義該結構：
- Time （日期時間）
- LogLevel (字串)
- Message (字串)
- Component (字串)
- Identifier (字串)
選取 ，創建。

建立資料收集端點（DCE）

Azure 入口網站
Azure CLI

導航至監控>資料收集端點。
選取 + Create。
選擇你的訂閱、資源群組和地區。
提供一個名稱（例如， my-dce）。
選取 [檢閱+建立]>[建立]。
複製日誌擷取端點的網址（例如）。 https://my-dce.eastus-1.ingest.monitor.azure.com

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）

瀏覽監控>資料收集規則。
選取 + Create。
選擇訂閱、資源群組、地區。
提供一個名稱（例如， my-dcr）。
在 資料來源中，選擇 自訂文字日誌。
配置：
- 資料收集端點：選擇您的DCE。
- 目的地：您的日誌分析工作空間。
- 表格：您的自訂表格（DabLogs_CL）。
選取 [檢閱+建立]>[建立]。
複製不可變 ID（以dcr-開頭）。

設定驗證

DAB 使用 Azure 管理身份 來認證 Log Analytics。你的設定中不會儲存任何憑證。

啟用受控識別

應用程式服務
容器應用程式 (Container Apps)

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

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

指派權限

請將 Monitoring Metrics Publisher 的角色授予 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	預設	Constraints
`enabled`	啟用或停用日誌分析整合。	`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`	資料收集端點網址。	（必修）	HTTPS 網址

Command-line

通過dab configure配置日誌分析。

啟用 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.

運作方式

啟用日誌分析時，DAB：

透過主機的管理身份驗證到 Azure。
根據 flush-interval-seconds 批次處理日誌條目。
將日誌傳送至資料收集端點（Data Collection Endpoint，DCE）。
DCE 會將日誌透過資料收集規則（Data Collection Rule, DCR）進行轉換。
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 內部結構	哪個模組產生了日誌
實例標識碼	設定	`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 中的查詢日誌

在 Azure 入口網站開啟你的 Log Analytics 工作區。

請前往日誌並執行 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 的定價基於：

資料引入：每 GB 引入。
資料保留：免費方案後每月按 GB 計算。

降低成本：

增加 flush-interval-seconds 以批量處理更多日志。
使用日誌層級過濾器排除冗長的日誌。欲了解更多資訊，請參閱「自訂日誌冗長度」。
在您的日誌分析工作區設定適當的資料保留。

範例：用濾網來降低音量

{
  "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 儲存以長期保存。

故障排除

日誌未出現在 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-iddce-endpoint。
未指派 Managed Identity：使用 az webapp identity show --name my-app --resource-group my-rg 驗證 Managed Identity 是否已啟用。檢查角色分配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 已停用」

原因：false 在設定中缺失或不存在。

解決方案：在您的設定中配置enabled: true。

日誌分析與應用洞察

能力	Application Insights	Log Analytics
專注	應用程式效能監控（APM）	集中式對數聚合
查詢語言	KQL	KQL
Scope	單一應用	Apps， VMS， containers， Azure resources
用例	效能、例外、痕跡	合規性、治理、跨資源相關性
Authentication	連線字串	管理身份（透過 DCR/DCE）

當你需要 APM 功能如請求追蹤、相依性映射和效能分析時，可以使用 Application Insights。當你需要跨多資源集中記錄並具企業合規要求時，可以使用日誌分析。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-28