🔭 OpenTelemetry

Open WebUI unterstützt den Export von verteiltem Tracing und Metriken über das OpenTelemetry (OTel) Protokoll (OTLP). Dies ermöglicht die Integration mit modernen Observability-Stacks wie Grafana LGTM (Loki, Grafana, Tempo, Mimir) sowie Jaeger, Tempo und Prometheus zur Echtzeitüberwachung von Anfragen, Datenbank-/Redis-Abfragen, Antwortzeiten und mehr.

🚀 Schneller Start mit Docker Compose

Der schnellste Weg, um mit Observability zu beginnen, ist die vorkonfigurierte Docker Compose-Datei.

# Spin up Open WebUI and the latest Grafana LGTM stack, all-in-one
docker compose -f docker-compose.otel.yaml up -d

Die Datei docker-compose.otel.yaml richtet diese Komponenten ein.

Dienst	Port(s)	Beschreibung
grafana	3000 (UI), 4317 (OTLP/gRPC), 4318 (HTTP)	Grafana LGTM (Loki+Grafana+Tempo+Mimir) All-in-One
open-webui	8088 (Standard) → 8080	WebUI, OTEL-aktiviert, auf Host-Port 8088 exponiert.

Nach dem Start greifen Sie auf das Grafana-Dashboard unter https://:3000 zu.
Login: admin / admin

⚙️ Umgebungsvariablen

Sie können OpenTelemetry in Open WebUI mit diesen Umgebungsvariablen konfigurieren (wie in der Compose-Datei verwendet).

Variable	Standard	Beschreibung
ENABLE_OTEL	true in Compose	Aktiviert OpenTelemetry-Tracing.
ENABLE_OTEL_METRICS	true in Compose	Aktiviert den Export von FastAPI HTTP-Metriken.
OTEL_EXPORTER_OTLP_ENDPOINT	http://grafana:4317 in Compose	OTLP gRPC/HTTP Collector-Endpunkt-URL.
OTEL_EXPORTER_OTLP_INSECURE	true in Compose	Unsichere (ohne TLS) Verbindung für OTLP.
OTEL_SERVICE_NAME	open-webui	Dienstname (getaggt in Traces und Metriken).
OTEL_BASIC_AUTH_USERNAME / OTEL_BASIC_AUTH_PASSWORD	(leer)	Basic Auth-Anmeldeinformationen, falls der Collector diese benötigt.

Tipp: Überschreiben Sie die Standardwerte bei Bedarf in Ihrer .env-Datei oder Compose-Datei.

  open-webui:
    environment:
      - ENABLE_OTEL=true
      - ENABLE_OTEL_METRICS=true
      - OTEL_EXPORTER_OTLP_INSECURE=true # Use insecure connection for OTLP, you may want to remove this in production
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://grafana:4317
      - OTEL_SERVICE_NAME=open-webui
      # You may set OTEL_BASIC_AUTH_USERNAME/PASSWORD here if needed

📊 Datensammlung

Verteiltes Tracing

Das Open WebUI-Backend instrumentiert automatisch

• FastAPI (Routen)
• SQLAlchemy (Datenbankabfragen)
• Redis
• requests, httpx, aiohttp (externe Aufrufe)

Jeder Trace-Span enthält umfangreiche Daten wie

• db.instance, db.statement, redis.args
• http.url, http.method, http.status_code
• Fehlerdetails (error.message, error.kind) bei Ausnahmen.

Metrikensammlung

WebUI exportiert die folgenden Metriken über OpenTelemetry.

Instrument	Typ	Einheit	Labels
http.server.requests	Zähler	1	http.method, http.route, http.status_code
http.server.duration	Histogramm	ms	(wie oben)

Metriken werden über OTLP gesendet (standardmäßig alle 10 Sekunden) und können in Grafana (über Prometheus/Mimir) visualisiert werden.

🔧 Benutzerdefinierte Collector-Einrichtung

Um einen anderen (externen) OpenTelemetry Collector/Stack zu verwenden.

docker run -d --name open-webui \
  -p 8088:8080 \
  -e ENABLE_OTEL=true \
  -e ENABLE_OTEL_METRICS=true \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  -e OTEL_SERVICE_NAME=open-webui \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main

🚨 Fehlerbehebung

Traces/Metriken erscheinen nicht in Grafana?

• Überprüfen Sie doppelt, ob ENABLE_OTEL und ENABLE_OTEL_METRICS beide auf true gesetzt sind.
• Ist der Endpunkt korrekt? (OTEL_EXPORTER_OTLP_ENDPOINT)
• Überprüfen Sie die Logs von Open WebUI (docker logs open-webui) auf OTLP-Fehler.
• Der OTLP-Port des Collectors (4317) sollte offen und erreichbar sein. Versuchen Sie
  curl https://:4317 (ersetzen Sie den Host nach Bedarf).

Authentifizierung erforderlich?

• Setzen Sie OTEL_BASIC_AUTH_USERNAME und OTEL_BASIC_AUTH_PASSWORD für mit Authentifizierung geschützte Collector.
• Wenn Sie SSL/TLS verwenden, passen Sie OTEL_EXPORTER_OTLP_INSECURE entsprechend an oder entfernen Sie es.