🔭 OpenTelemetry

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

🚀 使用 Docker Compose 快速开始

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

# Spin up Open WebUI and the latest Grafana LGTM stack, all-in-one
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 上暴露

启动后，通过 https://:3000 访问 Grafana 仪表盘。
登录: admin / admin

⚙️ 环境变量

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

变量	默认	描述
`ENABLE_OTEL`	Compose 中为 true	启用 OpenTelemetry 追踪
`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`	（空）	如果收集器需要，提供基本身份验证凭据

提示：根据需要，在您的 .env 文件或 Compose 文件中覆盖默认设置。

  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

📊 数据收集

分布式追踪

Open WebUI 后端自动检测：

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

每个追踪跨度都包含丰富的D据，例如：

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

指标收集

WebUI 通过 OpenTelemetry 导出以下指标：

指标类型	类型	单位	标签
`http.server.requests`	计数器	1	`http.method`, `http.route`, `http.status_code`
`http.server.duration`	直方图	毫秒	（同上）

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

🔧 自定义收集器设置

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

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

🚨 故障排除

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

仔细检查 ENABLE_OTEL 和 ENABLE_OTEL_METRICS 是否都设置为 true
端点是否正确？(OTEL_EXPORTER_OTLP_ENDPOINT)
检查 Open WebUI 的日志 (docker logs open-webui) 以查找 OTLP 错误
收集器的 OTLP 端口 (4317) 应该开放且可访问。尝试：
curl https://:4317 （根据需要替换主机）

需要身份验证？

对于受身份验证保护的收集器，设置 OTEL_BASIC_AUTH_USERNAME 和 OTEL_BASIC_AUTH_PASSWORD
如果使用 SSL/TLS，请酌情调整或移除 OTEL_EXPORTER_OTLP_INSECURE

🚀 使用 Docker Compose 快速开始​

⚙️ 环境变量​

📊 数据收集​

分布式追踪​

指标收集​

🔧 自定义收集器设置​

🚨 故障排除​