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

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

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节9 状态全文译文 模块测试、发布与运维、系统架构、接口与服务契约、界面与交互
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Observability and Monitoring 上一章8.4 下一章9.1
源码线索
  • cognee/__init__.py
  • cognee/api/client.py
  • cognee/api/v1/visualize/__init__.py
  • cognee/api/v1/visualize/visualize.py
  • cognee/modules/observability/__init__.py
  • cognee/modules/observability/trace_context.py
  • cognee/modules/observability/tracing.py
  • cognee/modules/search/methods/get_retriever_output.py
  • cognee/shared/utils.py
  • cognee/tests/test_telemetry.py
模块标签
  • 测试、发布与运维
  • 系统架构
  • 接口与服务契约
  • 界面与交互
  • 模型调用与提供方适配

章节正文

可观测性与监控

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/9-observability-and-monitoring

可观测性与监控

相关源文件

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

  • cognee/__init__.py
  • cognee/api/client.py
  • cognee/api/v1/visualize/__init__.py
  • cognee/api/v1/visualize/visualize.py
  • cognee/modules/observability/__init__.py
  • cognee/modules/observability/trace_context.py
  • cognee/modules/observability/tracing.py
  • cognee/modules/search/methods/get_retriever_output.py
  • cognee/shared/utils.py
  • cognee/tests/test_telemetry.py
  • cognee/tests/unit/processing/utils/utils_test.py

本文档介绍了 Cognee 的可观测性基础设施，该设施提供了对系统行为、性能和数据血缘的可见性。Cognee 实现了三个互补的可观测性系统：遥测（使用分析）、OpenTelemetry 追踪（分布式性能监控）和数据溯源（血缘追踪）。这些系统支持调试、性能优化以及理解数据在处理管线中的流转。

有关生成可观测性事件的管线执行系统的信息，请参阅核心数据管线。有关利用溯源数据的可视化功能，请参阅图谱可视化。

系统总览

Cognee 的可观测性架构由三个独立但互补的系统组成：

Cognee · 系统总览 · 图 1
Cognee · 系统总览 · 图 1

来源： cognee/shared/utils.py:176-200、cognee/modules/observability/tracing.py:100-142、cognee/api/client.py:57-70、cognee/modules/search/methods/get_retriever_output.py:35-44

遥测系统

遥测系统用于追踪使用分析，以获取产品洞察，同时尊重用户隐私。所有遥测数据默认是匿名的，并可通过环境变量禁用。

身份层

Cognee 使用三个身份层来关联遥测数据，同时保护隐私：

ID 类型存储位置持久性用途
anonymous_id<项目根目录>/.anon_id项目级别与历史数据的向后兼容性 cognee/shared/utils.py:49-73。
persistent_id~/.cognee/.persistent_id机器级别在重装和虚拟环境之间保持稳定身份 cognee/shared/utils.py:76-101。
user_id关系型数据库用户级别来自数据库的临时 Cognee 用户 UUID cognee/shared/utils.py:176-186。
api_key_tracking_id不适用（派生）密钥级别通过 PBKDF2-HMAC-SHA256 从 LLM API 密钥派生的假名 ID cognee/shared/utils.py:139-168。
数据消毒与指纹识别

在传输之前，敏感数据会经过以下处理：

  • 嵌套属性：url 和 path 等字段会使用 uuid5 进行递归哈希处理 cognee/shared/utils.py:107-124。
  • API 指纹识别：使用可配置的盐值从完整的 LLM_API_KEY 派生出一个稳定的假名 ID，以便在不暴露密钥的情况下对活动进行分组 cognee/shared/utils.py:139-168。
  • 禁用遥测：可以通过设置 TELEMETRY_DISABLED 环境变量来禁用遥测，或者在 dev 或 test 环境中自动禁用 cognee/shared/utils.py:176-180。

来源： cognee/shared/utils.py:49-105、cognee/shared/utils.py:139-173、cognee/shared/utils.py:176-200

OpenTelemetry 追踪

Cognee 实现了原生 OpenTelemetry 的分布式追踪。它使用自定义的内存 Span 缓冲区来实现程序化追踪访问，同时支持标准 OTLP 导出以用于外部监控工具。

追踪架构

追踪系统以 CogneeSpanExporter 为核心，该导出器按 trace_id 对已完成的 Span 进行分组，并维护一个包含最近 50 条追踪记录的有界缓冲区 cognee/modules/observability/tracing.py:92-111。

Cognee · 追踪架构 · 图 2
Cognee · 追踪架构 · 图 2

来源： cognee/modules/observability/tracing.py:100-142、cognee/modules/observability/__init__.py:64-81、cognee/modules/observability/trace_context.py:16-62

语义属性

Cognee 使用特定的常量来构建结构化的 Span 数据，以确保引擎内部的一致性：

类别属性常量
数据库COGNEE_DB_SYSTEM、COGNEE_DB_QUERY、COGNEE_DB_ROW_COUNT
大语言模型（LLM）COGNEE_LLM_MODEL、COGNEE_LLM_PROVIDER
搜索COGNEE_SEARCH_TYPE、COGNEE_SEARCH_QUERY、COGNEE_RESULT_COUNT
管线COGNEE_PIPELINE_NAME、COGNEE_PIPELINE_TASK_NAME
V2 APICOGNEE_SESSION_ID、COGNEE_DATASET_NAME、COGNEE_OPERATION_MODE

来源： cognee/modules/observability/tracing.py:32-58、cognee/modules/search/methods/get_retriever_output.py:35-44

数据溯源与血缘

溯源系统用于追踪由 Cognee 处理的数据的起源和血缘。这主要通过 DataPoint 模型以及在管线执行期间的元数据标记来处理。

溯源追踪

知识图谱中的每个 DataPoint 都包含标识其来源的元数据。这包括创建它的管线和任务，以及用于随时间追踪变更的版本信息。

  • source_pipeline：管线的名称 cognee/modules/observability/tracing.py:45。
  • source_task：特定任务的名称 cognee/modules/observability/tracing.py:39。
  • source_user：发起数据创建的用户上下文的标识符。
  • version：追踪数据点的迭代版本，以支持更新和历史记录。

对于 API 级别的错误监控，如果安装了 monitoring 附加组件并在环境中配置了 SENTRY_REPORTING_URL，Cognee 会与 Sentry 集成 cognee/api/client.py:57-70。

子页面

有关更详细的技术文档，请参阅以下子页面：

  • 遥测系统 — 关于 ID 生成、数据消毒以及通过 _send_telemetry_request 进行的异步传输管线的详细文档。
  • OpenTelemetry 追踪 — 深入探讨 CogneeSpanExporter、CogneeTrace 摘要生成以及外部 OTLP 集成。
  • 数据溯源与血缘 — 关于管线中溯源标记、源字段传播和版本追踪的技术细节。

总结

Cognee 的可观测性基础设施通过三个互补的系统提供了全面的可见性：

  1. 遥测：通过 send_telemetry() 进行匿名使用分析，使用保护隐私的机器级持久化 ID 和 LLM 密钥指纹识别 cognee/shared/utils.py:176-200。
  2. OpenTelemetry 追踪：使用自定义的 CogneeSpanExporter 进行分布式性能监控，并通过 get_last_trace() 进行程序化追踪访问 cognee/modules/observability/tracing.py:100-142。
  3. 数据溯源：用于审计和可视化数据在系统中移动的血缘追踪，嵌入在 DataPoint 元数据中。

来源： cognee/shared/utils.py:176-200、cognee/modules/observability/tracing.py:100-142、cognee/api/client.py:57-70