可观测性与监控（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/9-observability-and-monitoring
翻译时间：2026-05-27T08:45:16.945Z
翻译模型：deepseek-chat
原文字符数：10237
项目：Cognee (cognee)
---
可观测性与监控
相关源文件
以下文件为本维基页面的生成提供了上下文：
cognee/__init__.pycognee/api/client.pycognee/api/v1/visualize/__init__.pycognee/api/v1/visualize/visualize.pycognee/modules/observability/__init__.pycognee/modules/observability/trace_context.pycognee/modules/observability/tracing.pycognee/modules/search/methods/get_retriever_output.pycognee/shared/utils.pycognee/tests/test_telemetry.pycognee/tests/unit/processing/utils/utils_test.py
本文档介绍了 Cognee 的可观测性基础设施，该设施提供了对系统行为、性能和数据血缘的可见性。Cognee 实现了三个互补的可观测性系统：遥测（使用分析）、OpenTelemetry 追踪（分布式性能监控）和数据溯源（血缘追踪）。这些系统支持调试、性能优化以及理解数据在处理管线中的流转。
有关生成可观测性事件的管线执行系统的信息，请参阅核心数据管线。有关利用溯源数据的可视化功能，请参阅图谱可视化。
---
系统总览
Cognee 的可观测性架构由三个独立但互补的系统组成：
graph TB
subgraph "用户操作"
ADD["cognee.add()"]
COGNIFY["cognee.cognify()"]
SEARCH["cognee.search()"]
REMEMBER["cognee.remember()"]
end
subgraph "遥测系统 [cognee/shared/utils.py]"
SEND_TEL["send_telemetry()"]
ANON_ID["get_anonymous_id()"]
PERSIST_ID["get_persistent_id()"]
SANITIZE["_sanitize_nested_properties()"]
PROXY["分析代理<br/>test.prometh.ai"]
ANON_FILE[".anon_id 文件"]
PERSIST_FILE[".persistent_id 文件"]
end
subgraph "OpenTelemetry 追踪 [cognee/modules/observability]"
ENABLE["enable_tracing()"]
GET_TRACER["get_tracer()"]
EXPORTER["CogneeSpanExporter"]
PROVIDER["TracerProvider"]
OTLP["OTLP 导出器<br/>（可选）"]
end
subgraph "数据溯源"
DATAPOINT["DataPoint 模型"]
PROV_FIELDS["source_pipeline<br/>source_task<br/>source_user<br/>version"]
end
subgraph "外部集成"
DATADOG["Datadog"]
GRAFANA["Grafana Cloud"]
SENTRY["Sentry SDK"]
end
ADD --> SEND_TEL
COGNIFY --> SEND_TEL
SEARCH --> SEND_TEL
REMEMBER --> SEND_TEL
SEND_TEL --> ANON_ID
SEND_TEL --> PERSIST_ID
SEND_TEL --> SANITIZE
SEND_TEL --> PROXY
ANON_ID --> ANON_FILE
PERSIST_ID --> PERSIST_FILE
ADD --> GET_TRACER
COGNIFY --> GET_TRACER
SEARCH --> GET_TRACER
GET_TRACER --> PROVIDER
PROVIDER --> EXPORTER
PROVIDER --> OTLP
OTLP -.=> DATADOG
OTLP -.=> GRAFANA
SEARCH --> NEW_SPAN["new_span()"]
NEW_SPAN --> GET_TRACER
SENTRY -.-> CLIENT["cognee.api.client"]
来源： 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。
graph TB
subgraph "追踪控制 [cognee/modules/observability/trace_context.py]"
ENABLE["enable_tracing()"]
DISABLE["disable_tracing()"]
IS_ENABLED["is_tracing_enabled()"]
end
subgraph "执行上下文 [cognee/modules/observability/__init__.py]"
NEW_SPAN["new_span(name)"]
GET_TRACER["get_tracer_if_enabled()"]
end
subgraph "Span 缓冲 [cognee/modules/observability/tracing.py]"
EXPORTER["CogneeSpanExporter"]
BUFFER["_traces: dict[trace_id, list]"]
ORDER["_trace_order: list[trace_id]"]
end
subgraph "追踪访问"
GET_LAST["get_last_trace()"]
GET_ALL["get_all_traces()"]
CLEAR["clear_traces()"]
COGN_TRACE["CogneeTrace 对象"]
end
ENABLE --> IS_ENABLED
NEW_SPAN --> IS_ENABLED
IS_ENABLED --> GET_TRACER
GET_TRACER --> EXPORTER
EXPORTER --> BUFFER
EXPORTER --> ORDER
GET_LAST --> EXPORTER
GET_ALL --> EXPORTER
CLEAR --> EXPORTER
EXPORTER --> COGN_TRACE
来源： 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 API | COGNEE_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 的可观测性基础设施通过三个互补的系统提供了全面的可见性：
- 遥测：通过
send_telemetry()进行匿名使用分析，使用保护隐私的机器级持久化 ID 和 LLM 密钥指纹识别cognee/shared/utils.py:176-200。 - OpenTelemetry 追踪：使用自定义的
CogneeSpanExporter进行分布式性能监控，并通过get_last_trace()进行程序化追踪访问cognee/modules/observability/tracing.py:100-142。 - 数据溯源：用于审计和可视化数据在系统中移动的血缘追踪，嵌入在
DataPoint元数据中。
来源： cognee/shared/utils.py:176-200、cognee/modules/observability/tracing.py:100-142、cognee/api/client.py:57-70