fix(telemetry): reliable delivery + per-install identity in TS packages#293
Merged
Conversation
Mirror the Python analytics fixes into the four TS packages so npm consumers
report install/active signals correctly.
- Delivery: flush the *_init event immediately after capture, plus a
process.once('beforeExit') backstop (removed on shutdown). Add flush() to
the Analytics interface and NOOP. Deliberately no SIGINT/SIGTERM handlers —
a library must not seize the host's signal handling; beforeExit matches
Python atexit's normal-exit parity.
- Identity: distinctId is now a per-install UUID persisted at
~/.betterdb/instance_id (honors XDG_STATE_HOME, override BETTERDB_INSTANCE_ID).
The old Valkey-scoped id is demoted to a deployment_id property for roll-up,
so a fleet sharing one Valkey no longer collapses to a single user.
- MemoryStore: session counters rolled up into a memory_session event (on
close() and a beforeExit backstop) plus a memory_consolidated event.
Client-style split preserved: memory/retrieval use client.call('GET'/'SET'),
caches use client.get()/set(). Tests updated to assert install-id distinctId,
deployment_id property, and flush-on-init.
Remove the apiKey/host config options from AnalyticsOptions and the per-package option types, and drop the unused BETTERDB_POSTHOG_API_KEY/HOST runtime env override from semantic-cache. Key resolution is now uniform across all four packages: the build-time baked key only. Tests construct PostHogAnalytics directly (now exported) instead of injecting a key via the factory.
- getInstallId: memoize a per-process ephemeral id when persistence fails, so repeated/parallel init calls report one stable distinctId instead of a fresh UUID each time (all 4 analytics.ts). - MemoryStore.captureSession: only arm the one-shot flag once counts are non-zero, so an early beforeExit with zero activity no longer blocks a later close() from emitting memory_session.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit f032954. Configure here.
| // Key resolution: opts.apiKey → BETTERDB_POSTHOG_API_KEY env var → baked wheel value | ||
| const bakedKey = BAKED_POSTHOG_API_KEY.startsWith('__') ? undefined : BAKED_POSTHOG_API_KEY; | ||
| const apiKey = opts?.apiKey ?? process.env.BETTERDB_POSTHOG_API_KEY ?? bakedKey; | ||
| const apiKey = BAKED_POSTHOG_API_KEY.startsWith('__') ? undefined : BAKED_POSTHOG_API_KEY; |
There was a problem hiding this comment.
Semantic cache env key gone
Medium Severity
createAnalytics in semantic-cache no longer reads BETTERDB_POSTHOG_API_KEY or BETTERDB_POSTHOG_HOST, or option overrides. Deployments that enabled telemetry via those env vars without a build-injected baked key now always get NOOP_ANALYTICS.
Reviewed by Cursor Bugbot for commit f032954. Configure here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Mirror the Python analytics fixes into the four TS packages so npm consumers report install/active signals correctly.
Changes
Client-style split preserved: memory/retrieval use client.call('GET'/'SET'), caches use client.get()/set(). Tests updated to assert install-id distinctId, deployment_id property, and flush-on-init.
Checklist
roborev review --branchor/roborev-review-branchin Claude Code (internal)Note
Medium Risk
Changes product telemetry identity and removes runtime PostHog credential overrides (potential breaking change for custom keys); local filesystem writes for install IDs are new but analytics paths remain fail-soft.
Overview
Aligns agent-cache, agent-memory, retrieval, and semantic-cache npm analytics with the Python telemetry fixes so short-lived processes actually report usage and installs are counted correctly.
Identity: PostHog
distinctIdis now a per-machine install id (~/.betterdb/instance_id,XDG_STATE_HOME, orBETTERDB_INSTANCE_ID). The former Valkey-scoped UUID becomes adeployment_idevent property for rolling up clients that share one store.Delivery: Adds
flush()to the analytics interface (and noop). Init events are flushed immediately after capture, with abeforeExitbackstop (removed onshutdown()); no signal handlers.Config API:
analytics.apiKey/analytics.hostare removed from package options andcreateAnalytics; only build-injected PostHog credentials apply (semantic-cache no longer falls back toBETTERDB_POSTHOG_*env at runtime).Memory-only:
MemoryStoreaggregates operation counts into a one-shotmemory_sessionevent onclose()orbeforeExit, and emitsmemory_consolidatedon consolidate.Reviewed by Cursor Bugbot for commit f032954. Bugbot is set up for automated code reviews on this repo. Configure here.