9.1 · 遥测系统（Telemetry System）

遥测系统

遥测系统

相关源文件

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

• .dockerignore.ci
• .github/workflows/integration_tests.yml
• cognee/__init__.py
• cognee/api/client.py
• cognee/api/v1/visualize/__init__.py
• cognee/api/v1/visualize/visualize.py
• cognee/shared/utils.py
• cognee/tests/integration/shared/test_usage_logger_integration.py
• cognee/tests/test_telemetry.py
• cognee/tests/unit/processing/utils/utils_test.py

遥测系统通过收集关于管线执行、任务完成和错误的匿名操作数据，为 Cognee 提供使用分析。它会将经过消毒的事件数据发送到分析代理，而不会传输敏感用户信息。该系统设计为非阻塞、保护隐私且易于禁用。

有关基于 OpenTelemetry 的追踪和性能监控信息，请参见 9.2 OpenTelemetry 追踪。有关知识图谱中的数据溯源和沿袭追踪，请参见 9.3 数据溯源与沿袭。

目的与范围

遥测系统收集以下内容：

• 管线与任务执行事件：任务开始、完成或出错时的事件。
• 操作元数据：任务名称、管线名称和 Cognee 版本。
• 匿名标识符：持久化机器 ID、匿名项目 ID 和稳定的假名 API 追踪 ID cognee/shared/utils.py:176-192。

该系统不会收集：

• 用户凭证或原始大语言模型（LLM）API 密钥 cognee/shared/utils.py:139-148。
• 敏感文件路径或 URL（在传输前通过 UUID5 哈希进行消毒）cognee/shared/utils.py:107-124。
• 用户数据内容或特定查询结果。
• 个人身份信息。

架构总览

遥测系统采用多层身份方法来关联数据，同时保持匿名性。

身份层示意图

来源： cognee/shared/utils.py:176-205 cognee/shared/utils.py:49-105 cognee/shared/utils.py:139-168

匿名与持久化 ID 生成

Cognee 使用多个标识符来跨会话和环境追踪使用情况。

匿名 ID（项目级别）

存储在项目根目录的 .anon_id 文件中。此 ID 用于与历史分析数据向后兼容，如果项目被重新克隆或安装到不同目录，可能会发生变化 cognee/shared/utils.py:49-73。可以通过 TRACKING_ID 环境变量覆盖 cognee/shared/utils.py:58-60。

持久化 ID（机器级别）

存储在 ~/.cognee/.persistent_id 文件中。此 ID 在 cognee.forget(everything=True)、虚拟环境重建和 Git 重新克隆后仍然保留 cognee/shared/utils.py:76-89。如果可用，它会从 anonymous_id 中播种，以将两者关联起来 cognee/shared/utils.py:94-95。

API 密钥追踪 ID

为了识别唯一环境而不暴露密钥，_get_api_key_tracking_id() 函数使用 PBKDF2-HMAC 和 SHA256 从 LLM_API_KEY 派生出一个稳定的假名 ID cognee/shared/utils.py:139-168。这避免了发送原始密钥片段，同时允许分析按密钥对活动进行分组 cognee/shared/utils.py:142-144。

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

数据消毒

_sanitize_nested_properties() 函数递归遍历遥测载荷以保护用户隐私 cognee/shared/utils.py:107-124。

来源： cognee/shared/utils.py:107-124 cognee/shared/utils.py:139-168

遥测事件与载荷

遥测事件在核心操作期间触发。每个事件包含身份层：anonymous_id、persistent_id、user_id 和 api_key_tracking_id cognee/shared/utils.py:176-192。

事件载荷结构

发送到代理的标准载荷包括：

{
    "anonymous_id": str, # 项目级别 ID
    "event_name": str,   # 例如 "任务已开始"
    "user_properties": {
        "user_id": str,       # 临时数据库 ID
        "persistent_id": str, # 稳定机器 ID
        "api_key_tracking_id": str # 稳定假名密钥 ID
    },
    "properties": {
        "time": "MM/DD/YYYY",
        "cognee_version": str,
        # ... 其他已消毒属性
    }
}

来源： cognee/shared/utils.py:176-205

配置与控制

禁用遥测

遥测可以通过环境变量禁用，或者在非生产环境中自动抑制 cognee/shared/utils.py:208-213。

异步与非阻塞设计

遥测系统使用带有特定超时的 aiohttp，以确保它永远不会阻塞主执行流程 cognee/shared/utils.py:127-137。

TELEMETRY_REQUEST_TIMEOUT 默认为 5 秒，可以通过环境变量覆盖 cognee/shared/utils.py:24。

来源： cognee/shared/utils.py:21-24 cognee/shared/utils.py:127-137

测试

系统通过单元测试和集成测试进行验证。

来源：

• cognee/tests/test_telemetry.py:1-126
• cognee/tests/unit/processing/utils/utils_test.py:1-74
• cognee/tests/integration/shared/test_usage_logger_integration.py:1-210