OpenTelemetry

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

额外依赖

如果你是从源码或通过 pip 运行 Open WebUI（也就是不使用官方 Docker 镜像），OpenTelemetry 依赖项可能不会默认安装。你可能需要手动安装它们：

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

🚀 使用 Docker Compose 快速开始

启用可观测性的最快方式是下载示例 Compose 文件并启动一个本地 Grafana LGTM 栈与 Open WebUI：

curl -fsSLO https://docs.openwebui.com/docker-compose.otel.yaml
docker compose -f docker-compose.otel.yaml up -d

docker-compose.otel.yaml 文件会配置以下组件：

服务	端口	描述
lgtm	3000（UI）、4317（OTLP/gRPC）、4318（HTTP）	Grafana LGTM（Loki + Grafana + Tempo + Mimir）栈
open-webui	8088 → 8080	启用了 OTEL 导出的 Open WebUI

启动后：

Open WebUI 可以在 http://localhost:8088 访问
Grafana 可以在 http://localhost:3000 访问，默认账号 admin / admin
Open WebUI 在 Compose 网络内通过 http://lgtm:4317 发送 OTLP 数据

⚙️ 环境变量

你可以使用下面这些环境变量（与 Compose 文件中的配置一致）在 Open WebUI 中配置 OpenTelemetry：

变量	默认值	描述
`ENABLE_OTEL`	在 Compose 中为 true	OpenTelemetry 的总开关
`ENABLE_OTEL_TRACES`	在 Compose 中为 true	启用分布式追踪导出
`ENABLE_OTEL_METRICS`	在 Compose 中为 true	启用 FastAPI HTTP 指标导出
`ENABLE_OTEL_LOGS`	在 Compose 中为 true	启用 OpenTelemetry 日志导出
`OTEL_EXPORTER_OTLP_ENDPOINT`	在 Compose 中为 `http://lgtm:4317`	用于追踪的 OTLP 端点
`OTEL_METRICS_EXPORTER_OTLP_ENDPOINT`	在 Compose 中为 `http://lgtm:4317`	用于指标的 OTLP 端点
`OTEL_LOGS_EXPORTER_OTLP_ENDPOINT`	在 Compose 中为 `http://lgtm:4317`	用于日志的 OTLP 端点
`OTEL_EXPORTER_OTLP_INSECURE`	在 Compose 中为 true	使用不安全连接（无 TLS）连接 OTLP
`OTEL_SERVICE_NAME`	`open-webui`	服务名称（会显示在追踪和指标中）
`OTEL_METRICS_EXPORT_INTERVAL_MILLIS`	`10000`	指标导出间隔（毫秒）（10 秒约等于 6 次/分钟；`60000` 约 1 次/分钟）
`OTEL_BASIC_AUTH_USERNAME` / `OTEL_BASIC_AUTH_PASSWORD`	(为空)	如果收集器需要，可配置基本认证凭据

提示

你可以根据需要在 .env 文件或 Compose 文件中覆盖默认值。

  open-webui:
    environment:
      - ENABLE_OTEL=true
      - ENABLE_OTEL_TRACES=true
      - ENABLE_OTEL_METRICS=true
      - ENABLE_OTEL_LOGS=true
      - OTEL_EXPORTER_OTLP_INSECURE=true # OTLP 使用不安全连接；生产环境中你可能希望移除这一项
      - 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
      # 如有需要，可在此设置 OTEL_BASIC_AUTH_USERNAME/PASSWORD

📊 数据收集

分布式追踪

Open WebUI 后端自动检测：

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

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

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`	直方图	ms	同上

指标会通过 OTLP 发送（默认每 10 秒一次，可通过 OTEL_METRICS_EXPORT_INTERVAL_MILLIS 配置），并可以在 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_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

🚨 故障排除

追踪/指标没有显示在 Grafana 中？

仔细检查 ENABLE_OTEL、ENABLE_OTEL_TRACES 和 ENABLE_OTEL_METRICS 是否都设为 true
端点是否正确？在示例 Compose 中，必须能从 Open WebUI 容器内以 http://lgtm:4317 访问该端点。
检查 Open WebUI 日志（docker logs open-webui-otel）以查找 OTLP 错误
收集器的 OTLP 端口（4317）应保持开放且可达。可以尝试： curl http://localhost:4317 (根据需要替换主机)

需要认证？

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

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议以了解适用条款。

🚀 使用 Docker Compose 快速开始​

⚙️ 环境变量​

📊 数据收集​

分布式追踪​

指标收集​

🔧 自定义收集器设置​

🚨 故障排除​