Configurar a telemetria para aplicativos do Databricks

Importante

A telemetria do aplicativo está em Beta.

A telemetria do Databricks Apps coleta traços, logs e métricas e os persiste nas tabelas do Unity Catalog utilizando o protocolo OpenTelemetry (OTel). Depois de habilitar a telemetria do aplicativo, o Databricks captura automaticamente logs do sistema e eventos de uso, como logon do usuário e solicitações diretas de API. Você também pode adicionar instrumentação personalizada usando o SDK do OpenTelemetry para sua estrutura.

Requisitos

Seu workspace deve estar em uma região com suporte: australiaeast, brazilsouth, canadacentral, centralindia, centralus, eastus, eastus2, germanywestcentral, northcentralus, northeurope, southcentralus, southeastasia, swedencentral, switzerlandnorth, uksouth, westeurope, westus, westus2, westus3.

Para criar novas tabelas de destino de telemetria no Catálogo do Unity, você precisa de CAN MANAGE permissões no catálogo e no esquema de destino e CREATE TABLE no esquema.
Para gravar em tabelas de destino de telemetria existentes no Catálogo do Unity, você precisa de CAN MANAGE permissões no catálogo e no esquema de destino ou todos os usuários da conta devem terUSE CATALOG, USE SCHEMASELECTe MODIFY nas tabelas de destino.
As tabelas de destino devem ser tabelas Delta que são gerenciadas na mesma região que a área de trabalho.
O Databricks recomenda habilitar a otimização preditiva nas tabelas de destino de telemetria para melhorar o desempenho da consulta.

Habilitar telemetria do aplicativo

Observação

Se você criou um aplicativo antes da telemetria beta do aplicativo, deve interrompê-lo e reiniciá-lo antes de prosseguir com as etapas de configuração a seguir.

Para ativar a telemetria de um aplicativo, configure um catálogo e um esquema para as tabelas de telemetria nas configurações do aplicativo.

Abra a página de detalhes do aplicativo no workspace do Azure Databricks.
Na guia visão geral, localize a seção configuração de telemetria do aplicativo e clique em Adicionar.
Insira ou navegue para selecionar um catálogo e um esquema. O Azure Databricks grava dados de telemetria em três tabelas no local selecionado: otel_metricse otel_spansotel_logs.
(Opcional) Especifique um prefixo de tabela para que as tabelas sejam nomeadas <prefix>_otel_metricse <prefix>_otel_spans<prefix>_otel_logs. O Azure Databricks acrescentará a tabelas existentes ou as criará se elas não existirem.
Clique em Salvar.
Reimplante o aplicativo para que a telemetria comece a fluir para o Catálogo do Unity.

Verificar dados de telemetria

A otel_logs tabela é preenchida automaticamente após a reimplantação. As tabelas otel_spans e otel_metrics são preenchidas somente depois que você adiciona instrumentação personalizada ao seu aplicativo.

Depois de reimplantar o aplicativo:

Visite a URL do aplicativo para gerar atividade.
Aguarde alguns segundos para que o lote inicial de dados apareça.
Execute a seguinte consulta no DATAbricks SQL para confirmar se os dados estão fluindo:
```
SELECT * FROM <catalog>.<schema>.otel_logs
LIMIT 10;
```

Consultar dados de telemetria

Colunas úteis para filtrar e correlacionar dados de telemetria incluem time, , service_name, trace_ide span_idattributes. A attributes coluna é um mapa que contém metadados específicos do evento, como event.name.

Para exibir o esquema completo de qualquer tabela de telemetria, execute:

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

O exemplo a seguir consulta a tabela otel_logs para logs de erro OpenTelemetry personalizados ou do sistema na última hora.

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;

Adicionar instrumentação personalizada

Adicione a instrumentação automática OpenTelemetry para gerar rastreamentos, métricas e logs personalizados. Atualize seu app.yaml e os arquivos de dependência, conforme mostrado para seu framework.

Streamlit

Atualizar app.yaml:

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

Atualizar 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

Traço

Atualizar app.yaml:

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

Atualizar 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

Atualizar app.yaml:

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

Atualizar requirements.txt:

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

FastAPI

Atualizar app.yaml:

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

Atualizar requirements.txt:

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

Node.js

Criar um arquivo 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);

Atualizar 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"
  }
}

Variáveis de ambiente

Quando você habilita a telemetria do aplicativo, o Databricks configura automaticamente variáveis de ambiente no runtime do aplicativo para o ponto de extremidade do coletor OTLP, o protocolo de exportação, os atributos de recurso e o processamento em lote. Para obter a lista completa de variáveis de ambiente OTel, consulte variáveis de ambiente de telemetria de aplicativo.

Limites e limitações

A telemetria do aplicativo utiliza o conector Zerobus Ingest para gravar dados nas tabelas do Unity Catalog. Todas as limitações do conector de Ingestão Zerobus se aplicam à telemetria do aplicativo, incluindo limites no tamanho dos dados, largura de banda, garantias de entrega e requisitos para a tabela de destino.

Além dos limites do Zerobus, a telemetria do aplicativo impõe um tamanho máximo de linha de log de 1 MB por linha de log.

Comentários

Esta página foi útil?

Last updated on 2026-03-15

Compartilhar via

Configurar a telemetria para aplicativos do Databricks

Requisitos

Habilitar telemetria do aplicativo

Verificar dados de telemetria

Consultar dados de telemetria

Adicionar instrumentação personalizada

Streamlit

Traço

Flask

FastAPI

Node.js

Variáveis de ambiente

Limites e limitações

Comentários

Recursos adicionais