Pular para o conteúdo principal
Última atualização em

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.

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

  1. Acesse o URL do aplicativo para gerar atividade.

  2. Aguarde alguns segundos para que os primeiros lotes de dados apareçam.

  3. 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 os logs de nível de erro da última hora, o que é útil para problemas de aplicativos:

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;

Eventos do sistema de consulta​

O Databricks captura automaticamente eventos do sistema na tabela otel_logs , como eventos de uso para logins de usuários e solicitações diretas de API. Consulte esses eventos filtrando pelo atributo event.name .

O exemplo a seguir recupera os 100 eventos de uso mais recentes de um aplicativo:

SQL
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;

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.

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

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 e limitações​

A telemetria do aplicativo usa o conector Zerobus Ingest para gravar dados em tabelas Unity Catalog . Todas as limitações do conector Zerobus Ingest se aplicam à telemetria do aplicativo, incluindo limites de tamanho de registro, taxa de transferência, garantias de entrega e requisitos da tabela de destino.

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