Configurar a telemetria para aplicativos do Databricks

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

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

1. Abra a página de detalhes do aplicativo no workspace do Azure Databricks.
2. Na guia visão geral, localize a seção configuração de telemetria do aplicativo e clique em Adicionar.
3. 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.
4. (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.
5. Clique em Salvar.
6. 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:

1. Visite a URL do aplicativo para gerar atividade.

2. Aguarde alguns segundos para que o lote inicial de dados apareça.

3. 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.