Crate cognee_telemetry 

Cognee product-analytics client (send_telemetry).

Mirrors Python’s cognee.shared.utils.send_telemetry. Fires a single fire-and-forget HTTP POST to https://test.prometh.ai for every public API call so the cognee maintainers have an aggregate view of how the SDK is exercised.

Enabled by default (locked decision 1 — Python parity). The runtime check happens before any identity derivation or HTTP code path, so disabling at runtime costs zero.

See docs/observability/send_telemetry.md for the full operator-facing reference (payload schema, salt rotation, privacy notes, troubleshooting).

Quick start

use cognee_telemetry::send_telemetry;
use serde_json::json;

send_telemetry(
    "cognee.forget",
    "user-id-string",
    Some(json!({ "endpoint": "POST /api/v1/forget" })),
);

Opt-out

At runtime: TELEMETRY_DISABLED=1 (any non-empty value) or ENV=test / ENV=dev.

At compile time: build cognee-lib (or any consumer) with --no-default-features. send_telemetry and try_send_telemetry still exist in the public surface but are compiled to noop bodies — no reqwest, no tokio runtime fallback, no PBKDF2 cost.

Environment variables

Var	Default	Effect
TELEMETRY_DISABLED	unset	Any non-empty value disables. Read on every call.
ENV	unset	If test or dev, disables. Read on every call.
LLM_API_KEY	unset	Source of api_key_tracking_id (locked decision 11 — read at every event-emission, never cached).
TRACKING_ID	unset	Override anonymous_id.
TELEMETRY_API_KEY_TRACKING_SALT	cognee.telemetry.api-key-tracking.v1	PBKDF2 salt override (locked decision 12).
TELEMETRY_REQUEST_TIMEOUT	5	HTTP timeout in seconds. Clamped to [1, 60]. Read once per process.

Logging

All diagnostics use the cognee.telemetry tracing target. Enable with RUST_LOG=cognee.telemetry=debug.

Modules

env

Environment-driven configuration for send_telemetry.

ids

Identity-layer helpers for send_telemetry.

payload

Strongly-typed serde model of the send_telemetry proxy payload.

sanitize

Recursive URL-sanitization for caller-supplied properties.

Enums

TelemetryError

Errors returned by try_send_telemetry.

UserIdRef

Reference type for the user_id field. Accepts a Uuid, a &str, or Option<Uuid> via the From impls below; callers rarely construct this directly.

Functions

cognee_version

Returns the cognee crate version string for use in analytics payloads. Matches Python’s cognee.__version__.

send_telemetry

Fire-and-forget product-analytics event.

tenant_id_for_telemetry

Format a tenant_id for the telemetry wire payload, mirroring Python str(user.tenant_id) if user.tenant_id else "Single User Tenant".

try_send_telemetry

Same as send_telemetry but returns Result<(), TelemetryError> for callers that want to know whether dispatch was attempted.

Type Aliases

PropertyValue

Placeholder property type used when the telemetry feature is disabled. Replaced by serde_json::Value once the feature is on.