为 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 目录中写入现有的遥测目标表，你需要对目标表具有 SELECT 和 MODIFY 权限，并且需要以下之一：
- CAN MANAGE 目标目录和模式的权限。
- 所有账户用户在目标表上都有 USE CATALOG、USE SCHEMA、SELECT 和 MODIFY。
- 应用的服务主体在目标目录上具有 USE SCHEMA，在目标模式上具有 MODIFY，并且在目标表上具有 SELECT 和 USE CATALOG。
目标表必须是与工作区位于同一区域的托管 Delta 表。
Databricks 建议对遥测目标表启用预测优化，以提高查询性能。

启用应用遥测

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

UI

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

CLI

使用 databricks apps update 命令配置遥测，并指定完整的目录、架构和表名称：

databricks apps update <app-name> --json '{
  "telemetry_export_destinations": [
    {
      "unity_catalog": {
        "logs_table": "<catalog>.<schema>.<your-prefix>-otel_logs",
        "metrics_table": "<catalog>.<schema>.otel_metrics",
        "traces_table": "<catalog>.<schema>.otel_spans"
      }
    }
  ]
}'

重新部署应用，使遥测数据开始发送到 Unity Catalog：
```
databricks apps deploy <app-name>
```

验证遥测数据

该表会在重新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和依赖项文件。

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 环境变量的完整列表，请参阅应用遥测环境变量。

定价

遥测数据的采集按 Lakeflow Connect 使用量计费，因为应用遥测通过 Zerobus Ingest 连接器写入 Unity 目录表。这与运行应用本身的计算费用是分开的。

费用是针对“自动化无服务器”SKU计费的。有关费率，请参见 Lakeflow Connect定价页面。

要跟踪遥测数据摄取成本，请查询计费使用系统表。关于隔离Zerobus导入使用情况的过滤器，请参见 “监控您的使用情况”。要监控应用本身的计算成本，请参见 “监控应用成本”。

极限和限制

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

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

反馈

此页面是否有帮助？

上次更新时间为 2026-10-19

为 Databricks 应用配置遥测

要求

启用应用遥测

UI

CLI

验证遥测数据

查询遥测数据

查询系统事件

添加自定义检测

Streamlit

短划线

Flask

FastAPI

Node.js

环境变量

定价

极限和限制

反馈

其他资源