为 Databricks 应用配置遥测

重要

应用遥测处于 Beta 阶段。

Databricks Apps 遥测收集跟踪、日志和指标，并使用 OpenTelemetry (OTel) 协议将它们保存到 Unity Catalog 表中。启用应用遥测后，Databricks 会自动捕获系统日志和使用情况事件，例如用户登录和直接 API 请求。你还可以使用 OpenTelemetry SDK 为你的框架添加自定义监控。

要求

工作区必须位于受支持的区域中：australiaeast、brazilsouth、canadacentral、centralindia、centralus、eastus、eastus2、germanywestcentral、northcentralus、northeurope、southcentralus、southeastasia、swedencentral、switzerlandnorth、uksouth、westeurope、westus、westus2、westus3。

若要在 Unity 目录中创建新的遥测目标表，需要在目标目录和架构上具有CAN MANAGE权限，并且在架构上需要CREATE TABLE权限。
若要写入 Unity Catalog 中的现有遥测目标表，需要具有 CAN MANAGE 权限以访问目标目录和架构，或者所有帐户用户必须对目标表具有 USE CATALOG、USE SCHEMA、SELECT 和 MODIFY 权限。
目标表必须是位于与您的工作区同一区域内的托管 Delta 表。
Databricks 建议对遥测目标表启用预测优化，以提高查询性能。

启用应用遥测

注释

如果在应用遥测 beta 版之前创建了应用，则必须在继续执行以下配置步骤之前停止并重启它。

若要为应用启用遥测，请在应用设置中为遥测表配置目录和架构。

在 Azure Databricks 工作区中打开应用详细信息页。
在“概述”选项卡上，找到 “应用遥测 配置”部分，然后单击“ 添加”。
输入或浏览以选择目录和架构。 Azure Databricks 将遥测数据写入所选位置的三个表： otel_metrics， otel_spans以及 otel_logs。
（可选）指定表前缀，以便命名 <prefix>_otel_metrics表， <prefix>_otel_spans以及 <prefix>_otel_logs。 Azure Databricks 将追加到现有表，或者创建它们（如果不存在）。
单击“ 保存”。
重新部署应用程序，以便遥测数据开始转入 Unity Catalog。

验证遥测数据

该表会在重新otel_logs部署后自动填充。只有在向应用添加自定义检测后，otel_spans和otel_metrics表才会被填充。

重新部署应用后：

访问应用 URL 以生成活动。
等待几秒钟，以便显示初始数据批次。
在 Databricks SQL 中运行以下查询以确认数据正在流动：
```
SELECT * FROM <catalog>.<schema>.otel_logs
LIMIT 10;
```

查询遥测数据

用于筛选和关联遥测数据的有用列包括time、service_name、trace_id和span_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 和依赖项文件，按照您的框架所示进行更新。

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';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-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() {
  try {
    await sdk.shutdown();
  } catch (e) {
    console.error('OTel SDK shutdown failed', e);
  } finally {
    process.exit(0);
  }
}
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

更新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/exporter-logs-otlp-proto": "0.203.0",
    "@opentelemetry/sdk-metrics": "2.0.1"
  }
}

环境变量

启用应用遥测时，Databricks 会在应用运行时中为 OTLP 收集器终结点、导出协议、资源属性和批处理自动配置环境变量。有关 OTel 环境变量的完整列表，请参阅应用遥测环境变量。

极限和限制

应用遥测使用 Zerobus Ingest 连接器将数据写入 Unity Catalog 表。所有 Zerobus Ingest 连接器的限制都适用于应用遥测，包括记录大小、吞吐量、传输保证和目标表要求的限制。

除了 Zerobus 限制之外，应用程序遥测将每个日志行的最大大小限制为 1 MB。

反馈

此页面是否有帮助？

Last updated on 2026-03-21

通过

为 Databricks 应用配置遥测

要求

启用应用遥测

验证遥测数据

查询遥测数据

查询系统事件

添加自定义检测

Streamlit

短划线

Flask

FastAPI

Node.js

环境变量

极限和限制

反馈

其他资源