Настройка телеметрии для приложений Databricks

Данные телеметрии Databricks Apps собираются, сохраняются и отправляются в таблицы Unity Catalog с использованием протокола OpenTelemetry (OTel), включая трассировки, журналы и метрики. После включения телеметрии приложения Databricks автоматически записывает системные журналы и события использования, такие как вход пользователя и прямые запросы API. Вы также можете добавить настраиваемое инструментирование с помощью пакета SDK OpenTelemetry для платформы.

Требования

Ваше рабочее пространство должно находиться в поддерживаемом регионе: australiaeast, brazilsouth, centralus, centralindia, eastasia, eastus, canadacentral, switzerlandnorth, westus3, westeurope, westus2, westus, uaenorth, uksouth, eastus2, francecentral, germanywestcentral, japaneast, koreacentral, northcentralus, northeurope, southcentralus, southeastasia, swedencentral.

Чтобы создать новые целевые таблицы телеметрии в Unity Catalog, вам необходимо CREATE TABLE для схемы и одно из следующего:
- CAN MANAGE Разрешения для целевого каталога и схемы.
- Субъект-служба приложения имеет USE CATALOG в целевом каталоге и USE SCHEMA, SELECT и MODIFY в целевой схеме. Новые таблицы наследуют эти привилегии.
Чтобы записать в существующие целевые таблицы телеметрии в Unity Catalog, вам нужно SELECT и MODIFY на целевых таблицах, а также одно из следующего:
- CAN MANAGE Разрешения для целевого каталога и схемы.
- У всех пользователей аккаунта есть USE CATALOG, USE SCHEMA, SELECTи MODIFY в целевых таблицах.
- Субъект-служба приложения имеет USE CATALOG на целевой каталог, USE SCHEMA на целевую схему, а также SELECT и MODIFY на целевые таблицы.
Целевые таблицы должны быть управляемыми таблицами Delta в том же регионе, что и рабочая область.
Databricks рекомендует включить прогнозную оптимизацию целевых таблиц телеметрии для повышения производительности запросов.

Включение телеметрии приложения

Чтобы включить телеметрию для приложения, настройте каталог и схему для таблиц телеметрии в параметрах приложения.

Пользовательский интерфейс

Откройте страницу сведений о приложении в рабочей области Azure Databricks.
На вкладке "Параметры" найдите раздел конфигурации телеметрии приложения и нажмите кнопку "Добавить".
Введите или перейдите к выбору каталога и схемы. Azure Databricks записывает данные телеметрии в три таблицы в выбранном расположении: otel_metrics, otel_spans и otel_logs.
(Необязательно) Укажите префикс таблицы, чтобы таблицы были именованы <prefix>_otel_metrics, <prefix>_otel_spansи <prefix>_otel_logs. Azure Databricks дополняет существующие таблицы или создаёт новые, если таковые отсутствуют.
Нажмите кнопку Сохранить.
Повторно разверните приложение, чтобы данные телеметрии начали поступать в каталог Unity.

CLI

Настройте телеметрию с помощью команды databricks apps update, указывая полный каталог, схему и имена таблиц. Чтобы соответствовать именам таблиц, которые создаёт пользовательский интерфейс, используйте один и тот же <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"
      }
    }
  ]
}'
```
Повторно разверните приложение, чтобы данные телеметрии начали поступать в 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_idspan_idи attributes. Столбец 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, поскольку данные телеметрии приложения записываются в таблицы Unity Catalog через коннектор Zerobus Ingest. Это отдельно от вычислительных расходов на запуск самого приложения.

Оплата начисляется с «Автоматизированного безсерверного» SKU. Для получения тарифов смотрите страницу с ценами Lakeflow Connect.

Чтобы отслеживать затраты на приём телеметрии, запросите системную таблицу тарифицируемого использования. Фильтры, изолирующие использование Zerobus Ingest, см. раздел «Мониторинг вашего использования». Чтобы отслеживать вычислительные затраты самого приложения, смотрите раздел «Мониторинг затрат приложения».

Пределы и ограничения

Телеметрия приложения использует соединитель Ingest Zerobus для записи данных в таблицы каталога Unity. Все ограничения разъёмов Zerobus Ingest применяются к телеметрии приложений, включая ограничения по размеру записи, пропускной способности, гарантиям доставки и требованиям к таблице целей. См. квоты на Zerobus Ingest.

Помимо ограничений Zerobus, телеметрия приложения ограничивает максимальный размер строки журнала до 1 МБ.

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-11-05

Настройка телеметрии для приложений Databricks

Требования

Включение телеметрии приложения

Пользовательский интерфейс

CLI

Проверка данных телеметрии

Запрос данных телеметрии

Запрос системных событий

Добавьте настраиваемое инструментирование

Streamlit

Панель

Flask

FastAPI

Node.js

Переменные среды

Ценообразование

Пределы и ограничения

Обратная связь

Дополнительные ресурсы