OpenTelemetry

OPL 数据空间支持通过 OpenTelemetry（OTel）协议导出分布式追踪和指标。这让你可以把它接入 Grafana LGTM（Loki、Grafana、Tempo、Mimir）、Jaeger、Tempo、Prometheus 等现代可观测性系统，实时观察请求、数据库 / Redis 查询、响应时延等信息。

额外依赖

如果你是通过源码或 pip 运行 OPL 数据空间，而不是官方 Docker 镜像，OpenTelemetry 依赖不一定默认安装。你可能需要手动安装：

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

🚀 用 Docker Compose 快速启动

最快的体验方式，是直接使用预配置好的 Compose 文件：

docker compose -f docker-compose.otel.yaml up -d

docker-compose.otel.yaml 会启动以下组件：

服务	端口	说明
grafana	3000（UI）、4317（OTLP/gRPC）、4318（HTTP）	Grafana LGTM 一体化栈
open-webui	8088（宿主）→ 8080（容器）	开启 OTEL 的 OPL 数据空间

启动后可以访问 http://localhost:3000
登录：admin / admin

⚙️ 环境变量

可通过这些环境变量控制 OpenTelemetry：

变量	默认值	说明
`ENABLE_OTEL`	Compose 中为 `true`	总开关
`ENABLE_OTEL_TRACES`	Compose 中为 `true`	是否导出 trace
`ENABLE_OTEL_METRICS`	Compose 中为 `true`	是否导出 FastAPI HTTP metrics
`OTEL_EXPORTER_OTLP_ENDPOINT`	Compose 中为 `http://grafana:4317`	OTLP 收集端点
`OTEL_EXPORTER_OTLP_INSECURE`	Compose 中为 `true`	是否禁用 TLS
`OTEL_SERVICE_NAME`	`open-webui`	trace / metrics 中的服务名
`OTEL_METRICS_EXPORT_INTERVAL_MILLIS`	`10000`	指标导出周期（毫秒）
`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
    - OTEL_EXPORTER_OTLP_ENDPOINT=http://grafana:4317
    - OTEL_SERVICE_NAME=open-webui

📊 会采集什么？

分布式追踪

OPL 数据空间后端会自动为这些组件打点：

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

每个 span 通常会包含以下信息：

db.instance、db.statement、redis.args
http.url、http.method、http.status_code
异常时的 error.message、error.kind

指标

默认会导出以下 HTTP 指标：

指标	类型	单位	标签
`http.server.requests`	Counter	1	`http.method`、`http.route`、`http.status_code`
`http.server.duration`	Histogram	ms	与上面相同

指标默认每 10 秒通过 OTLP 发送一次，周期可用 OTEL_METRICS_EXPORT_INTERVAL_MILLIS 调整。你可以在 Grafana 中通过 Prometheus / Mimir 做可视化。

🔧 接外部 Collector

如果你要把 OPL 数据空间接到外部 OTel Collector：

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 是否正确
查看 OPL 数据空间日志：docker logs open-webui
确认 Collector 的 4317 端口可达

Collector 需要认证？

设置 OTEL_BASIC_AUTH_USERNAME 和 OTEL_BASIC_AUTH_PASSWORD
如果你启用了 TLS，请相应调整或移除 OTEL_EXPORTER_OTLP_INSECURE

🚀 用 Docker Compose 快速启动​

⚙️ 环境变量​

📊 会采集什么？​

分布式追踪​

指标​

🔧 接外部 Collector​

🚨 排障​