agentic_huge_data_base / wiki
页面 Onyx · 12.3 可观测性与监控·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 12.3

12.3 · 可观测性与监控（Observability and Monitoring）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节12.3 状态全文译文 模块测试、发布与运维、接口与服务契约、工作流与编排、界面与交互
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Observability and Monitoring 上一章12.2 下一章12.4
源码线索
  • backend/ee/onyx/background/celery_utils.py
  • backend/ee/onyx/background/task_name_builders.py
  • backend/onyx/background/celery/tasks/monitoring/tasks.py
  • backend/onyx/background/task_utils.py
  • backend/onyx/chat/chat_processing_checker.py
  • backend/onyx/chat/stop_signal_checker.py
  • backend/onyx/connectors/google_site/connector.py
  • backend/onyx/connectors/jira/connector.py
  • backend/onyx/connectors/jira/utils.py
  • backend/onyx/federated_connectors/oauth_utils.py
模块标签
  • 测试、发布与运维
  • 接口与服务契约
  • 工作流与编排
  • 界面与交互
  • 认证、权限与安全

章节正文

可观测性与监控

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/12.3-observability-and-monitoring

可观测性与监控

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • backend/ee/onyx/background/celery_utils.py
  • backend/ee/onyx/background/task_name_builders.py
  • backend/onyx/background/celery/tasks/monitoring/tasks.py
  • backend/onyx/background/task_utils.py
  • backend/onyx/chat/chat_processing_checker.py
  • backend/onyx/chat/stop_signal_checker.py
  • backend/onyx/connectors/google_site/connector.py
  • backend/onyx/connectors/jira/connector.py
  • backend/onyx/connectors/jira/utils.py
  • backend/onyx/federated_connectors/oauth_utils.py
  • backend/onyx/key_value_store/factory.py
  • backend/onyx/key_value_store/store.py
  • backend/onyx/mcp_server_main.py
  • backend/onyx/server/features/release_notes/utils.py
  • backend/onyx/server/metrics/perm_sync_metrics.py
  • backend/onyx/utils/platform.py
  • backend/onyx/utils/telemetry.py
  • backend/tests/daily/connectors/confluence/test_confluence_basic.py
  • backend/tests/daily/connectors/confluence/test_confluence_permissions_basic.py
  • backend/tests/daily/connectors/jira/test_jira_basic.py
  • backend/tests/external_dependency_unit/connectors/confluence/test_confluence_group_sync.py
  • backend/tests/external_dependency_unit/connectors/google_drive/test_google_drive_group_sync.py
  • backend/tests/external_dependency_unit/connectors/jira/test_jira_doc_sync.py
  • backend/tests/external_dependency_unit/connectors/jira/test_jira_group_sync.py
  • backend/tests/unit/onyx/connectors/jira/test_jira_bulk_fetch.py
  • backend/tests/unit/onyx/connectors/jira/test_jira_checkpointing.py
  • backend/tests/unit/onyx/connectors/jira/test_jira_large_ticket_handling.py
  • backend/tests/unit/server/metrics/test_perm_sync_metrics.py
  • profiling/README.md
  • profiling/prometheus.yml

本文档介绍了 Onyx 的可观测性与监控基础设施，包括错误追踪、分析、健康检查、日志记录，以及针对 API 服务器和后台索引管线的 Prometheus 指标。

概述

Onyx 采用多层可观测性方案来确保系统可靠性和性能：

  • 错误追踪：通过 Sentry 集成后端（FastAPI）和前端（Next.js）。
  • 产品分析：集成 PostHog，并配置自定义代理。
  • 健康检查：提供 HTTP 端点供编排器探针和外部服务校验使用。
  • 日志记录：标准化日志，包含租户上下文和延迟追踪。
  • 运维指标：Prometheus 收集器，用于监控数据库连接池健康、Celery 队列深度和索引进度。

来源：backend/onyx/main.py:329-336, backend/onyx/background/celery/tasks/monitoring/tasks.py:145-170, backend/onyx/utils/telemetry.py:99-106

错误追踪（Sentry）

Sentry 提供实时异常监控。系统采用多环境配置，以捕获不同执行上下文中的错误。

后端 Sentry 配置

后端在创建 FastAPI 应用时初始化 Sentry。它集成了 Starlette 和 FastAPI，用于捕获未处理的异常和性能追踪。

后端 Sentry 初始化流程

Onyx · 后端 Sentry 配置 · 图 1
Onyx · 后端 Sentry 配置 · 图 1

来源：backend/onyx/main.py:329-336

前端 Sentry 配置

Next.js 前端使用 @sentry/nextjs，并针对服务器、边缘和浏览器环境进行了特定配置。该功能根据构建时的环境变量（如 NEXT_PUBLIC_SENTRY_DSN）条件启用。

来源：web/next.config.js:159-188

产品分析（PostHog）

PostHog 追踪用户交互和系统里程碑事件。为防止广告拦截器干扰，Onyx 通过自身的 Next.js 后端代理 PostHog 流量。

PostHog 代理架构

Onyx · 产品分析（PostHog） · 图 2
Onyx · 产品分析（PostHog） · 图 2

来源：web/next.config.js:80-91, backend/onyx/utils/telemetry.py:181-193

指标收集（Prometheus）

Onyx 在 GET /metrics 端点暴露运维指标。这些指标分为 API 指标和后台基础设施指标。

1. API 和数据库指标

API 服务器使用自定义收集器来监控 SQLAlchemy 连接池健康和 API 性能。

指标名称类型描述
onyx_db_pool_checked_out仪表盘（Gauge）当前活跃的数据库连接数
onyx_db_pool_checked_in仪表盘（Gauge）连接池中的空闲连接数
onyx_db_pool_overflow仪表盘（Gauge）超出 pool_size 的连接数
onyx_api_slow_requests_total计数器（Counter）超过阈值的请求数
2. 索引管线指标

基础设施指标由 monitoring Celery 工作进程收集。这些指标用于监控后台任务健康状况和资源使用情况。

索引管线监控架构

Onyx · 2. 索引管线指标 · 图 3
Onyx · 2. 索引管线指标 · 图 3

关键实现细节：

  • 队列长度：_collect_queue_metrics 函数使用 celery_get_queue_length 监控 docfetching、docprocessing 和 vespa_metadata_sync 等队列 backend/onyx/background/celery/tasks/monitoring/tasks.py:145-170。
  • 进程内存：emit_process_memory 使用 psutil 追踪各工作进程的内存使用情况 backend/onyx/background/celery/tasks/monitoring/tasks.py:24-24。
  • 指标发送：Metric 类提供了标准接口，用于记录日志并通过 optional_telemetry 可选地发送遥测数据 backend/onyx/background/celery/tasks/monitoring/tasks.py:85-102。

来源：backend/onyx/background/celery/tasks/monitoring/tasks.py:1-170, backend/onyx/background/celery/celery_redis.py:22-22

健康检查与遥测

健康端点
  • 存活探针：/health（默认 FastAPI 检查）。
  • 就绪状态：/api/manage/get-state 报告系统就绪状态。
  • MCP 服务器：模型上下文协议（MCP）服务器包含自己的 uvicorn 入口点和追踪配置 backend/onyx/mcp_server_main.py:15-32。
遥测系统

optional_telemetry 函数负责处理匿名使用报告。在多租户环境中，它使用 uuid5 生成稳定的匿名租户标识符。

遥测数据流

Onyx · 遥测系统 · 图 4
Onyx · 遥测系统 · 图 4

来源：backend/onyx/utils/telemetry.py:99-150, backend/onyx/utils/telemetry.py:49-51

日志记录与性能追踪

Onyx 使用标准 Python 日志记录，并针对生产环境进行了特定增强：

  • 结构化指标：监控任务中的 Metric 模型会记录结构化 JSON，供日志聚合器入库 backend/onyx/background/celery/tasks/monitoring/tasks.py:93-100。
  • 键值存储：关键配置和实例元数据（如 KV_CUSTOMER_UUID_KEY）持久化存储在混合的 Postgres/Redis PgRedisKVStore 中 backend/onyx/key_value_store/store.py:19-30。

标准化指标日志格式：

{
  "metric": "docprocessing_queue_length",
  "value": 42,
  "tags": {"tenant_id": "default"}
}

来源：backend/onyx/background/celery/tasks/monitoring/tasks.py:95-100, backend/onyx/key_value_store/store.py:15-53, backend/onyx/utils/telemetry.py:11-13