Skip to content

armgit / crm

Public Imported from GitHub
0

Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.

TypeScript
19.6 KB
Raw Blame

Telemetry

What this install reports about itself, in full. The decisions behind it are in adrs/telemetry.md; this file is the list.

Turn it off with CRM_TELEMETRY_DISABLED="1" or DO_NOT_TRACK=1 in the root .env, then restart. This file is the full account of what is sent; there is no settings page for it, so this is the thing to read.

Where it goes is not configurable and deliberately so: the project key and host are constants in packages/telemetry/src/project.ts. A phc_ key is write-only — it sends events and reads nothing back — so a variable would only have made a public identifier look like a secret. Point a fork somewhere else by editing that file. Nothing is sent while NODE_ENV is test, so a test run cannot emit.

The shape of it

  • Server side only, in everything you run. posthog-node in apps/api and apps/agent. No autocapture, no session replay and nothing client-side anywhere a record can be reached. Autocapture on a CRM would lift contact names, email addresses, company domains and deal amounts out of your database; the simplest way not to hold that is not to collect it. The single exception is the marketing site at trycrm.ai, which is a web page and not an install — The landing page, below, is the whole of it, and it cannot run on your hostname.
  • One identifier, a UUID generated by the migration that created your database. It is attached to nothing else. identify() is never called, there are no person properties, and no user, email or ALLOWED_SIGN_IN value is ever sent.
  • One event a day, plus eight one-shot setup events and one event per failure.
  • No IP address. Every event sets $ip: null and disables geoip, and the receiving project has anonymize_ips on so the address is dropped at ingestion. Both are needed: PostHog stamps $ip from the incoming connection whatever the SDK sends, and reads a null as "not provided" rather than "do not keep". Point this at a different project and you must set it there too.
  • Never blocks and never throws. Every send is fire-and-forget behind a swallowed handler; a telemetry failure logs at debug and is invisible everywhere else.
  • Off leaves no marks. With telemetry disabled the rollup route returns before the funnel sweep runs: no milestone is recorded, no counter is drained, no rollup day is claimed. Turn it back on and the funnel is still whole, because nothing was quietly consumed while it was off.
  • Nothing is sent from a test run. NODE_ENV=test disables it, and apps/api and apps/agent additionally set CRM_TELEMETRY_DISABLED=1 in their test scripts — because a spec is allowed to reassign process.env.NODE_ENV, and one that does was enough to let a real event out.
  • An allowlist, in code. ALLOWED_PROPERTIES in packages/telemetry/src/allowlist.ts names every property that may be sent. Anything else is dropped before the event is built — not by review, not by convention.

Events

install_daily

Once per install per day, from the API itself. Counts and distributions from grouped queries. Never a value from a row.

It runs in-process and needs no cron. TelemetryService rolls up on boot and then hourly, and the day claim below makes all but the first of those a no-op. That covers both shapes an install comes in: a serverless deployment rolls up on a cold start, a long-running container on the timer. POST /internal/telemetry/rollup still exists for a platform cron that would rather drive it, and still refuses without CRON_SECRET — it is an anonymous route, so an unauthenticated one would let a stranger drive any install's aggregation. Nothing depends on it: an install that never sets CRON_SECRET reports exactly the same.

The day is claimed under a row lock on install before anything is gathered, so two crons that fire at once produce one event rather than two — and the second does not find the counters already drained. A rollup that fails to send hands the day and the counters back, so tomorrow's run is not suppressed by a send that never happened.

The event carries a deterministic uuid, stableUuid(install.uuid, "install_daily", day) — a SHA-256 digest in a v8 UUID — and PostHog ingests a repeat of one it has already seen only once. RFC 4122 defines v5 as SHA-1, and CodeQL rightly refuses to see a hash of the install identity and a weak algorithm in the same expression. Nothing here needs v5, so it is v8, the slot RFC 9562 leaves for a derivation of one's own. The lock stops two processes racing; the id stops the same process sending twice, which the release path can otherwise cause. Counting installs survives a duplicate either way, because PostHog's unique math is per install per day, but tool_calls_total and the other summed properties would be counted twice, and now are not.

A send reports failure conservatively. posthog-node does not reject on a failed send — its sendImmediate catches the error and emits it on the client instead — so client.ts enqueues and awaits flush(), which does throw, and additionally checks the client's error counter, which any capture in flight can move. Either signal is treated as a failure. That errs toward re-sending a rollup that actually landed, which the deterministic id makes free, rather than consuming a day whose event never arrived, which cannot be recovered.

The install

Property What it is
crm_version The root package.json version, re-read on every boot
git_commit_sha VERCEL_GIT_COMMIT_SHA when there is one; omitted otherwise
days_since_install Whole days since the first migration ran
is_vercel Whether VERCEL is set
node_version Major only, e.g. 22
postgres_version Major only, e.g. 17
members_bucket How many people work here, in bands
agent_model_id The model chosen on Settings → General, e.g. zai/glm-5.2-fast
agent_model_context_window Its context window in tokens
seed_only True when every contact came from bun run db:seed

Capabilities — booleans, never values

cap_perplexity, cap_context_dev, cap_blob, cap_github, cap_redis, cap_agent_bridge, cap_cron_secret, cap_ai_gateway, cap_google_oauth, cap_sso_provider, cap_tracking, is_marketing.

Each is only whether the key is set. cap_context_dev is whether an AppSetting row holds one, cap_sso_provider whether an ssoProvider row exists, cap_tracking whether a tracking site id has been minted — never the id itself. No key, value or last-four is sent.

cap_context_dev covers both of the agent's Context capabilities: company brand data by domain, and reading a person off a LinkedIn URL. They are one key, so they are one boolean.

The agent

Property What it is
tool_calls Calls in the last 24h, keyed by tool name
tool_calls_total Their sum
tool_errors Of those, the ones that returned an error, keyed by tool name
sandbox_used Whether any sandbox tool (bash, grep, glob, file reads and writes) ran
sessions_started / sessions_completed / sessions_failed Distinct sessions in the window
tools_per_session_mean Tool calls divided by sessions that made one
tasks_claimed / tasks_completed / tasks_retired AgentTask counts keyed by kind
task_attempts_mean / task_attempts_max Attempts per kind
budget_exhausted Sessions that stopped because the research budget ran out. Once per session, not once per blocked tool call
recheck_scheduled recheck tasks queued in the window
recheck_interval_days Their intervals, in day bands
agent_conversations How many AgentConversation rows exist

Tool names are matched against the authored tools in apps/agent/agent/tools/ and eve's own builtins. Anything else is counted as other. Task kinds are matched against TASK_KINDS.

Tool counts are read from the agentEvent rows the audit hook already writes — the event type and the tool name only. AgentEvent.data itself is never sent.

The evidence ledger

Property What it is
facts_by_status ContactFact counts by APPLIED / PROPOSED / DISMISSED / SUPERSEDED
facts_by_band Counts by VERIFIED / PROBABLE / POSSIBLE
facts_by_method Counts by the method label a tool recorded
facts_by_evidence_kind Counts by evidence kind, from the WEIGHTS map in lib/evidence.ts
fact_dismissal_rate The share of decided facts a human rejected
fact_decision_median_hours Median hours from observedAt to decidedAt
facts_superseded_within_7_days Facts the agent changed its mind about

Evidence kinds are matched against the eleven in lib/evidence.ts; anything else is other. method is a label a tool writes, so it is sent only when it matches a strict lowercase dotted-slug shape under 40 characters — a name, an address or a sentence cannot pass, and is counted as other instead. The fact's value, field, evidence and sourceUrl are never sent.

The CRM

Property What it is
contacts_bucket, companies_bucket, deals_bucket, activities_bucket Sizes, in bands
contacts_by_source, companies_by_source Counts by MANUAL / IMPORT / EMAIL / CALENDAR
deals_by_stage Counts by DealStage. Stages, never amounts
activities_by_type Counts by ActivityType
mailbox_sync_configured Whether any MailboxSync row exists
mailbox_sync_status Counts by GoogleSyncStatus
threads_ingested, messages_ingested How many arrived in the window. Counts only
enrichment_by_status Company counts by EnrichmentStatus
suppressed_domains, suppressed_contacts Counts. Never the domains or addresses
workspace_profile_written Whether a WorkspaceProfile row exists

Website tracking

Property What it is
tracking_domains How many domains are on the allow list, in bands. Never a host
tracking_page_views Page views recorded in the window. A count, never a path
tracking_forms Form submissions stored in the window. A count, never a field
tracking_contacts_created Contacts created by tracking in the window — Contact.source = TRACKING, not submissions that attached to somebody already filed
tracking_capped Submissions the hourly contact cap refused. Matched against CONTACT_CAP_REASON (@crm/db/tracking) exactly, so the wording is a constant two files share rather than prose one of them may reword
tracking_paused Whether collection is paused

The setup funnel

Eight events, each sent once per install, ever. Each carries the timestamp of the thing it records rather than the moment it was noticed, so the funnel reads true even though a nightly job is what sends it.

migrations_applied → first_sign_in → google_oauth_configured → first_mailbox_sync → first_non_seed_contact → first_agent_task_claimed → first_agent_task_completed → first_fact_applied

They carry no properties of their own beyond the common ones — version, days since install, whether this is Vercel.

google_oauth_configured is the one step with no row to read a time off: two environment variables leave no timestamp behind. It is stamped from the first Google account row when one exists — configuration must have come before the account did — and otherwise from the moment the sweep first saw the variables set. That sweep runs on every API boot, not only on the cron, so an install that arrives configured is stamped on its first boot.

first_fact_applied is the earliest decidedAt of any fact a human accepted, or the earliest observedAt of any fact the agent applied itself, whichever came first. Facts that were applied and later superseded still count — being replaced later does not make the first application not have happened.

The step is claimed before it is sent, and handed back if the send fails. The claim is the insert itself — telemetryMilestone.step is the primary key, so of two processes sweeping at the same instant exactly one is told it landed the row, and only that one sends. A failed send deletes the row, so the next sweep tries again rather than losing the step forever.

This is the opposite of the ordering the funnel shipped with, which sent first and recorded after. That was chosen on the grounds that a duplicate is a rounding error while a lost step cannot be recovered — but it made a duplicate the likely outcome rather than a rare one, because both the boot sweep and the rollup call sweep(). One install sent first_fact_applied six times. Claiming first costs the case the old ordering was protecting against: a crash between the claim and the send drops the step. Each event also carries a deterministic uuid, stableUuid(install.uuid, step), so a step that is genuinely sent twice is still ingested once.

Nothing is recorded at all while telemetry is off.

Errors

Error class and where it came from. Never a message, never a stack trace, never a payload: our errors would carry contact fields.

Event Properties
agent_error error_class, tool, task_kind, error_source (tool / turn / session)
sync_error error_class, sync_source (gmail / calendar / outlook), error_source (google_sync / microsoft_sync / mailbox_sync)
api_error error_class, route, status_code
model_error error_class, model_id

sync_error's error_source is derived from sync_source rather than passed in, so one mailbox pipeline that dispatches to both providers cannot report an Outlook failure as a Google one. A source that is not one of the three is sent as other, and its error_source as mailbox_sync.

route is the route pattern — /internal/sync/google, /trpc/contacts.list — never a URL with parameters in it. Anything that does not match a strict path shape is sent as other, and so is any error class that is not a plain identifier.

The landing page

trycrm.ai is the one place posthog-js runs: web analytics and session replay of strangers reading a pitch. It is a website, not an install — there is no database behind that page and no record within reach of it. Everything above still holds for the CRM itself.

It cannot run on your hostname. analyticsAllowed (apps/app/lib/analytics.ts) compares window.location.hostname against two literals — trycrm.ai and www.trycrm.ai — and posthog-js sits behind a dynamic import() on the far side of that check. Turn IS_MARKETING="true" on and serve the same page from a domain of your own and the SDK is never fetched: not sent and then dropped, never downloaded. The gate is the hostname rather than IS_MARKETING, because IS_MARKETING is precisely the flag a self-hoster is invited to set.

PostHog refuses it from the other side too. recording_domains on the receiving project names the same two origins, so replay and heatmaps are declined for any other page that presents the key.

It shares the install's project, key and host, and the two do not mix: the landing page sends $pageview, $pageleave, $autocapture, $web_vitals and the two CTA events below about a browser, an install sends install_daily and its funnel about a database. Install events set $process_person_profile: false, so they never become a person and never join one.

The two CTA events

Event When
setup_prompt_copied The setup prompt reached the clipboard — after the write resolves, so a refused clipboard is not counted as a copy
github_star_clicked The Star on GitHub button was clicked. A click on the way to GitHub, not a star: whether one was given happens on a page we cannot see

Both carry one property, cta_location — hero or closing — because both buttons appear twice on the page and which one a stranger reaches is the only interesting thing about them. Nothing else is attached.

They go through captureLanding in components/landing/analytics.tsx, behind the same hostname gate and the same dynamic import() as init. On any other hostname the SDK is never fetched, so the click is not sent and then dropped — there is nothing there to send it. Both sends are fire-and-forget behind a swallowed handler; neither delays the copy or the navigation.

anonymize_ips stays on, and that costs something here: PostHog drops the address before geoip runs, so the landing page has no country, region or city. That setting is what makes the no-IP promise above true for every install, and an install's anonymity outranks a marketing map. A separate project is the only way to have both.

ALLOWED_PROPERTIES does not reach these events — it guards what packages/telemetry builds, and these are the browser SDK's own. What it sends is ordinary web analytics: URL, referrer, UTM parameters, browser, device, screen size, a session ID. Replay masks every input by default and the page has no field to type in.

What is never sent

  • Any Contact or User name, email, title or photo
  • Any Company name, domain, industry or location
  • ContactFact.value, .sourceUrl, .evidence, .field
  • AgentTask.reason and AgentTask.outcome — both free text the agent wrote about a named person
  • ContactBrief content, WorkspaceProfile.website, .narrative, .sections
  • EmailThread and EmailMessage subjects or bodies, CalendarEvent titles, CalendarAttendee rows
  • Deal names and amounts. Stage distribution is fine; amounts are not.
  • AgentEvent.data, AgentConversation content, prompts, completions, reasoning traces
  • ALLOWED_SIGN_IN, AppSetting.contextDevApiKey, any key, secret, token or connection string
  • SuppressedDomain and SuppressedContact values — counts only
  • IP address. Set $ip: null and disable geoip. n8n collects IP and has to caveat their anonymity claim because of it. We do not need it and we would rather the claim be unqualified.

On that last line: the two properties alone do not achieve it, because PostHog fills $ip in from the connection during ingestion. anonymize_ips is enabled on the receiving project, which is what actually drops it. See adrs/telemetry.md.

Where it lives

packages/telemetry The only place posthog-node is imported. Allowlist, install accessor, event builders
install table The UUID, the version, and when the last rollup went. One row, made by the migration
telemetryMilestone table Which funnel steps have fired
telemetryCounter table The one runtime number no other row records — budget_exhausted — drained by each rollup and put back if the send fails
packages/telemetry/src/project.ts The key, the ingest host and the UI host. Three constants, no imports, so the browser can read them too
apps/api/src/telemetry The daily rollup, the funnel sweep, the boot-and-hourly timer, the optional cron route
apps/agent/agent/hooks/telemetry.ts Tool, turn and session failures
apps/app/lib/analytics.ts The two hostnames the landing page may report from
apps/app/components/landing/analytics.tsx The only posthog-js import in the repo, behind that gate and a dynamic import(). init on mount, captureLanding for the two CTA events

Nothing is instrumented inside apps/agent/agent/sandbox, which runs deny-all egress by design. A capture in there would hang and then fail.

Adding a property

  1. Add its name to ALLOWED_PROPERTIES. Until it is there, it is dropped.
  2. Add a row to the table above.
  3. If it is an open set of keys — a tool, a method, a route — give it a permitted* function so the keys are constrained too, not just the property name.