agentic_huge_data_base / wiki
页面 Graphiti · 10.7 OpenTelemetry 跟踪与可观测性·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 10.7

10.7 · OpenTelemetry 跟踪与可观测性（OpenTelemetry Tracing and Observability）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节10.7 状态全文译文 模块测试、发布与运维、检索、召回与索引、界面与交互、系统架构
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节OpenTelemetry Tracing and Observability 上一章10.6 下一章11
源码线索
  • .github/secret_scanning.yml
  • CLAUDE.md
  • OTEL_TRACING.md
  • examples/opentelemetry/.env.example
  • examples/opentelemetry/README.md
  • examples/opentelemetry/otel_stdout_example.py
  • examples/opentelemetry/pyproject.toml
  • examples/opentelemetry/uv.lock
  • graphiti_core/llm_client/cache.py
  • graphiti_core/telemetry/__init__.py
模块标签
  • 测试、发布与运维
  • 检索、召回与索引
  • 界面与交互
  • 系统架构
  • 安装与启动

章节正文

OpenTelemetry 跟踪与可观测性

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/10.7-opentelemetry-tracing-and-observability

OpenTelemetry 追踪与可观测性

相关源文件

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

  • .github/secret_scanning.yml
  • CLAUDE.md
  • OTEL_TRACING.md
  • examples/opentelemetry/.env.example
  • examples/opentelemetry/README.md
  • examples/opentelemetry/otel_stdout_example.py
  • examples/opentelemetry/pyproject.toml
  • examples/opentelemetry/uv.lock
  • graphiti_core/llm_client/cache.py
  • graphiti_core/telemetry/__init__.py
  • graphiti_core/telemetry/telemetry.py
  • graphiti_core/tracer.py
  • tests/llm_client/test_cache.py

Graphiti 提供了一套全面的可观测性栈，用于监控知识图谱操作的性能和行为。这包括一个基于 OpenTelemetry 的可插拔追踪系统（用于分布式追踪）和一个匿名 遥测系统（用于使用分析）。

追踪架构

追踪系统围绕一个抽象接口构建，该接口使 Graphiti 与特定追踪库保持解耦，同时为事件处理和检索管线提供深度可见性。

追踪器接口

Graphiti 定义了一个内部追踪抽象层，以确保核心库可以在有或没有 opentelemetry-sdk 等外部依赖的情况下正常运行。

  • Tracer：一个抽象基类，定义了 start_span 方法 graphiti_core/tracer.py:52-58。
  • TracerSpan：一个用于单个 Span 的抽象基类，提供了添加属性、设置状态和记录异常的方法 graphiti_core/tracer.py:33-50。
实现方式
  1. OpenTelemetryTracer：标准 OpenTelemetry Tracer 的包装器。它会自动在所有 Span 名称前添加一个可配置的前缀（默认为 graphiti）graphiti_core/tracer.py:126-157。
  2. NoOpTracer：一个零开销的实现，在追踪被禁用或未安装 OpenTelemetry 库时使用 graphiti_core/tracer.py:74-81。
  3. OpenTelemetrySpan：TracerSpan 的具体实现，包装了 opentelemetry.trace.Span。它包含过滤 None 值并确保属性为原始类型或字符串的逻辑 graphiti_core/tracer.py:83-106。
追踪器初始化流程

create_tracer 工厂函数根据环境和提供的参数决定提供哪种实现 graphiti_core/tracer.py:159-193。

追踪初始化逻辑

Graphiti · 追踪器初始化流程 · 图 1
Graphiti · 追踪器初始化流程 · 图 1

来源：graphiti_core/tracer.py:159-193，graphiti_core/tracer.py:126-146，graphiti_core/tracer.py:74-76

配置分布式追踪

追踪是可选的。要启用它，用户必须向 Graphiti 构造函数提供一个 OpenTelemetry Tracer 实例。

安装

opentelemetry-sdk 是一个可选依赖 OTEL_TRACING.md:5-9。

uv add opentelemetry-sdk
集成示例

在初始化 Graphiti 客户端时，传入 tracer 会在所有内部方法（如 add_episode 和 search）中启用仪表化 OTEL_TRACING.md:13-33。

from opentelemetry import trace
from graphiti_core import Graphiti

# 标准 OTEL 设置
tracer = trace.get_tracer(__name__)

graphiti = Graphiti(
    graph_driver=kuzu_driver,
    tracer=tracer,
    trace_span_prefix="myapp.graphiti"
)

来源：OTEL_TRACING.md:13-33，examples/opentelemetry/otel_stdout_example.py:50-57

追踪数据流

当执行操作时，Graphiti 会将内部逻辑包装在 Span 中。OpenTelemetrySpan 实现负责处理数据类型转换，以确保与 OpenTelemetry 后端的兼容性，将非原始类型转换为字符串 graphiti_core/tracer.py:91-103。

操作追踪序列

Graphiti · 追踪数据流 · 图 2
Graphiti · 追踪数据流 · 图 2

来源：graphiti_core/tracer.py:148-157，graphiti_core/tracer.py:89-106，graphiti_core/tracer.py:108-119

仪表化组件

追踪已集成到关键路径中，包括：

  • 搜索管线：为查询嵌入向量（search.embed_query_vector）、作用域执行（search.execute_scopes）和边搜索重排序（search.edge_search.rerank）发出 Span tests/utils/search/test_search_tracing.py:77-83。
  • 属性：Span 包含元数据，如 query.length、query_vector.dimension 和 scope.edges 标志 tests/utils/search/test_search_tracing.py:87-92。

匿名遥测系统

Graphiti 包含一个遥测模块，用于通过 PostHog 收集匿名使用统计信息。该系统与 OpenTelemetry 追踪分离，用于产品改进 graphiti_core/telemetry/telemetry.py:1-5。

关键组件
组件描述来源
is_telemetry_enabled检查 GRAPHITI_TELEMETRY_ENABLED 环境变量。在 pytest 期间返回 False。graphiti_core/telemetry/telemetry.py:29-37
get_anonymous_id在 ~/.cache/graphiti/telemetry_anon_id 中持久化一个 UUID。graphiti_core/telemetry/telemetry.py:40-63
capture_event向 PostHog 发送包含架构、版本和自定义属性的事件。graphiti_core/telemetry/telemetry.py:92-118
initialize_posthog使用公共 API 密钥初始化 PostHog 客户端。graphiti_core/telemetry/telemetry.py:76-90
配置
  • 启用/禁用：将 GRAPHITI_TELEMETRY_ENABLED 环境变量设置为 true 或 false。默认值为 true graphiti_core/telemetry/telemetry.py:22-37。
  • 隐私：该系统使用一个公共 PostHog 密钥（phc_UG6EcfDbuXz92neb3rMlQFDY0csxgMqRcIPWESqnSmo），该密钥设计用于客户端暴露，不会收集个人身份信息（PII）graphiti_core/telemetry/telemetry.py:15-18。
  • 存储：匿名 ID 本地存储在用户主目录下的 .cache/graphiti/telemetry_anon_id 中 graphiti_core/telemetry/telemetry.py:24-26。

来源：graphiti_core/telemetry/telemetry.py:15-37，graphiti_core/telemetry/telemetry.py:40-63，graphiti_core/telemetry/telemetry.py:92-118，.github/secret_scanning.yml:5-8