A telemetry event is one of six fixed, content-free records a Chickpea deployment sends to the project’s maintainers after a committed milestone. Where a usage record and an audit entry stay inside the state a deployment owns, a telemetry event is the only product signal that leaves it. This page is the field-level catalog: the six event names, every property each carries, allowed values and fallbacks, the properties common to all six, the pseudonym derivation, and the delivery constants.
Source of truth: src/telemetry/events.ts holds the event union and the per-event property allowlist, src/telemetry/client.ts the common properties and delivery bounds, and src/telemetry/identity.ts the installation identity and pseudonyms. TELEMETRY.md in the product repository is the contract those files are reviewed against. The catalog is exhaustive: there is no autocapture, session recording, exception capture, or catch-all event API. For why telemetry exists and how to switch it off, see Product telemetry.
Event summary
| Event | Emitted when | Event-specific properties |
|---|---|---|
workspace_connected |
A Slack workspace installation moves into a healthy connected state | workspace_key, transport_mode |
agent_created |
A user-created Agent is committed | workspace_key, agent_key, surface |
connection_ready |
A connected account becomes ready for an Agent | workspace_key, agent_key, connection_kind, owner_kind, surface |
schedule_created |
A new schedule and its authority binding are committed | workspace_key, agent_key, cadence_kind, destination_kind |
run_completed |
An interactive delivery or a scheduled run reaches a terminal state | workspace_key, agent_key, agent_origin, trigger_kind, outcome |
installation_active |
The deployment claims the current UTC day | workspace_count, user_agent_count, ready_connection_count, enabled_schedule_count |
Properties on every event
Every event in the batch carries these eight properties in addition to its own.
| Property | Type | Value |
|---|---|---|
distinct_id |
string | The installation’s random UUID, stored under telemetry.identity.v1. |
timestamp |
string | ISO 8601 UTC time of the delivery attempt. |
schema_version |
number | 1. |
runtime_target |
string | cloudflare or node, from the running target. |
app_version |
string | The package version compiled into the release. The current pre-release reports 0.0.0. |
telemetry_environment |
string | production, development, or test. |
$process_person_profile |
boolean | false, so PostHog creates no person profile. |
$geoip_disable |
boolean | true, so PostHog derives no location from the request IP. |
Pseudonym properties
workspace_key and agent_key stand in for a Slack workspace ID and a Chickpea Agent ID. Both are installation-local: the same workspace produces unrelated values in two deployments, and neither can be reversed into the original ID.
- Derivation. HMAC-SHA-256 over the domain string
chickpea-product-telemetry-<domain>-v1, a NUL byte, then the local ID, keyed with the installation’s 32-byte key.<domain>isworkspaceoragent. - Encoding. The first 16 bytes of the signature, base64url without padding, which is 22 characters.
- Prefix.
ws_for a workspace,agent_for an Agent. - Constraint. The local ID must be a string of 1 to 512 characters. Outside that range no event is built and nothing is sent.
workspace_connected
Emitted when a Slack workspace installation transitions into a healthy connected state from a state that was not healthy. The “Use your own Slack app” lane records it after an installation credential check turns healthy. The “Add to Slack” lane records it when the gateway binding is stored and the previous health was not healthy.
| Property | Type | Allowed values | Fallback |
|---|---|---|---|
workspace_key |
string | Workspace pseudonym | None. Without a valid workspace ID the event is not built. |
transport_mode |
string | direct, gateway |
direct |
direct is the “Use your own Slack app” lane, gateway the shared gateway behind “Add to Slack”.
agent_created
Emitted when a user-created Agent is committed, either through Admin or through the management service. A fresh install seeds no Agent, so every Agent in a new deployment emits it.
| Property | Type | Allowed values | Fallback |
|---|---|---|---|
workspace_key |
string | Workspace pseudonym | None. Without a valid workspace ID the event is not built. |
agent_key |
string | Agent pseudonym | None. Without a valid Agent ID the event is not built. |
surface |
string | admin, slack, mcp, other |
other |
surface is the door the creation came through: Admin, a Slack conversation, or the management MCP server. The management service passes its caller’s origin, which is one of slack, mcp, and admin.
connection_ready
Emitted when a connected account first becomes usable by an Agent. The connections store records it when an account reaches lifecycle ready from another lifecycle and its Agent binding is enabled. The Slack setup routes record it when an MCP or API connection completes setup. The event does not identify the provider, toolkit, account, or account owner.
| Property | Type | Allowed values | Fallback |
|---|---|---|---|
workspace_key |
string | Workspace pseudonym | None. Without a valid workspace ID the event is not built. |
agent_key |
string | Agent pseudonym | None. Without a valid Agent ID the event is not built. |
connection_kind |
string | managed, mcp, api |
api |
owner_kind |
string | team, member |
team |
surface |
string | admin, slack, mcp, other |
other |
owner_kind distinguishes a team account (team) from a personal account (member). connection_kind is the connection’s lane: a managed connector, a vendor MCP server, or a direct API connection.
schedule_created
Emitted when a save operation in the management service commits a new schedule together with its Agent authority binding. Editing an existing schedule emits nothing. The event carries no task, expression, time zone, destination, or recipient.
| Property | Type | Allowed values | Fallback |
|---|---|---|---|
workspace_key |
string | Workspace pseudonym | None. Without a valid workspace ID the event is not built. |
agent_key |
string | Agent pseudonym | None. Without a valid Agent ID the event is not built. |
cadence_kind |
string | one_time, recurring |
one_time |
destination_kind |
string | channel, direct_thread |
channel |
recurring corresponds to a repeating trigger, one_time to a schedule that runs once. destination_kind says whether the result is delivered to a channel or to a direct thread, not which one.
run_completed
Emitted when a customer-visible interactive delivery or a scheduled-run settlement reaches a terminal state. Interactive deliveries are captured on Cloudflare, on Node, and in the ledger turn driver, and only when the turn reports an outcome, so a replayed delivery sends nothing. The event carries no output, duration, token count, model, failure class, or error text.
| Property | Type | Allowed values | Fallback |
|---|---|---|---|
workspace_key |
string | Workspace pseudonym | None. Without a valid workspace ID the event is not built. |
agent_key |
string | Agent pseudonym | None. Without a valid Agent ID the event is not built. |
agent_origin |
string | seeded, user_created |
Not applicable. It is computed, not supplied. |
trigger_kind |
string | interactive, scheduled |
interactive |
outcome |
string | succeeded, no_op, failed |
failed |
agent_origin is seeded when the Agent ID is agent_default, an id no fresh install produces any more, and user_created for every other Agent. Interactive deliveries report succeeded or failed only. no_op comes from a scheduled run that settles without delivering anything.
installation_active
A coarse installation snapshot, appended to the batch of another event at most once per UTC day. The deployment claims the day atomically under telemetry.active_day.v1 before reading any inventory, so concurrent activity produces one snapshot at most, and a snapshot that fails is not retried. The event is never sent on its own, and a client composed without an inventory store never produces it.
| Property | Type | Allowed values | What it counts |
|---|---|---|---|
workspace_count |
string | 0, 1, 2_4, 5_plus |
Slack workspace installations whose health is not revoked. |
user_agent_count |
string | 0, 1, 2_4, 5_plus |
Agents of kind user, which excludes the @Chickpea system Agent. |
ready_connection_count |
string | 0, 1, 2_4, 5_plus |
Connection accounts in those workspaces whose lifecycle is ready. |
enabled_schedule_count |
string | 0, 1, 2_4, 5_plus |
Schedule references of those Agents whose state is active. |
Bucketing runs before delivery and cannot be reversed into an exact number:
| Input | Bucket |
|---|---|
| Not a finite number, or 0 or less | 0 |
| Exactly 1 | 1 |
| 2 to 4 | 2_4 |
| 5 or more | 5_plus |
A fractional count is floored before bucketing.
Values that fall back or drop
The serializer treats its callers as untrusted and rebuilds each payload from the allowlist above.
- An unrecognised event name produces nothing. The event is discarded at the boundary rather than forwarded.
- An unrecognised property value becomes the fallback listed in that event’s table, so
surfacebecomesotherandoutcomebecomesfailed. - An invalid workspace or Agent ID cancels the event. A value that is not a string of 1 to 512 characters stops the build before any property is written.
- An oversized batch is dropped, not trimmed. A serialized body above 32 KiB is discarded.
- Properties outside the allowlist never reach the payload, whatever a caller passes.
Delivery constants
| Constant | Value |
|---|---|
| Endpoint | https://us.i.posthog.com/batch |
| Method | POST with content-type: application/json |
| Batch contents | The captured event, plus installation_active on the day it is claimed |
| Maximum request size | 32 KiB, 32,768 bytes of UTF-8 |
| Deadline | 5,000 ms, after which the request is aborted |
| Redirects | manual, never followed |
| Response body | Cancelled, never read |
| Retries | None. A failed delivery is discarded |
| Credential | A public PostHog project token compiled into the client, ingestion only |
A delivery failure is swallowed and cannot change an HTTP response, a Slack acknowledgement, an Agent result, a state transition, a retry decision, or a scheduled-run outcome.
Stored telemetry state
| Settings key | Contents |
|---|---|
telemetry.identity.v1 |
JSON holding version 1, the installation UUID, and the 32-byte HMAC key as 43 base64url characters. |
telemetry.active_day.v1 |
The last claimed UTC date, as YYYY-MM-DD. |
Both live in the deployment’s own app-settings store. The HMAC key never leaves the deployment.
Environment label
telemetry_environment resolves in this order.
| Condition | Label |
|---|---|
CHICKPEA_TELEMETRY_ENVIRONMENT is production, development, or test |
That value |
CHICKPEA_TELEMETRY_ENVIRONMENT is set to anything else |
development |
Unset, and NODE_ENV is one of the three values |
That value |
| Unset, on Cloudflare | production |
| Unset, on Node | development |
The label never disables an event, and an unsupported value cannot enter the production measurement set.
Opt-out variables
| Variable | Accepted values | Effect |
|---|---|---|
DO_NOT_TRACK |
1, true, yes, case-insensitive |
Disables all six events |
CHICKPEA_DISABLE_TELEMETRY |
1, true, yes, case-insensitive |
Disables all six events |
Either variable is enough. Values are trimmed before comparison, and a Cloudflare binding wins over a process.env entry of the same name. With either set, the telemetry composition returns a no-op before it reads or creates identity state, reads inventory, generates randomness, starts a timer, makes a network request, or writes a telemetry log. Nothing is buffered for later delivery. The full list of telemetry variables sits alongside every other setting in Environment variables.
What is not covered
- Semantic activity records are not telemetry. They are written to the deployment’s own log with the prefix
[chickpea:activity]and are never delivered off the deployment. - Usage and audit records stay in deployment state. They are not part of this catalog.
- Operational logs and exception paths are not capture points. Product hooks run only after committed milestones and terminal settlements.