OpenTelemetry

Open WebUI 支持通过 OpenTelemetry (OTel) 协议 (OTLP) 导出 分布式追踪和指标。这使得您可以与现代可观测性技术栈（如 Grafana LGTM (Loki, Grafana, Tempo, Mimir)）以及 Jaeger、Tempo 和 Prometheus 集成，从而实时监控请求、数据库/Redis 查询、响应时间等。

🚀 使用 Docker Compose 快速开始

开始使用可观测性最快的方法是使用预先配置好的 Docker Compose：

# 一键启动 Open WebUI 和最新的 Grafana LGTM 栈
docker compose -f docker-compose.otel.yaml up -d

docker-compose.otel.yaml 文件设置了以下组件：

服务	端口	描述
grafana	3000 (UI), 4317 (OTLP/gRPC), 4318 (HTTP)	Grafana LGTM (Loki+Grafana+Tempo+Mimir) 一体化方案
open-webui	8088 (默认) → 8080	已启用 OTEL 的 WebUI，在宿主机 8088 端口公开

启动后，通过以下地址访问 Grafana 仪表板：http://localhost:3000 登录信息：admin / admin

⚙️ 环境变量

您可以通过以下环境变量在 Open WebUI 中配置 OpenTelemetry（如 Compose 文件中所用）：

变量	默认值	描述
`ENABLE_OTEL`	在 Compose 中为 true	启用 OpenTelemetry 设置的主开关
`ENABLE_OTEL_TRACES`	在 Compose 中为 true	启用分布式追踪导出
`ENABLE_OTEL_METRICS`	在 Compose 中为 true	启用 FastAPI HTTP 指标导出
`OTEL_EXPORTER_OTLP_ENDPOINT`	在 Compose 中为 `http://grafana:4317`	OTLP gRPC/HTTP 收集器端点 URL
`OTEL_EXPORTER_OTLP_INSECURE`	在 Compose 中为 true	OTLP 的非安全连接（无 TLS）
`OTEL_SERVICE_NAME`	`open-webui`	服务名称（在追踪和指标中标记）
`OTEL_BASIC_AUTH_USERNAME` / `OTEL_BASIC_AUTH_PASSWORD`	(空)	如果收集器需要，则设置 Basic Auth 凭据

提示

根据需要，在您的 .env 文件或 Compose 文件中覆盖默认值。

  open-webui:
    environment:
      - ENABLE_OTEL=true
      - ENABLE_OTEL_TRACES=true
      - ENABLE_OTEL_METRICS=true
      - OTEL_EXPORTER_OTLP_INSECURE=true # 为 OTLP 使用非安全连接，在生产环境中您可能需要移除此项
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://grafana:4317
      - OTEL_SERVICE_NAME=open-webui
      # 如果需要，您可以在此处设置 OTEL_BASIC_AUTH_USERNAME/PASSWORD

📊 数据收集

分布式追踪

Open WebUI 后端会自动对以下内容进行插桩（Instrumentation）：

FastAPI（路由）
SQLAlchemy（数据库查询）
Redis
requests, httpx, aiohttp（外部调用）

每个追踪跨度（Span）都包含丰富的数据，例如：

db.instance, db.statement, redis.args
http.url, http.method, http.status_code
异常时的错误详情 (error.message, error.kind)

指标收集

WebUI 通过 OpenTelemetry 导出以下指标：

仪表	类型	单位	标签
`http.server.requests`	Counter	1	`http.method`, `http.route`, `http.status_code`
`http.server.duration`	Histogram	ms	(同上)

指标通过 OTLP 发送（默认每 10 秒一次），并可以在 Grafana 中（通过 Prometheus/Mimir）进行可视化。

🔧 自定义收集器设置

要使用不同的（外部）OpenTelemetry 收集器/技术栈：

docker run -d --name open-webui \
  -p 8088:8080 \
  -e ENABLE_OTEL=true \
  -e ENABLE_OTEL_TRACES=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

🚨 故障排除

追踪/指标未在 Grafana 中显示？

再次检查 ENABLE_OTEL、ENABLE_OTEL_TRACES 和 ENABLE_OTEL_METRICS 是否都设置为 true
端点是否正确？ (OTEL_EXPORTER_OTLP_ENDPOINT)
查看 Open WebUI 的日志 (docker logs open-webui) 以获取 OTLP 错误
收集器的 OTLP 端口 (4317) 应该是开放且可达的。尝试： curl http://localhost:4317（根据需要替换主机名）

需要身份验证？

为受认证保护的收集器设置 OTEL_BASIC_AUTH_USERNAME 和 OTEL_BASIC_AUTH_PASSWORD
如果使用 SSL/TLS，请相应地调整或移除 OTEL_EXPORTER_OTLP_INSECURE

🚀 使用 Docker Compose 快速开始​

⚙️ 环境变量​

📊 数据收集​

分布式追踪​

指标收集​

🔧 自定义收集器设置​

🚨 故障排除​