OpenTelemetry 监控

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

额外依赖项

如果您是从源码运行 Open WebUI 或通过 pip（而非官方的 Docker 镜像）进行安装的，默认情况下可能没有安装 OpenTelemetry 依赖项。您可能需要手动安装它们：

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

🚀 使用 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	WebUI，已启用 OTel，暴露在宿主机的 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 Collector 端点 URL
OTEL_EXPORTER_OTLP_INSECURE	在 Compose 中为 true	OTLP 使用非安全（无 TLS）连接
OTEL_SERVICE_NAME	open-webui	服务名称（用于在追踪和指标中进行标记）
OTEL_METRICS_EXPORT_INTERVAL_MILLIS	10000	指标导出间隔时间，单位为毫秒（10s = 约每分钟 6 次 (DPM)；若设为 60000 则约每分钟 1 次 (DPM)）
OTEL_BASIC_AUTH_USERNAME / OTEL_BASIC_AUTH_PASSWORD	(空)	如果 Collector 需要，则在此提供 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 后端会自动对以下组件进行监测：

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

每个追踪跨度 (trace 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 秒发送一次，可通过 OTEL_METRICS_EXPORT_INTERVAL_MILLIS 进行配置），并可在 Grafana 中（通过 Prometheus/Mimir）进行可视化展示。

🔧 自定义 Collector 设置

要使用其他的（外部）OpenTelemetry Collector/Stack：

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 中看不到 Trace/Metrics？

• 双击检查 ENABLE_OTEL、ENABLE_OTEL_TRACES 和 ENABLE_OTEL_METRICS 是否全部被设置为 true。
• 端点设置正确吗？（检查 OTEL_EXPORTER_OTLP_ENDPOINT）
• 检查 Open WebUI 的日志（docker logs open-webui）中是否有 OTLP 错误。
• Collector 的 OTLP 端口 (4317) 应该开放且可被访问。可以尝试： curl http://localhost:4317（根据需要替换为主机地址）

需要身份验证？

• 对于受认证保护的 Collector，请设置 OTEL_BASIC_AUTH_USERNAME 和 OTEL_BASIC_AUTH_PASSWORD。
• 如果使用 SSL/TLS，请根据需要调整或删除 OTEL_EXPORTER_OTLP_INSECURE。