Analytics & Telemetry

SochDB can collect optional, anonymous usage telemetry to help improve the database. This page explains what data is collected, how telemetry is enabled or disabled per component, and the privacy practices behind it.

Versions on this page

Core engine 2.0.3 · Python SDK 0.5.9 · Node.js SDK 0.5.3 · Go SDK 0.4.5. Telemetry behavior differs by component — read the per-component status section below.

What Is Collected

When telemetry is active, SochDB sends a single anonymous usage event — database_opened — to help us understand:

• Whether the database is opened in embedded or server mode
• Platform distribution (OS, architecture)
• The SDK and SDK version in use

Only database_opened is sent

Earlier releases mentioned vector_search, batch_insert, and error events. The per-operation tracking has been removed. The only usage event currently emitted is database_opened. The clients also retain a static capture_error helper (error category + code location, no payload), but it is not wired into a default hot path.

Example Event Data

{
  "event": "database_opened",
  "properties": {
    "sdk": "nodejs",
    "sdk_version": "0.5.3",
    "os": "darwin",
    "arch": "arm64",
    "mode": "embedded",
    "has_custom_path": true
  },
  "distinct_id": "a1b2c3d4e5f6g7h8"
}

The distinct_id is a stable, one-way SHA-256 hash of non-identifying machine information (hostname, OS, architecture, uid), truncated to 16 hex characters. The same machine always produces the same id, but the id cannot be reversed to identify the machine.

What Is NOT Collected

SochDB never collects:

• Database contents, keys, values, or query data
• API keys or credentials
• Personal information (names, emails, IP addresses)
• File paths or directory structures (only a boolean has_custom_path)
• Hostnames (only a one-way hash is used for distinct_id)

Per-Component Status

Telemetry is wired up differently in each component. The table below reflects the current state on disk.

Component	Version	Default	How to control it
Core engine (Rust)	2.0.3	Off (opt-in)	Set SOCHDB_ENABLE_ANALYTICS=true to opt in; built only into release builds that bake in a PostHog key
Python SDK	0.5.9	Effectively off	SOCHDB_DISABLE_ANALYTICS=true; see caveat below
Node.js SDK	0.5.3	On if posthog-node installed	SOCHDB_DISABLE_ANALYTICS=true
Go SDK	0.4.5	Off	posthog-go is a go.mod dependency, but no active telemetry module is wired into the client

The core engine is opt-in and off by default

In the Rust core (the sochdb crate / engine, AGPL-3.0-or-later), telemetry is disabled by default. It is only sent if you explicitly set SOCHDB_ENABLE_ANALYTICS=true and the build has a PostHog ingestion key compiled in (via SOCHDB_POSTHOG_API_KEY at build time, which official release builds set). A plain cargo build carries no ingestion key, so it never phones home. SOCHDB_DISABLE_ANALYTICS=true always takes precedence and keeps tracking off even if it was opted in elsewhere.

Python telemetry is effectively a no-op

The Python SDK (0.5.9, Apache-2.0) attempts from .analytics import track_database_open when a database is opened, but the analytics module is not shipped inside the sochdb package — the import is wrapped in a try/except that silently swallows the failure. As a result, the pure-Python SDK does not emit telemetry today, regardless of the [analytics] extra. The extra still exists in pyproject.toml (pip install sochdb[analytics], which pulls in posthog>=3.0.0), but there is no in-package module that uses it.

Disabling Telemetry

To force telemetry off everywhere, set the environment variable before starting your process:

Bash / Zsh

export SOCHDB_DISABLE_ANALYTICS=true

PowerShell

$env:SOCHDB_DISABLE_ANALYTICS = "true"

Windows CMD

set SOCHDB_DISABLE_ANALYTICS=true

The value is matched case-insensitively; any of true, 1, yes, or on disables telemetry. Set the variable from code before opening a database if you prefer:

Python

import os
os.environ["SOCHDB_DISABLE_ANALYTICS"] = "true"

Node.js

process.env.SOCHDB_DISABLE_ANALYTICS = "true";

Core engine: opting in

For the Rust core, the inverse flag enables (rather than disables) telemetry:

export SOCHDB_ENABLE_ANALYTICS=true

Even then, no data is sent unless the build has a PostHog key compiled in.

Checking the Disabled State

Each component exposes its own way to inspect whether telemetry is disabled.

Node.js

The function lives in the SDK's internal analytics module. It is not re-exported from the package entry point, so it cannot be imported from @sochdb/sochdb directly. To check the state without importing internals, read the environment variable yourself:

const disabled = ["true", "1", "yes", "on"].includes(
  (process.env.SOCHDB_DISABLE_ANALYTICS || "").toLowerCase()
);
console.log(`Analytics disabled: ${disabled}`);

Rust

use sochdb_core::analytics::is_analytics_disabled;

println!("Analytics disabled: {}", is_analytics_disabled());

Python

The pure-Python SDK does not ship an is_analytics_disabled helper. Inspect the environment variable directly:

import os

disabled = os.environ.get("SOCHDB_DISABLE_ANALYTICS", "").lower() in (
    "true", "1", "yes", "on",
)
print(f"Analytics disabled: {disabled}")

Telemetry Provider

When telemetry is active, SochDB sends events to PostHog, an open-source product analytics platform.

• Endpoint: https://us.i.posthog.com (overridable in the core via SOCHDB_POSTHOG_HOST)
• Data retention: Aggregated metrics only
• No third-party sharing: Data is used only by SochDB developers

Optional Dependency

The PostHog client is an optional dependency. If it is not installed, all tracking calls become silent no-ops.

Python

pip install sochdb[analytics]

Pulls in posthog>=3.0.0. Note the caveat above: no in-package module currently uses it.

Node.js

posthog-node (^4.18.0) is listed under optionalDependencies, so it is installed by default but the SDK works without it.

Rust

Enable the analytics feature flag on the core build. Release builds also bake in the ingestion key via SOCHDB_POSTHOG_API_KEY at compile time.

Events

Event	Description	Properties
database_opened	A database handle was opened	sdk, sdk_version, os, arch, mode, has_custom_path

Source Code

Telemetry is fully open source. The implementation lives in:

• Rust core: sochdb-core/src/analytics.rs (AGPL-3.0-or-later)
• Node.js SDK: sochdb-nodejs-sdk/src/analytics.ts (Apache-2.0)

The Python (0.5.9) SDK does not currently ship an active telemetry module (see the caveat above). The Go (0.4.5) SDK lists posthog-go as a go.mod dependency but does not wire an active telemetry module into the client.

Questions?

If you have any questions or concerns about telemetry, please open an issue or email sushanth@sochdb.dev.