Configurar telemetria para aplicações Databricks

A telemetria do Databricks Apps recolhe rastos, registos e métricas e persiste-os para as tabelas do Catálogo Unity usando o protocolo OpenTelemetry (OTel). Depois de ativar a telemetria da aplicação, o Databricks captura automaticamente registos do sistema e eventos de utilização, como login de utilizador e pedidos diretos de API. Também pode adicionar instrumentação personalizada usando o SDK OpenTelemetry para o seu framework.

Requisitos

• O seu espaço de trabalho deve estar numa região suportada: australiaeast, brazilsouth, canadacentral, centralindia, centralus, eastus, eastus2, germanywestcentral, northcentralus, northeurope, southcentralus, southeastasia, swedencentral, switzerlandnorth, uksouth, westeurope, westus, westus2, westus3.

• Para criar novas tabelas de alvo de telemetria no Unity Catalog, precisas CAN MANAGE de permissões sobre o catálogo e esquema de destino, e CREATE TABLE sobre o esquema.
• Para escrever nas tabelas de telemetria alvo existentes no Unity Catalog, precisa de CAN MANAGE permissões no catálogo e no esquema alvo, ou todos os utilizadores da mesma conta devem ter USE CATALOG, USE SCHEMA, SELECT e MODIFY nas tabelas alvo.
• As tabelas alvo devem ser tabelas Delta geridas na mesma região que o seu espaço de trabalho.
• O Databricks recomenda ativar a otimização preditiva nas tabelas de alvo de telemetria para melhor desempenho das consultas.

Ativar a telemetria da aplicação

Para ativar a telemetria numa aplicação, configura um catálogo e um esquema para as tabelas de telemetria nas definições da aplicação.

1. Abra a página de detalhes da aplicação no seu espaço de trabalho Azure Databricks.
2. No separador de visão geral, localize a secção de configuração de telemetria da aplicação e clique em Adicionar.
3. Insira ou navegue para selecionar um catálogo e um esquema. O Azure Databricks escreve dados de telemetria em três tabelas na localização selecionada: otel_metrics, otel_spans, e otel_logs.
4. (Opcional) Especifique um prefixo de tabela para que as tabelas sejam nomeadas <prefix>_otel_metrics, <prefix>_otel_spans, e <prefix>_otel_logs. O Azure Databricks acrescenta dados a tabelas existentes ou cria-as caso não existam.
5. Clique em Salvar.
6. Reimplemente a aplicação para que a telemetria comece a fluir para o Unity Catalog.

Verificar dados de telemetria

A otel_logs tabela é preenchida automaticamente após a redistribuição. As otel_spans e otel_metrics tabelas só são preenchidas depois de adicionar instrumentação personalizada à sua aplicação.

Depois de reimplementares a aplicação:

1. Visite o URL da aplicação para gerar atividade.

2. Espere alguns segundos até aparecer o primeiro lote de dados.

3. Execute a seguinte consulta no Databricks SQL para confirmar que os dados estão a fluir:

   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_id, span_id, e attributes. A attributes coluna é um mapa que contém metadados específicos de eventos, como event.name.

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

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

O exemplo seguinte consulta a otel_logs tabela para registos de ERRO do sistema ou personalizados do OpenTelemetry da ú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 auto-instrumentação do OpenTelemetry para gerar rastreamentos, métricas e registos personalizados. Atualize os seus app.yaml ficheiros e os de dependências conforme mostrado para o seu framework.

Streamlit

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

Traço

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

Flask

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

FastAPI

Atualização app.yaml:

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

Atualização requirements.txt:

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

Node.js

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

Atualização 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 ativa a telemetria da aplicação, o Databricks configura automaticamente variáveis de ambiente no runtime da aplicação para o endpoint coletor OTLP, protocolo de exportação, atributos de recursos e processamento em lote. Para a lista completa de variáveis de ambiente OTel, veja Variáveis de ambiente de telemetria de aplicação.

Limites e limitações

A telemetria de aplicações utiliza o conector Zerobus Ingest para escrever dados em tabelas do Catálogo Unity. Todas as limitações do conector Zerobus Ingest aplicam-se à telemetria de aplicações, incluindo restrições ao tamanho de registo, à taxa de transferência, garantias de entrega e requisitos da tabela de destino.

Para além dos limites do Zerobus, a telemetria da aplicação impõe um tamanho máximo de linha logarítmica de 1 MB por linha log.