Konfigurieren der Telemetrie für Databricks-Apps

Die Databricks Apps Telemetrie sammelt Traces, Logs und Metriken und speichert diese mithilfe des OpenTelemetry-Protokolls (OTel) in Unity-Katalogtabellen. Nachdem Sie Die App-Telemetrie aktiviert haben, erfasst Databricks automatisch Systemprotokolle und Nutzungsereignisse, z. B. Benutzeranmeldungs- und direkte API-Anforderungen. Sie können auch benutzerdefinierte Instrumentierung mithilfe des OpenTelemetry SDK für Ihr Framework hinzufügen.

Anforderungen

• Ihr Arbeitsbereich muss sich in einer unterstützten Region befinden: australiaeast, brazilsouth, canadacentral, centralindia, centralus, eastus, eastus2, germanywestcentral, northcentralus, northeurope, southcentralus, southeastasia, swedencentral, switzerlandnorth, uksouth, westeurope, westus, westus2, westus3.

• Zum Erstellen neuer Telemetriezieltabellen im Unity-Katalog benötigen CAN MANAGE Sie Berechtigungen für den Zielkatalog und das Schema sowie CREATE TABLE für das Schema.
• Wenn Sie in vorhandene Telemetriezieltabellen im Unity-Katalog schreiben möchten, benötigen Sie entweder CAN MANAGE-Berechtigungen für den Zielkatalog und das Schema, oder alle Kontobenutzer müssen über USE CATALOG, USE SCHEMA, SELECT und MODIFY für die Zieltabellen verfügen.
• Zieltabellen müssen verwaltete Delta-Tabellen in derselben Region wie Ihr Arbeitsbereich sein.
• Databricks empfiehlt die Aktivierung der prädiktiven Optimierung in den Telemetriezieltabellen für eine bessere Abfrageleistung.

Aktivieren der App-Telemetrie

Um Telemetrie für eine App zu aktivieren, konfigurieren Sie einen Katalog und ein Schema für die Telemetrietabellen in den App-Einstellungen.

1. Öffnen Sie die Seite mit den App-Details in Ihrem Azure Databricks-Arbeitsbereich.
2. Suchen Sie auf der Registerkarte "Übersicht" den Abschnitt " App-Telemetriekonfiguration ", und klicken Sie auf "Hinzufügen".
3. Geben Sie einen Katalog und ein Schema ein, oder navigieren Sie, um einen Katalog und ein Schema auszuwählen. Azure Databricks schreibt Telemetriedaten in drei Tabellen am ausgewählten Speicherort: otel_metrics, , otel_spansund otel_logs.
4. (Optional) Geben Sie ein Tabellenpräfix an, sodass Tabellen benannt <prefix>_otel_metricswerden, <prefix>_otel_spansund <prefix>_otel_logs. Azure Databricks fügt vorhandene Tabellen an oder erstellt sie, wenn sie nicht vorhanden sind.
5. Klicke auf Speichern.
6. Stellen Sie die App erneut bereit, damit die Telemetrie zum Unity-Katalog zu fließen beginnt.

Überprüfen von Telemetriedaten

Die otel_logs Tabelle wird nach der erneuten Bereitstellung automatisch aufgefüllt. Die otel_spans- und otel_metrics-Tabellen werden erst gefüllt, nachdem Sie Ihrer App benutzerdefinierte Instrumentierung hinzugefügt haben.

Nach der erneuten Bereitstellung der App:

1. Besuchen Sie die App-URL, um Aktivitäten zu generieren.

2. Warten Sie einige Sekunden, bis der anfängliche Datenbatch angezeigt wird.

3. Führen Sie die folgende Abfrage in Databricks SQL aus, um zu bestätigen, dass Daten fließen:

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

Telemetriedaten abfragen

Nützliche Spalten zum Filtern und Korrelieren von Telemetriedaten sind time, service_name, trace_id, span_id und attributes. Die attributes Spalte ist eine Map, die ereignisspezifische Metadaten enthält, z. B. event.name.

Führen Sie Folgendes aus, um das vollständige Schema einer telemetrietabelle anzuzeigen:

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

Das folgende Beispiel fragt die otel_logs Tabelle nach System- oder benutzerdefinierten OpenTelemetry ERROR-Protokollen innerhalb der letzten Stunde ab:

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;

Hinzufügen einer benutzerdefinierten Instrumentierung

Fügen Sie die automatische OpenTelemetry-Instrumentierung hinzu, um benutzerdefinierte Ablaufverfolgungen, Metriken und Protokolle zu generieren. Aktualisieren Sie die app.yaml-Dateien und Abhängigkeitsdateien, wie für Ihr Framework gezeigt.

Streamlit

Aktualisieren Sie app.yaml:

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

Aktualisieren Sie 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

Gedankenstrich

Aktualisieren Sie app.yaml:

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

Aktualisieren Sie 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

Aktualisieren Sie app.yaml:

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

Aktualisieren Sie requirements.txt:

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

FastAPI

Aktualisieren Sie app.yaml:

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

Aktualisieren Sie requirements.txt:

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

Node.js

Erstellen Sie eine Datei vom Typ 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);

Aktualisieren Sie 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"
  }
}

Umgebungsvariablen

Wenn Sie App-Telemetrie aktivieren, konfiguriert Databricks Umgebungsvariablen automatisch in Ihrer App-Laufzeit für den OTLP-Sammelendpunkt, das Exportprotokoll, Ressourcenattribute und die Batchverarbeitung. Die vollständige Liste der OTel-Umgebungsvariablen finden Sie unter App-Telemetrieumgebungsvariablen.

Grenzwerte und Einschränkungen

App-Telemetrie verwendet den Zerobus Ingest-Connector zum Schreiben von Daten in Unity-Katalogtabellen. Alle Einschränkungen des Zerobus Ingest-Connectors gelten für App-Telemetrie, einschließlich Grenzwerten für Datensatzgröße, Durchsatz, Übermittlungsgarantien und Anforderungen an die Zieltabelle.

Zusätzlich zu Zerobus-Grenzwerten erzwingt die App-Telemetrie eine maximale Protokollzeilengröße von 1 MB pro Protokollzeile.