為 Databricks 應用程式設定遙測

Databricks Apps 遙測使用 OpenTelemetry(OTel)協定收集追蹤、日誌和指標,並將這些數據持久化至 Unity Catalog 資料表。 啟用應用程式遙測後,Databricks 會自動擷取系統日誌與使用事件,如使用者登入和直接 API 請求。 你也可以使用 OpenTelemetry SDK 為你的框架新增自訂儀器。

需求規格

  • 您的工作區必須位於受支援的區域:australiaeast、westeurope、northcentralus、koreacentral、japaneast、germanywestcentral、northeurope、francecentral、eastus2、southcentralus、uaenorth、switzerlandnorth、uksouth、swedencentral、westus、westus2、canadacentral、centralus、westus3、centralindia、eastasia、eastus、southeastasia、brazilsouth。
  • 若要在 Unity Catalog 中建立新的遙測目標表,你需要具備 CREATE TABLE 對結構描述的權限,以及下列其中一項:
    • CAN MANAGE 目標目錄與架構的權限。
    • 應用程式的服務主體在目標目錄上具有USE SCHEMA,並在目標結構描述上具有USE CATALOG、SELECT 和 MODIFY。 新表格繼承了這些權限。
  • 要在 Unity Catalog 中寫入現有的遙測目標表,你需要在目標表上具有 SELECT 和 MODIFY,並且具有以下其中一項:
    • CAN MANAGE 目標目錄與架構的權限。
    • 所有帳號使用者在目標資料表上都有 USE CATALOG、USE SCHEMA、SELECT 和 MODIFY 權限。
    • 應用程式的服務主體在目標目錄上具有 USE SCHEMA、在目標結構描述上具有 MODIFY,並且在目標資料表上具有 SELECT 和 USE CATALOG。
  • 目標資料表必須是受管理的 Delta 資料表,且位於與你的工作區相同的區域內。
  • Databricks 建議在遙測目標表啟用 預測優化 ,以提升查詢效能。

啟用應用程式遙測

要開啟應用程式的遙測,請在應用程式設定中設定遙測表的目錄和架構。

UI

  1. 在你的 Azure Databricks 工作空間中開啟應用程式詳情頁面。
  2. 在 設定 標籤中,找到 應用程式遙測 設定區塊,點選 新增。
  3. 輸入或瀏覽以選擇目錄與架構。 Azure Databricks 將遙測資料寫入選定位置的三個表格:otel_metrics、otel_spans 及 otel_logs。
  4. (可選)指定一個表格前綴,使表格被命名 <prefix>_otel_metrics為 、 <prefix>_otel_spans、 <prefix>_otel_logs和 。 Azure Databricks 會附加到現有的資料表上,或如果沒有資料表就會建立它們。
  5. 點選 [儲存]。
  6. 重新部署應用程式,讓遙測資料開始流向 Unity Catalog。

CLI

  1. 使用 databricks apps update 指令設定遙測,指定完整的目錄、結構與資料表名稱。 為了符合 UI 建立的表格名稱,請在三個表格上使用相同的 <prefix>_,或省略它以使用預設名稱:

    databricks apps update <app-name> --json '{
      "telemetry_export_destinations": [
        {
          "unity_catalog": {
            "logs_table": "<catalog>.<schema>.<prefix>_otel_logs",
            "metrics_table": "<catalog>.<schema>.<prefix>_otel_metrics",
            "traces_table": "<catalog>.<schema>.<prefix>_otel_spans"
          }
        }
      ]
    }'
    
  2. 重新部署應用程式,讓遙測資料開始流向 Unity Catalog:

    databricks apps deploy <app-name>
    

驗證遙測資料

重新部署後,該 otel_logs 表格會自動填入。 這些otel_spans和otel_metrics表格只有在您為應用程式新增自訂儀器後才會填入資料。

重新部署應用程式後:

  1. 造訪應用程式網址以產生活動。

  2. 等幾秒鐘,等第一批資料出現。

  3. 請在 Databricks SQL 執行以下查詢以確認資料是否在流動:

    SELECT * FROM <catalog>.<schema>.otel_logs
    LIMIT 10;
    

查詢遙測資料

用於篩選與關聯遙測資料的有用欄位包括 time、 service_name、 trace_idspan_idattributes、 和 。 欄位 attributes 是一個包含事件特定元資料的映射,例如 event.name。

要查看任何遙測表的完整結構,請執行:

DESCRIBE TABLE <catalog>.<schema>.otel_logs;

以下是過去一小時錯誤級日誌的範例查詢,對於除錯應用程式問題很有幫助:

SELECT time, body
FROM <catalog>.<schema>.otel_logs
WHERE service_name = '<app-name>'
  AND severity_text = "ERROR"
  AND time >= current_timestamp() - INTERVAL 1 HOUR
ORDER BY time DESC
LIMIT 100;

查詢系統事件

Azure Databricks 會自動在 otel_logs 表格中擷取系統事件,例如使用者登入使用事件及直接 API 請求。 查詢這些事件時,請透過篩選event.name屬性。

以下範例將擷取該應用程式最近100次使用事件:

SELECT time, attributes
FROM <catalog>.<schema>.otel_logs
WHERE service_name = '<app-name>'
  AND attributes:["event.name"]::string = 'app.auth'
ORDER BY time DESC
LIMIT 100;

新增自訂儀器

新增 OpenTelemetry 自動儀器化功能,以產生自訂的追蹤、指標與日誌。 依照所示更新您的 app.yaml 和相依檔案以符合您的架構。

Important

設定 OTEL_TRACES_SAMPLER 為 always_on,讓 OpenTelemetry 記錄所有追蹤。 沒有它,預設的父級取樣器會跟隨每個進來請求的取樣決定,並丟棄標記為未取樣的請求,導致你的 otel_spans 資料表不完整或為空。

Streamlit

更新 app.yaml:

command: ['opentelemetry-instrument', 'streamlit', 'run', 'app.py']
env:
  - name: OTEL_TRACES_SAMPLER
    value: 'always_on'

更新 requirements.txt:

streamlit==1.38.0

# Auto-instrumentation
opentelemetry-distro
opentelemetry-exporter-otlp-proto-grpc

# Required for Streamlit
opentelemetry-instrumentation-tornado

# Host metrics (CPU, memory)
opentelemetry-instrumentation-system-metrics

破折號

更新 app.yaml:

command: ['opentelemetry-instrument', 'python', 'app.py']
env:
  - name: OTEL_TRACES_SAMPLER
    value: 'always_on'

更新 requirements.txt:

dash
dash-bootstrap-components
pandas
plotly
databricks-sql-connector
databricks-sdk
python-dotenv
dash-ag-grid
opentelemetry-distro[otlp]
opentelemetry-instrumentation-flask
opentelemetry-exporter-otlp-proto-grpc

Flask

更新 app.yaml:

command: ['opentelemetry-instrument', 'flask', '--app', 'app.py', 'run', '--no-reload']
env:
  - name: OTEL_TRACES_SAMPLER
    value: 'always_on'

更新 requirements.txt:

opentelemetry-distro
opentelemetry-exporter-otlp-proto-grpc
opentelemetry-instrumentation-flask

FastAPI

更新 app.yaml:

command: ['opentelemetry-instrument', 'uvicorn', 'app:app', '--host', '0.0.0.0', '--port', '8000']
env:
  - name: OTEL_TRACES_SAMPLER
    value: 'always_on'

更新 requirements.txt:

fastapi
uvicorn
opentelemetry-distro
opentelemetry-exporter-otlp-proto-grpc
opentelemetry-instrumentation-fastapi

Node.js

建立 otel.js 檔案︰

'use strict';

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-proto';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter(),
    exportIntervalMillis: 10000,
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': { enabled: false },
    }),
  ],
});

try {
  sdk.start();
} catch (e) {
  console.error('OTel SDK failed to start', e);
}

async function shutdown(signal) {
  const hasAppHandler = process.listenerCount(signal) > 0;

  try {
    await sdk.shutdown();
  } catch (e) {
    console.error('OTel SDK shutdown failed', e);
  }

  if (!hasAppHandler) {
    process.kill(process.pid, signal);
  }
}
process.once('SIGTERM', shutdown);
process.once('SIGINT', shutdown);

處理常式在關機時嘗試寫出擱置中的遙測資料。 如果你的應用程式註冊了自己的訊號處理器,請與該處理器協調 SDK 關閉,確保在應用程式退出前完成刷新,並確保處理器在清理完成時終止處理序。 否則,當 SDK 關閉嘗試完成後,程序就會退出。

更新 package.json:

{
  "name": "nodejs-otel",
  "version": "0.1.0",
  "private": true,
  "main": "app.js",
  "scripts": {
    "start": "node -r ./otel.js app.js"
  },
  "dependencies": {
    "express": "^4.21.2",
    "morgan": "^1.10.0",
    "@opentelemetry/api": "^1.9.0",
    "@opentelemetry/sdk-node": "0.203.0",
    "@opentelemetry/auto-instrumentations-node": "0.67.3",
    "@opentelemetry/exporter-trace-otlp-proto": "0.203.0",
    "@opentelemetry/exporter-metrics-otlp-proto": "0.203.0",
    "@opentelemetry/sdk-metrics": "2.0.1"
  }
}

環境變數

啟用應用程式遙測時,Databricks 會自動在應用程式執行環境中設定 OTLP 收集端點、匯出協定、資源屬性及批次處理的環境變數。 欲了解完整的 OTel 環境變數清單,請參見 App 遙測環境變數。

定價

遙測資料擷取會依 Lakeflow Connect 使用量計費,因為應用程式遙測資料會透過 Zerobus Ingest 連接器寫入 Unity Catalog 資料表。 這與執行應用程式本身的計算費用是分開的。

費用是從「自動化無伺服器」SKU上計費的。 有關費率,請參閱 Lakeflow Connect 的定價頁面。

若要追蹤遙測資料擷取的費用,請查詢可計費使用量系統資料表。 如需查看用來區分 Zerobus Ingest 使用情況的篩選器,請參閱 監控您的使用情況。 若要監控應用程式本身的運算成本,請參閱 「監控應用程式成本」。

限制與局限

應用程式遙測使用 Zerobus Ingest 連接器將資料寫入 Unity 目錄資料表。 所有 Zerobus Ingest 連接器的限制都適用於應用程式遙測,包括記錄大小、吞吐量、交付保證及目標表要求的限制。 請參見 Zerobus Ingest 配額。

除了 Zerobus 限制外,應用程式遙測還強制執行每條日誌行的最大大小為 1 MB。