Configurer la télémétrie pour Databricks Apps

info

Aperçu public

La télémétrie de l’application est en version préliminaire publique.

La télémétrie de Databricks Apps collecte les traces, les logs et les métriques et les conserve dans les tables Unity Catalog à l'aide du protocole OpenTelemetry (OTel). Après avoir activé la télémétrie de l’application, Databricks capture automatiquement les logs système et les événements d’utilisation tels que la connexion de l’utilisateur et les requêtes API directes. Vous pouvez également ajouter une instrumentation personnalisée à l'aide du SDK OpenTelemetry pour votre framework.

Exigences

• Votre Workspace doit se trouver dans une région prise en charge : 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.

• Pour créer de nouvelles tables cibles de télémétrie dans Unity Catalog, vous avez besoin des autorisations CAN MANAGE sur le catalogue et le schéma cibles, et CREATE TABLE sur le schéma.

• Pour écrire dans des tables cibles de télémétrie existantes dans Unity Catalog, vous avez besoin des autorisations CAN MANAGE sur le catalogue et le schéma cibles, ou tous les utilisateurs du compte doivent disposer de USE CATALOG, USE SCHEMA, SELECT et MODIFY sur les tables cibles.

• Les tables cibles doivent être des tables Delta gérées dans la même région que votre workspace.

• Databricks recommande d'activer l'optimisation prédictive sur les tables cibles de télémétrie pour de meilleures performances des queries.

Activer la télémétrie de l'application

Pour activer la télémétrie pour une application, configurez un catalogue et un schéma pour les tables de télémétrie dans les paramètres de l'application.

UI

1. Ouvrez la page de détails de l'application dans votre Workspace Databricks.
2. Sous l'tab Paramètres , recherchez la section de configuration Télémétrie de l'application et cliquez sur Ajouter .
3. Saisissez ou parcourez pour sélectionner un catalogue et un schéma. Databricks écrit les données de télémétrie dans trois tables à l'emplacement sélectionné : otel_metrics, otel_spans et otel_logs.
4. (Facultatif) Spécifiez un préfixe de table afin que les tables soient nommées <prefix>_otel_metrics, <prefix>_otel_spans et <prefix>_otel_logs. Databricks ajoute des éléments aux tables existantes ou les crée si elles n'existent pas.
5. Cliquez sur Enregistrer .
6. Redéployez l'application afin que la télémétrie commence à être acheminée vers Unity Catalog.

CLI

1. Configurez la télémétrie à l'aide de la commande databricks apps update, en spécifiant les noms complets du catalogue, du schéma et de la table :

   Bash

   databricks apps update <app-name> --json '{
     "telemetry_export_destinations": [
       {
         "unity_catalog": {
           "logs_table": "<catalog>.<schema>.<your-prefix>-otel_logs",
           "metrics_table": "<catalog>.<schema>.otel_metrics",
           "traces_table": "<catalog>.<schema>.otel_spans"
         }
       }
     ]
   }'

2. Redéployez l'application afin que la télémétrie commence à être acheminée vers Unity Catalog :

   Bash

   databricks apps deploy <app-name>

Vérifier les données de télémétrie

La table otel_logs est remplie automatiquement après le redéploiement. Les tables otel_spans et otel_metrics ne sont renseignées qu'après avoir ajouté une instrumentation personnalisée à votre application.

Après avoir redéployé l'application :

1. Visitez l’URL de l’application pour générer de l’activité.

2. Patientez quelques secondes pour que le batch initial de données apparaisse.

3. Exécutez la query suivante dans Databricks SQL pour confirmer le flux de données :

   SQL

   SELECT * FROM <catalog>.<schema>.otel_logs
   LIMIT 10;

Query les données de télémétrie

Les colonnes utiles pour filtrer et corréler les données de télémétrie incluent time, service_name, trace_id, span_id et attributes. La colonne attributes est une map qui contient des métadonnées spécifiques aux événements, telles que event.name.

Pour afficher le schéma complet de toute table de télémétrie, exécutez :

SQL

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

La query d'exemple suivante recherche les logs de niveau d'erreur de la dernière heure, ce qui est utile pour le debugging des problèmes d'application :

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;

Query les événements système

Databricks capture automatiquement les événements système dans la table otel_logs, tels que les événements d’utilisation pour les connexions utilisateur et les requêtes API directes. Interrogez ces événements en filtrant sur l’attribut event.name.

L'exemple suivant récupère les 100 événements d'utilisation les plus récents pour une application :

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;

Ajouter une instrumentation personnalisée

Ajoutez l'auto-instrumentation OpenTelemetry pour générer des traces, des métriques et des logs personnalisés. Mettez à jour vos app.yaml et fichiers de dépendance comme indiqué pour votre framework.

Streamlit

Mise à jour app.yaml:

YAML

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

Mise à jour 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

Dash

Mise à jour app.yaml:

YAML

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

Mise à jour 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

Mise à jour app.yaml:

YAML

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

Mise à jour requirements.txt:

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

FastAPI

Mise à jour app.yaml:

YAML

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

Mise à jour requirements.txt:

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

Node.js

Créer un fichier 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);

Mise à jour 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"
  }
}

Variables d'environnement

Lorsque vous activez la télémétrie de l'application, Databricks configure automatiquement les variables d'environnement dans l'exécution de votre application pour l'endpoint du collecteur OTLP, le protocole d'exportation, les attributs de ressource et le traitement par batch. Pour la liste complète des variables d'environnement OTel, consultez les variables d'environnement de télémétrie d'application.

Limites et limitations

La télémétrie d'application utilise le connecteur Zerobus Ingest pour écrire des données dans les tables Unity Catalog. Toutes les limitations du connecteur Zerobus Ingest s'appliquent à la télémétrie d'application, y compris les limites sur la taille des enregistrements, le throughput, les garanties de livraison et les exigences de la table cible.

En plus des limites de Zerobus, la télémétrie de l'application applique une taille maximale de 1 Mo par ligne de log.