Configure a telemetria para Databricks Apps

info

Beta

A telemetria do aplicativo está em versão Beta.

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

Requisitos

Seu workspace deve estar em uma região compatível: ap-northeast-1, ap-northeast-2, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, eu-central-1, eu-west-1, eu-west-2, sa-east-1, us-east-1, us-east-2, us-west-2.
Para criar novas tabelas de destino de telemetria no Unity Catalog, você precisa de permissões CAN MANAGE no catálogo e esquema de destino e CREATE TABLE no esquema.
Para gravar em tabelas de destino de telemetria existentes no Unity Catalog, você precisa de permissões CAN MANAGE no catálogo e esquema de destino, ou todos os usuários account devem ter USE CATALOG, USE SCHEMA, SELECT e MODIFY nas tabelas de destino.
As tabelas de destino devem ser tabelas Delta gerenciadas na mesma região que seu workspace.
A Databricks recomenda ativar a otimização preditiva nas tabelas de destino da telemetria para obter melhor desempenho das consultas.

Ativar telemetria do aplicativo

nota

Se você criou um aplicativo antes da versão beta da telemetria de aplicativos, você deve pará-lo e reiniciá-lo antes de prosseguir com as seguintes etapas de configuração.

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 em seu workspace Databricks .
Na tab Visão geral, localize a seção Configuração de telemetria do aplicativo e clique em Adicionar .
Digite ou navegue para selecionar um catálogo e um esquema. O Databricks grava dados de telemetria em três tabelas no local selecionado: otel_metrics, otel_spans e otel_logs.
(Opcional) Especifique um prefixo de tabela para que as tabelas sejam nomeadas <prefix>_otel_metrics, <prefix>_otel_spans e <prefix>_otel_logs. O Databricks adiciona dados a tabelas existentes ou as cria caso não existam.
Clique em Salvar .
Reimplante o aplicativo para que a telemetria comece a fluir para Unity Catalog.

Verificar dados de telemetria

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

Após reimplantar o aplicativo:

Acesse o URL do aplicativo para gerar atividade.
Aguarde alguns segundos para que os primeiros lotes de dados apareçam.
Execute a seguinte consulta em Databricks SQL para confirmar se os dados estão fluindo:
SQL
```
SELECT * FROM <catalog>.<schema>.otel_logs
LIMIT 10;
```

Consultar dados de telemetria

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

Para view o esquema completo de qualquer tabela de telemetria, execute o seguinte comando:

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

O exemplo a seguir consulta a tabela otel_logs em busca de logs de ERRO do OpenTelemetry, sejam eles do sistema ou personalizados, da última hora:

SQL
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 instrumentação automática do OpenTelemetry para gerar rastreamentos, métricas e logs personalizados. Atualize seus arquivos app.yaml e de dependência conforme mostrado para sua estrutura.

Streamlit
Dash
Flask
Node.js

Atualização app.yaml:

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

Atualização 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

Atualização app.yaml:

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

Atualização 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

Atualização app.yaml:

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

Atualização requirements.txt:

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

Crie um arquivo otel.js :

JavaScript
'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);

Atualização package.json:

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ável de ambiente

Ao ativar a telemetria do aplicativo, Databricks configura automaticamente as variáveis de ambiente no ambiente de execução do seu aplicativo para o endpoint do coletor OTLP, protocolo de exportação, atributos de recurso e processamento de lotes. Para obter a lista completa de OTel variável de ambiente, consulte App telemetria variável de ambiente.

Limites

Os seguintes limites se aplicam à telemetria do aplicativo:

Limite	Valor
Tamanho do registro	10 MB por registro
Tamanho da solicitação	30 MB por solicitação
tamanho da linha logarítmica	1 MB por linha log
Limite de taxa	100 solicitações de exportação por segundo por workspace
Durabilidade	Disponibilidade em apenas uma zona. O pipeline de exportação poderá sofrer interrupções caso a zona esteja indisponível.
Entrega	Pelo menos uma vez. Um aviso do servidor significa que o registro foi gravado de forma permanente na tabela Delta.

Limitações

A telemetria do aplicativo apresenta as seguintes limitações:

Os nomes das tabelas aceitam apenas letras ASCII, dígitos e sublinhados.
As tabelas de destino não podem usar o armazenamento default do Arclight.
Não é possível recriar uma tabela de destino.
A telemetria do aplicativo não oferece suporte à evolução do esquema nas tabelas de destino.

Requisitos​

Ativar telemetria do aplicativo​

Verificar dados de telemetria​

Consultar dados de telemetria​

Adicionar instrumentação personalizada​

variável de ambiente​

Limites​

Limitações​

Requisitos

Ativar telemetria do aplicativo

Verificar dados de telemetria

Consultar dados de telemetria

Adicionar instrumentação personalizada

variável de ambiente

Limites

Limitações