agentic_huge_data_base / wiki
页面 Cognee · 9.2 OpenTelemetry 跟踪·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 9.2

9.2 · OpenTelemetry 跟踪（OpenTelemetry Tracing）

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

项目Cognee 章节9.2 状态全文译文 模块系统架构、测试、发布与运维、配置治理、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节OpenTelemetry Tracing 上一章9.1 下一章9.3
源码线索
  • 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
模块标签
  • 系统架构
  • 测试、发布与运维
  • 配置治理
  • 接口与服务契约
  • 界面与交互

章节正文

OpenTelemetry 跟踪

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/9.2-opentelemetry-tracing

OpenTelemetry 追踪

相关源文件

本章引用的主要源码文件：

  • 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

OpenTelemetry 追踪为 Cognee 操作提供了性能监控、调试能力和可观测性。该系统使用 OpenTelemetry 标准捕获管线任务、数据库查询、大语言模型（LLM）调用和搜索操作的执行追踪。追踪数据会在内存中缓冲以便程序化访问，并可以选择通过 OTLP 导出到外部可观测性平台。

关于通用可观测性和使用分析，请参见遥测系统。关于通过来源字段追踪数据血缘，请参见数据来源与血缘。

追踪架构总览

Cognee 的追踪系统基于 OpenTelemetry SDK 构建，同时提供内存内追踪收集和可选的外部导出功能。

追踪系统组件
Cognee · 追踪系统组件 · 图 1
Cognee · 追踪系统组件 · 图 1

来源： cognee/modules/observability/tracing.py:1-218, cognee/modules/observability/trace_context.py:1-90, cognee/modules/observability/__init__.py:45-81

启用和禁用追踪

程序化控制

可以通过公共 API 以编程方式启用和禁用追踪。enable_tracing 会使用内存中的 CogneeSpanExporter 设置 TracerProvider cognee/modules/observability/trace_context.py:16-24。

import cognee

# 启用追踪（可选控制台输出）
cognee.enable_tracing(console_output=True)

# 禁用追踪并关闭 TracerProvider
cognee.disable_tracing()

来源： cognee/modules/observability/trace_context.py:16-32, cognee/modules/observability/tracing.py:13-27

环境变量配置

可以通过环境变量自动启用追踪。is_tracing_enabled() 函数会检查这些变量，并在请求时惰性初始化追踪 cognee/modules/observability/trace_context.py:34-62。

环境变量值描述
COGNEE_TRACING_ENABLEDtrue、1、yes启动时启用追踪
OTEL_EXPORTER_OTLP_ENDPOINTURL用于外部导出的 OTLP 端点

来源： cognee/modules/observability/trace_context.py:34-62, cognee/modules/observability/tracing.py:7-27

CogneeSpanExporter：内存 Span 缓冲区

CogneeSpanExporter 类实现了 OpenTelemetry 的 SpanExporter 接口，并维护一个有限的内存缓冲区来存储已完成的 Span cognee/modules/observability/tracing.py:100-105。

缓冲区管理
  • Span 按 trace_id 分组到不同的追踪中 cognee/modules/observability/tracing.py:115-133。
  • 最多保留 50 个不同的追踪（_MAX_TRACES = 50）cognee/modules/observability/tracing.py:92。
  • 当超过限制时，最旧的追踪会被淘汰 cognee/modules/observability/tracing.py:138-140。
  • 使用 threading.Lock() 确保线程安全访问 cognee/modules/observability/tracing.py:108。
Span 字典结构

导出到缓冲区的每个 Span 会被转换为包含以下字段的字典 cognee/modules/observability/tracing.py:116-132：

  • name：操作名称。
  • trace_id / span_id / parent_span_id：十六进制标识符。
  • duration_ms：计算方式为 (end_time - start_time) / 1,000,000。
  • status：OTEL 状态码名称（例如 "OK"、"ERROR"）。
  • attributes：元数据的键值对。

来源： cognee/modules/observability/tracing.py:100-168

语义属性

Cognee 定义了标准语义属性，以确保追踪之间的一致性。

V1 和 V2 属性
常量值用途
COGNEE_DB_SYSTEM"cognee.db.system"数据库类型（例如 "kuzu"、"neo4j"）
COGNEE_LLM_MODEL"cognee.llm.model"大语言模型（LLM）模型标识符
COGNEE_SEARCH_TYPE"cognee.search.type"使用的检索策略
COGNEE_RESULT_COUNT"cognee.result.count"检索到的项目数量 cognee/modules/observability/tracing.py:44
COGNEE_RESULT_SUMMARY"cognee.result.summary"人类可读的结果摘要 cognee/modules/observability/tracing.py:43
COGNEE_SESSION_ID"cognee.session.id"唯一会话标识符
COGNEE_GRAPH_EDGES_SYNCED"cognee.graph.edges_synced"同步到会话的边数量

来源： cognee/modules/observability/tracing.py:32-58

在检索和 Memify 中的集成

追踪深度集成到搜索和记忆系统中，以提供对检索性能和数据流的可见性。

检索追踪

get_retriever_output 函数使用多个 Span 来追踪搜索过程的不同阶段 cognee/modules/search/methods/get_retriever_output.py:19-89：

  • cognee.retrieval.get_objects：追踪从数据库原始检索数据的过程 cognee/modules/search/methods/get_retriever_output.py:35-45。
  • cognee.retrieval.get_context：追踪从检索对象中提取上下文的过程 cognee/modules/search/methods/get_retriever_output.py:51-60。
  • cognee.retrieval.get_completion：追踪大语言模型（LLM）生成阶段 cognee/modules/search/methods/get_retriever_output.py:66-79。

来源： cognee/modules/search/methods/get_retriever_output.py:33-76

检索和分析追踪

追踪检索 API
  • get_last_trace()：返回缓冲区中最近完成的追踪 cognee/modules/observability/trace_context.py:65-73。
  • get_all_traces()：返回所有缓冲的 CogneeTrace 对象列表 cognee/modules/observability/trace_context.py:76-82。
  • clear_traces()：重置内存缓冲区 cognee/modules/observability/trace_context.py:85-89。
CogneeTrace 类

CogneeTrace 类提供对追踪 Span 的只读视图 cognee/modules/observability/tracing.py:172-175。

  • spans()：返回按 start_time_ns 排序的 Span 字典扁平列表 cognee/modules/observability/tracing.py:178-180。
  • summary()：返回聚合字典，包含总持续时间、Span 数量和错误列表 cognee/modules/observability/tracing.py:182-203。

来源： cognee/modules/observability/trace_context.py:65-90, cognee/modules/observability/tracing.py:172-218

密钥脱敏

为防止在追踪中泄露敏感信息，Cognee 使用了 redact_secrets() 函数。该函数使用正则表达式模式识别并掩码类似 API 密钥（例如 OpenAI sk-...）、Bearer 令牌和密码的字符串 cognee/modules/observability/tracing.py:63-78。

来源： cognee/modules/observability/tracing.py:61-78

系统流程：追踪收集

此图连接了追踪生命周期中涉及的代码实体，特别聚焦于搜索流程。

Cognee · 系统流程：追踪收集 · 图 2
Cognee · 系统流程：追踪收集 · 图 2

来源： cognee/modules/observability/trace_context.py:16-73, cognee/modules/observability/tracing.py:100-157, cognee/modules/search/methods/get_retriever_output.py:33-76