跳到主要内容

可观测性

Libre WebUI 为运维人员提供两条可观测性路径：

  • 写入本地标准输出和错误输出的结构化应用日志；
  • 可选 OpenTelemetry 导出器，用于 HTTP 请求、持久任务、计数器和警告/错误日志。

两者都不会向 Libre WebUI 项目发送遥测。只有运维人员配置收集器端点后， OpenTelemetry 才会启用。管理员的系统与用量页面是独立的： 它们从部署自身读取诊断和用量，而不是从 OpenTelemetry 收集器读取。

结构化日志​

默认 LOG_FORMAT=text 保留熟悉的作用域控制台输出。设置 LOG_FORMAT=json 可让每行输出一个 JSON 对象：

LOG_LEVEL=info
LOG_FORMAT=json

每行包含：

  • ISO 时间戳；
  • 级别和日志记录器作用域；
  • 消息；
  • 当前请求或持久任务的关联 ID（如果存在）；以及
  • 调用者提供的有限结构化详情。

每个 HTTP 请求都会获得 X-Request-Id。Libre 只接受由字母、数字、.、_ 或 - 组成且长度为 8–64 的传入 ID，否则创建 UUID。ID 会在响应中返回，并随 异步工作进入日志上下文。访问日志记录 HTTP 方法、路径、状态和时长，但移除查询串， 因为查询参数可能含用户内容或短期凭据。

LOG_LEVEL 接受 silent、error、warn、info 或 debug。调试日志可能暴露 更多运维详情，只应在诊断问题时启用，并像其他部署数据一样保护。

脱敏边界​

结构化详情和导出遥测使用同一有限脱敏辅助程序：

  • 名称类似密码、密钥、令牌、授权、cookie、凭据、bearer 值或 JWT 的字段会省略；
  • 字符串最多 512 个字符；
  • 数组、嵌套深度和导出属性数受限；
  • 错误对象保留名称和有限消息，不保留任意对象图。

这是纵深防御，不代表可以记录提示词或秘密。字段名不具秘密特征的短用户字符串仍可能 成为普通日志文本。扩展应记录标识符和结果，而不是请求正文、提示词、文档文本、工具 结果或提供商负载。限制日志访问并应用运维保留策略。

启用 OpenTelemetry​

Libre 直接导出 OTLP/HTTP JSON，无需 OpenTelemetry SDK 依赖。将其指向接受标准 信号路径的收集器 HTTP 基础 URL：

OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui

导出器会附加 /v1/traces、/v1/metrics 和 /v1/logs。 OTEL_EXPORTER_OTLP_HEADERS 是逗号分隔的 key=value 对。将收集器凭据作为部署 密钥保存，不要提交。OTEL_SERVICE_NAME 默认为 libre-webui。

缺少端点变量时，span、指标和日志记录都是空操作，没有内容离开进程。团队部署中， 应用和外部 worker 独立导出；为各进程提供所需配置。按角色使用不同服务名可简化面板。

导出信号​

信号Libre 记录的内容
HTTP 服务器 span不含查询串的方法和路径、响应状态、时长、成功/失败状态和请求 ID
HTTP 计数器按方法和响应状态类统计的单调请求数
持久任务 span任务类型、尝试次数、时长和成功/失败状态
持久任务计数器按任务类型和结果统计的单调执行数
日志记录脱敏的警告和错误消息，含记录器作用域与请求/任务关联 ID

span 是本地已完成 span。Libre 目前不传播传入 OpenTelemetry trace parent，不在服务间 创建父子 span 树，也不检测浏览器渲染和每次提供商调用。模型令牌和媒体用量归入本地 用量分析和成本治理账本。

交付行为​

遥测明确采用尽力而为：

  • 缓冲最多保存 2,048 个 span 和 2,048 条日志，压力下丢弃最旧条目；
  • 最多保留 512 个计数器序列；
  • 导出器约每五秒刷新；
  • 每次 HTTP 导出超时三秒；
  • 收集器错误会丢弃该批次，绝不阻塞或使应用请求/持久任务失败。

因此导出器不是审计日志或持久计费系统。安全事件使用只追加安全审计日志，成本使用 SQL 用量账本，遥测保留和警报使用收集器自身功能。

故障排除​

**没有遥测到达。**确认准确应用或 worker 进程环境中存在 OTEL_EXPORTER_OTLP_ENDPOINT，只包含收集器基础 URL，并确认收集器在三个标准 路径接受 OTLP/HTTP JSON。

**收集器返回未授权。**检查逗号分隔标头语法以及收集器需要 authorization=Bearer ... 还是其他标头。更改环境变量后重启进程。

**收集器停机时请求仍成功。**这是预期行为。导出路径开放失败以保持应用可用性， 不会保存失败批次供重试。

**日志字段缺失或被截短。**秘密特征键会移除，长值或深层值会按设计受限。记录安全 标识符或摘要，而不要削弱脱敏边界。

相关文档​