diff --git a/docs/reference/monitoring/otel.md b/docs/reference/monitoring/otel.md index 2a84a699..a1be81ac 100644 --- a/docs/reference/monitoring/otel.md +++ b/docs/reference/monitoring/otel.md @@ -17,23 +17,25 @@ pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp ## 🚀 Quick Start with Docker Compose -The fastest way to get started with observability is with the pre-configured Docker Compose: +The fastest way to get started with observability is to download the example Compose file and start Open WebUI with a local Grafana LGTM stack: ```bash - -# Spin up Open WebUI and the latest Grafana LGTM stack, all-in-one +curl -fsSLO https://docs.openwebui.com/docker-compose.otel.yaml docker compose -f docker-compose.otel.yaml up -d ``` The `docker-compose.otel.yaml` file sets up these components: -| Service | Port(s) | Description | -|-------------|------------------------------------------|------------------------------------------------------| -| **grafana** | 3000 (UI), 4317 (OTLP/gRPC), 4318 (HTTP) | Grafana LGTM (Loki+Grafana+Tempo+Mimir) all-in-one | -| **open-webui** | 8088 (default) → 8080 | WebUI, OTEL enabled, exposes on host port 8088 | +| Service | Port(s) | Description | +| -------------- | ----------------------------------------- | -------------------------------------------------- | +| **lgtm** | 3000 (UI), 4317 (OTLP/gRPC), 4318 (HTTP) | Grafana LGTM (Loki + Grafana + Tempo + Mimir) stack | +| **open-webui** | 8088 → 8080 | Open WebUI with OTEL export enabled | -After startup, access the Grafana dashboard at [http://localhost:3000](http://localhost:3000) -Login: `admin` / `admin` +After startup: + +- Open WebUI is available at [http://localhost:8088](http://localhost:8088) +- Grafana is available at [http://localhost:3000](http://localhost:3000) with `admin` / `admin` +- Open WebUI sends OTLP data to `http://lgtm:4317` from inside the Compose network ## ⚙️ Environment Variables @@ -44,7 +46,10 @@ You can configure OpenTelemetry in Open WebUI with these environment variables ( | `ENABLE_OTEL` | **true** in Compose | Master switch to enable OpenTelemetry setup | | `ENABLE_OTEL_TRACES` | **true** in Compose | Enable distributed tracing export | | `ENABLE_OTEL_METRICS` | **true** in Compose | Enable FastAPI HTTP metrics export | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://grafana:4317` in Compose| OTLP gRPC/HTTP Collector endpoint URL | +| `ENABLE_OTEL_LOGS` | **true** in Compose | Enable OpenTelemetry log export | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://lgtm:4317` in Compose | OTLP endpoint used for traces | +| `OTEL_METRICS_EXPORTER_OTLP_ENDPOINT`| `http://lgtm:4317` in Compose | OTLP endpoint used for metrics | +| `OTEL_LOGS_EXPORTER_OTLP_ENDPOINT` | `http://lgtm:4317` in Compose | OTLP endpoint used for logs | | `OTEL_EXPORTER_OTLP_INSECURE` | **true** in Compose | Insecure (no TLS) connection for OTLP | | `OTEL_SERVICE_NAME` | `open-webui` | Service name (tagged in traces and metrics) | | `OTEL_METRICS_EXPORT_INTERVAL_MILLIS`| `10000` | Metrics export interval in ms (10s = ~6 DPM; set `60000` for ~1 DPM) | @@ -62,8 +67,11 @@ Override defaults in your `.env` file or Compose file as needed. - ENABLE_OTEL=true - ENABLE_OTEL_TRACES=true - ENABLE_OTEL_METRICS=true + - ENABLE_OTEL_LOGS=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_EXPORTER_OTLP_ENDPOINT=http://lgtm:4317 + - OTEL_METRICS_EXPORTER_OTLP_ENDPOINT=http://lgtm:4317 + - OTEL_LOGS_EXPORTER_OTLP_ENDPOINT=http://lgtm:4317 - OTEL_SERVICE_NAME=open-webui # You may set OTEL_BASIC_AUTH_USERNAME/PASSWORD here if needed ``` @@ -108,6 +116,8 @@ docker run -d --name open-webui \ -e ENABLE_OTEL_METRICS=true \ -e OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317 \ -e OTEL_EXPORTER_OTLP_INSECURE=true \ + -e OTEL_METRICS_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317 \ + -e OTEL_LOGS_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317 \ -e OTEL_SERVICE_NAME=open-webui \ -v open-webui:/app/backend/data \ ghcr.io/open-webui/open-webui:main @@ -118,8 +128,8 @@ docker run -d --name open-webui \ **Traces/metrics not appearing in Grafana?** - Double-check `ENABLE_OTEL`, `ENABLE_OTEL_TRACES`, and `ENABLE_OTEL_METRICS` are all set to `true` -- Is the endpoint correct? (`OTEL_EXPORTER_OTLP_ENDPOINT`) -- Inspect logs from Open WebUI (`docker logs open-webui`) for OTLP errors +- Is the endpoint correct? In the example Compose file it must be reachable as `http://lgtm:4317` from the Open WebUI container. +- Inspect logs from Open WebUI (`docker logs open-webui-otel`) for OTLP errors - Collector's OTLP port (`4317`) should be open and reachable. Try: `curl http://localhost:4317` (replace host as needed) diff --git a/static/docker-compose.otel.yaml b/static/docker-compose.otel.yaml new file mode 100644 index 00000000..0ec7ab43 --- /dev/null +++ b/static/docker-compose.otel.yaml @@ -0,0 +1,39 @@ +services: + lgtm: + image: grafana/otel-lgtm:latest + container_name: open-webui-lgtm + restart: unless-stopped + ports: + - "3000:3000" # Grafana UI + - "4317:4317" # OTLP gRPC receiver + - "4318:4318" # OTLP HTTP receiver + volumes: + - lgtm-data:/data + + open-webui: + image: ghcr.io/open-webui/open-webui:main + container_name: open-webui-otel + restart: unless-stopped + depends_on: + - lgtm + ports: + - "8088:8080" + environment: + ENABLE_OTEL: "true" + ENABLE_OTEL_TRACES: "true" + ENABLE_OTEL_METRICS: "true" + ENABLE_OTEL_LOGS: "true" + OTEL_SERVICE_NAME: open-webui + OTEL_EXPORTER_OTLP_ENDPOINT: http://lgtm:4317 + OTEL_EXPORTER_OTLP_INSECURE: "true" + OTEL_METRICS_EXPORTER_OTLP_ENDPOINT: http://lgtm:4317 + OTEL_METRICS_EXPORTER_OTLP_INSECURE: "true" + OTEL_LOGS_EXPORTER_OTLP_ENDPOINT: http://lgtm:4317 + OTEL_LOGS_EXPORTER_OTLP_INSECURE: "true" + OTEL_METRICS_EXPORT_INTERVAL_MILLIS: "10000" + volumes: + - open-webui:/app/backend/data + +volumes: + lgtm-data: + open-webui: