Skip to content

Index

diapason.analytics

External anonymous usage analytics.

Sends anonymized events to PostHog so the Diapason team can measure setup success, retention, feature usage, and churn — without ever collecting chat content, prompts, file paths, emails, IPs, or hardware identifiers.

Distinct from :mod:diapason.telemetry, which stores local FLOPs and energy metrics in a SQLite DB and never leaves the machine.

Disable: set [analytics] enabled = false in ~/.diapason/config.toml.

AnalyticsClient

Send anonymized usage events to PostHog.

Construct once at server / CLI startup, share for the process lifetime, call :meth:shutdown on exit to flush pending events.

capture(event_name, properties=None)

Send one event. Unknown events are silently dropped.

Runs through redaction → event-spec validation → SDK capture. Failures at any stage are swallowed; analytics is best-effort.

flush()

Force-flush queued events. Safe to call repeatedly.

shutdown()

Flush and close the SDK. Call once on process exit.

EventBridge

Subscribes to the internal bus and routes to the analytics client.

start()

Attach subscribers to the bus. Idempotent.

stop()

Detach subscribers and flush buffered sessions.

SessionAggregator

Buffers per-session counts; emits chat_session_ended on close.

end_session(session_id)

Emit chat_session_ended for one session and drop the buffer.

shutdown()

Flush every buffered session and stop the flusher thread.

get_or_create_anon_id(path)

Return the persisted anon ID, generating one on first call.

Idempotent across processes — if the file already exists with a non-empty value, return it; otherwise generate a fresh UUID v4 and write atomically (rename-after-write so a crashed write leaves no half-file).

hash_id(s)

Return a 16-char sha256 prefix of s.

Used for model / tool / connector names that aren't on the public allowlist — we still want to see "uses-a-custom-model-X" cohorting without ever learning which model.

is_analytics_enabled(cfg)

Return True if analytics is enabled in config.

Local-only mode overrides [analytics] enabled, which ships as True with a hard-coded PostHog host and project key. Telemetry is anonymous and carries no conversation content, but "nothing leaves this machine" that still phones home on every launch is not a promise — it is a caveat.

This single predicate is the whole gate: AnalyticsClient.__init__ consults it before calling _init_sdk, so under local-only no PostHog client is ever constructed and the project key is never read.

redact(properties)

Return a copy of properties with PII-bearing string values dropped.

Non-string values pass through unchanged. Strings exceeding MAX_STR_LEN are dropped. Strings matching any PII pattern are dropped. The event-spec validator (in :mod:events) runs after this and provides a second layer of structural enforcement.

reset_anon_id(path)

Delete the persisted ID and generate a fresh one (privacy reset).