Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Product telemetry: the event catalogue
What the Switch core server reports about how it is used, where it goes, and
what may never be in it. Design note for CHOO-2806.
This is the product/usage half of telemetry. The operational half —
structured logging, the export path itself, server health, tracing and
alerting — is CHOO-2807 and lands first. The two meet at one seam, described
under What this needs from the export path.
This is the reference for what the server reports: the events, their exact
properties, and the rule that keeps identifiers out of them. It is enforced
rather than merely documented — core/switch_core/telemetry/catalogue.py is the
same catalogue in executable form, and an event that does not match it raises
where it is built. Read them together; the code is authoritative on the shape
and this is authoritative on why.
What we are trying to learn
Two questions, and they want different shapes of data.
How much is Switch used, and is it growing? Counts of users, rooms, agents, sessions and connectors, over time. These are reported as a daily snapshot.
How quickly does a new deployment reach value, and where does it get stuck? How long from install to a working connector, from install to a room that is actually being used, and whether one collaboration platform is markedly harder to set up than another. These are reported as one-time milestone events carrying elapsed time.
The second question is the one that changes what gets built, so it is worth being explicit: it requires a per-deployment clock starting at install, and it requires each milestone to be emitted exactly once, ever.
Where it goes
The Switch Console already reports to the company OTLP relay, which fans out to
Amplitude (product analytics) and Datadog (operations). The relay holds the
vendor keys; senders carry no credential and are admitted on a client id alone.
The endpoint and the wire format are in
console/apps/switch-console-desktop/src/main/core/telemetry/ — config.ts for
the endpoint, relay-client.ts for the payload.
The server reports to the same relay, in the same shape. There is deliberately no second pipeline: a second one is a second thing to secure, a second consent story, and a second place for a customer's data to leak from.
The Console's implementation is the reference for the wire format, and its choices are load-bearing rather than incidental:
- One OTLP log record per event, not a metric and not a span. Amplitude
consumes events; the relay's filter keys on the
event.nameattribute. - The event name is sent twice — as the log record's own
eventNamefield and as anevent.nameattribute. The relay filters on the attribute and the exporter reads the field. Sending only one is dropped silently, with a 200 at every hop. - A name prefix per product, because one Amplitude project holds several.
The Console sends
switch_console.<event>; the server sendsswitch_core.<event>. - Numbers go as
doubleValue, booleans asboolValue. The relay delivers both typed to Amplitude and Datadog — zero andfalseincluded — so a count can be summed and a flag filtered on at the far end. A number sent as text arrives as a category instead. The relay's own test suite pins this end to end; the tests beside each encoder pin the half Switch controls. - Non-finite numbers are refused before sending. JSON has no NaN or infinity, so neither could arrive as a number whatever the relay did with it.
- At most 100 attributes per record. The relay drops any record over 128 and still answers 200. The margin is held by a test over every event, on both the server and the Console.
- At most 16 KiB per event. The relay drops an event over 32 KiB before it reaches Amplitude, because Amplitude refuses a request over 1 MB. It answers 200 and counts the drop. A test over every event, at its largest possible values, holds the margin on both clients; the largest today is about 3 KiB.
Which Amplitude project
The relay keeps one Amplitude project per environment and files each event
under the one its flint_env resource attribute names: prod, staging,
dev or local. An event naming none goes to production, and one naming
anything else is dropped and counted. So every event says where it belongs,
even prod:
- The server sends
TELEMETRY_ENVIRONMENT, which defaults toprodbecause every customer's deployment is production. Flint's own development deployment setsdev;.env.example, whichjust init-envcopies for a developer's machine, setslocal. Any other value stops the server at startup. It is set by the Helm chart'sswitchCore.telemetry.environment, and forwarded by the standalone compose file. - Switch Console sends one per build:
prodfrom a released stable build,stagingfrom a released canary,devfrom a packaged build that is not a release (a test build, or one packaged on a laptop), andlocalwhen run from source. The release workflow stamps tagged buildsVITE_RELEASE=1, and a test holds every build step to it. A server Console runs for the user is given Console's.
flint_env rides on the resource, beside the client id. It describes where
the reporting process runs, not anything inside the deployment, so it is not
an identifier in the sense of the rule above.
Internal usage
Staff use the product too, and their usage is real but is not adoption. Three signals tell it apart, none of them an identifier:
flint_internalon the resource:"true"or"false"from the server, set byTELEMETRY_INTERNAL(HelmswitchCore.telemetry.internal) on the company's own deployments and never on a customer's. Switch Console sends"true"when any account it is signed in to a Switch server with is onsandboxaq.comorsandboxquantum.com,"false"when only other accounts are, and"unknown"when none is; only that answer leaves the machine. A server Console runs for the user is given Console's answer.user_internal_countin the daily snapshot: accounts on those domains, so a deployment that serves both staff and customers can be split.user_internal_active_1d/_7ddo the same for the active counts, so customer activity isuser_active_*minus them.- Each deployment's
flint.client_id, for the company's own deployments by name.
tenant_id is deliberately not one of them: no identifier for anything inside
a deployment is ever sent, and a tenant is inside one.
What the relay's 200 means
The relay answers 200 once it has accepted a payload, before it forwards
anything: it batches, and at response time it does not yet know whether
Amplitude will take the events. So a 200 means received, never delivered,
and a sender cannot learn from the response that an event was lost. That is
deliberate. An error status would be either a 400 the sender can do nothing
about or a 500 that makes it retry the same payload forever.
Making loss visible is therefore the relay's job, not the sender's: counting what it receives, what its own checks drop, and what Amplitude and Datadog refuse, and alerting on those counts. The relay's own repository documents the metrics, the alerts and how they are switched on, and the gaps that remain.
What that leaves to Switch is not sending anything the relay would drop: the event name in both places, finite numbers, the attribute and size margins, and a valid client id.
The rule: abstracted counts, never specifics
No identifier for anything inside a deployment is ever sent. Not a room, tenant, agent, user, message or channel — not the name, not the id, and not a hash of either.
This is the same rule the Console holds itself to (console/AGENTS.md), and
the Console enforces it with a test that tries to smuggle a room name into
every event and asserts it never reaches the wire. The server needs the
equivalent.
It costs less than it sounds, because every metric asked for is a count or a duration. The server counts locally, where it legitimately knows the ids, and reports only the total. What is given up is per-room and per-tenant breakdowns: we can say a deployment had 40 active rooms this week, never which.
Specifically never sent, in addition to any identifier:
- message bodies, prompts, code, or any room content
- room, agent, group, reference or document names
- file paths, working directories, repository names or URLs
- user emails, sign-in identities or platform handles
- hostnames, IP addresses, or the external channel a room is bridged to
- error messages and stack traces — an enumerated reason code instead
Free text never reaches the wire at all: every property is a number, a boolean,
or a value from a closed set fixed in code. Almost every set is written out in
the catalogue; bridge_platform is the platforms this build registers, which
are code too. A property carrying an unexpected value is a bug to be raised,
not a string to be passed through.
Deployment identity and the install clock
The relay admits a sender on a client id and nothing else, so the server needs one. It does not have one today.
A per-deployment id: a random UUID generated once on first use and stored in
the database, sent as the flint.client_id resource attribute. It identifies
the installation, and nothing else — it is not derived from a hostname, a
licence, a tenant, an account or any customer value, and it survives restarts
and redeploys so that a deployment is one Amplitude subject over its whole life
rather than a new one each boot.
The row that holds it also holds installed_at, and that timestamp is the
clock every time-to-value metric is measured from. It is written once, when the
id is generated, and never updated.
In Amplitude, a deployment is the user. Every event from one installation collapses onto it, which is what makes a funnel across the milestone events below work natively: Amplitude computes time-to-convert between two events for the same subject.
A deployment running several tenants reports as one subject, because the alternative is a per-tenant identifier, which is exactly what the rule above forbids. Tenant count is reported; tenant identity is not.
Time to value is measured for new deployments only. When the id is
generated, the server checks whether the database already holds rooms, agents or
messages. On an empty database this is a genuinely new installation:
installed_at is set to now and the milestone events below are armed. On a
database that already has content, the deployment predates this telemetry,
installed_at stays null, and no milestone event is ever emitted for it.
No approximation, and no backfill. An install date guessed from the oldest row would be wrong by an unknown margin in an unknown direction, and a funnel built on it would read as confident when it is not. A deployment that cannot answer "how long did activation take" should say nothing rather than guess, so the time-to-value figures describe only installations actually watched from their first boot.
The counts in the daily snapshot are unaffected — every deployment reports those, old or new.
Resource attributes
On every event:
| Attribute | Value |
|---|---|
service.name |
switch-core, always |
service.version |
the running version, as /version reports it; omitted when unknown |
flint.client_id |
the per-deployment id |
flint_env |
prod | staging | dev | local, from TELEMETRY_ENVIRONMENT |
flint_internal |
true | false, from TELEMETRY_INTERNAL |
And one event property on every event, added by the service rather than declared by any event (no event may declare it):
| Property | Value |
|---|---|
deployment_kind |
switch_cloud when the switch_cloud feature flag is on; else managed_by_console when Switch Console runs the server (MANAGED_BY_CONSOLE); else self_hosted. The same answer get_my_context gives an agent |
A property rather than a resource attribute because the relay passes event properties to Amplitude and promotes only a fixed few resource attributes, so this is what lets a chart take Switch Cloud's traffic out, or look at it alone.
The rule against free text holds here too. service.name is a constant rather
than the SERVICE_NAME setting, and the ENVIRONMENT setting is not sent as
deployment.environment: both are free text an operator sets for their own log
pipeline, and either could name their company. The operational OTLP export
(OTLP_ENDPOINT) still carries both, because it goes to the operator's own
collector. A test sets both to a company name and checks the whole request body
the relay receives for it.
Four kinds of event
A daily snapshot, one per deployment, carrying the counts that describe the installation. This answers "how much".
Period counts, one per deployment per finished day, week and month, each counting distinct rooms and people over exactly that period. This answers "how many this week" in a way that adds up across deployments.
Milestone events, emitted at most once per deployment, each carrying the seconds elapsed since install. This answers "how fast to value".
Lifecycle events, one per occurrence, low volume. These carry mix and failure: which platforms are in use, how often a bridge drops, whether one connector fails repeatedly before it works.
Message events, one per message, the only high-volume kind. These carry how much is said and between whom — people to agents, agents back, people among themselves — and the size of the room it was said in.
The snapshot exists because of the identifier rule. Without room ids, per-occurrence events can tell you how much happened but never across how many rooms — counting distinct anything in Amplitude requires an identifier for the thing being counted. Counting locally and reporting the total sidesteps it.
Message events, and what they cannot tell you
An earlier version of this note argued against an event per message, for three reasons. Each is now answered rather than ignored:
- Volume. The relay path used to post one request per event. The relay sink now batches: events wait up to five seconds, or until two hundred are queued, and go as one request. Its buffer is bounded, so a relay that is down costs events, never memory.
- The sender must not pay for it. The transport and the router hand a small record to a queue and return. One worker looks up the room and the sender — cached, so a busy room is read once every fifteen minutes rather than once per message — and emits. That queue is bounded too, and drops with a warning when it falls behind.
- Content risk. The events carry the same kind of property as every other: closed sets, booleans and counts. There is no property a message body, a name or an id could reach, and the catalogue test enforces it.
They count messages, not people. No user id is ever sent, so in Amplitude
every event from a deployment belongs to one subject — the deployment — and
Amplitude's own "active users" counts deployments. How many people are active
comes only from the snapshot, which counts distinct people locally and reports
the total: chat_identity_in_room_count (seen in a room at all),
chat_identity_posted_* (said anything) and chat_identity_active_* (said
something in a room with an agent), with user_active_* counting the same
last tier as Switch accounts. The message events say how much those people
said, and to whom.
Definitions
These are the definitions the counts below are computed against. They are written down because most of them have a plausible alternative reading, and a metric whose definition drifts is worse than no metric.
Interaction — a human sent a message in a room that has at least one agent in it, or an agent replied to one. This is the unit "active" is built on throughout: mere membership is not activity, and two agents talking to each other is not a human using the product.
Active user — a human user with at least one interaction in the window. Counted distinctly per window, so one person in six rooms is one active user.
Active room — a room with at least one interaction in the window. Reported
over both one day and seven, because a weekly figure flatters a product used
intensely on Mondays and a daily one punishes it. Counted over rooms of every
origin, unlike the headline room_count — a bridge-adopted channel people
actually use is real usage even though it is not a room anybody created in
Switch.
Room created by a user — a room a human made, through the gateway or the Console. This is the headline "Rooms" figure. Rooms an agent provisioned for itself are counted separately and never stand in for it: an orchestration that spins up ten scratch rooms is not ten rooms of customer value, and letting the two share a number would make adoption look like whatever the agents happened to be doing that week.
Session — an agent session as the connection registry knows it: opened when an agent connects, closed when it disconnects or its heartbeat lapses.
Connector — a collaboration platform bridge (Slack, Mattermost, Discord, Teams, Telegram). A connector is added when a bridge for that platform first reaches a connected state; configuring one that never connects is not an add, which is deliberate — the metric is about reaching value, not about saving a form.
Agent runtimes (Claude Code, Codex, OpenCode) are counted too, under
agent_*_count, but they are not what "connector" means in the time-to-value
metrics below.
Room created by the system — a channel Switch adopted because it was invited to it on a platform, rather than one anybody asked for. Counted separately from both of the above, because folding these into the headline would make "rooms a person created" read as "channels this workspace happens to have".
The catalogue
Event names are snake_case, past tense, prefixed switch_core. on the wire.
Every event of a given name always carries exactly the same property keys —
where a property does not apply, it carries an explicit none rather than being
omitted, so a missing key always means a bug rather than a case.
Every event that can fail carries outcome, so that the failure population is
never invisible.
usage_snapshot — once a day per deployment
| Property | Type | Notes |
|---|---|---|
tenant_count |
number | tenants this pass actually counted — see tenant_failed_count |
tenant_failed_count |
number | tenants whose queries raised and were stepped over. One tenant's failure no longer takes the whole pass down, so the pair is what makes a partial pass self-describing: without it, every count dropping at once is indistinguishable from a deployment losing its users |
duration_ms |
number | wall time to collect the pass, on a monotonic clock. Roughly twenty queries per tenant against the database that is also serving rooms, and a background task is invisible to switch.http.request.duration — so this is the only place "what does the snapshot cost at scale" can be answered from |
user_count |
number | user accounts that exist |
user_internal_count |
number | of those, accounts on the company's own email domains — see "Internal usage" |
user_active_1d |
number | distinct Switch accounts that used a room with an agent in 24h: an account counts when a chat account it has claimed spoke. One person on two platforms is one account. Superseded by account_active_1d, the same figure; sent for one more stable release |
user_active_7d |
number | same over 7 days. Superseded by account_active_7d |
user_internal_active_1d |
number | of user_active_1d, accounts on the company's own email domains |
user_internal_active_7d |
number | same over 7 days |
chat_identity_count |
number | chat identities — Slack, Mattermost and other platform accounts — that exist, claimed by an account or not |
chat_identity_active_1d |
number | distinct chat identities that used a room with an agent in 24h. Most belong to no Switch account and one person may have several, which is why this runs above user_active_1d. Servers released before this change reported this figure as user_active_1d. Counts integrations as well as people; superseded by person_identity_active_1d plus bot_identity_active_1d, and sent for one more stable release |
chat_identity_active_7d |
number | same over 7 days. Superseded likewise |
person_identity_active_1d |
number | the headline count of people — distinct chat identities that used a room with an agent in 24h and never posted as an app in that window, linked to a Switch account or not. One person on two platforms is two identities. See "People, bots and accounts" |
person_identity_active_7d |
number | same over 7 days |
bot_identity_active_1d |
number | distinct chat identities that posted as an app in a room with an agent in 24h: an integration such as an alerting or CI app, or another Switch server's agent. See "People, bots and accounts" |
bot_identity_active_7d |
number | same over 7 days |
account_active_1d |
number | distinct Switch accounts that used a room with an agent in 24h, the same figure as user_active_1d under the name it keeps. The floor of the people count: an account exists only for someone who linked one |
account_active_7d |
number | same over 7 days |
chat_identity_posted_1d |
number | distinct chat identities that said anything in any room in 24h, agent or no agent |
chat_identity_posted_7d |
number | same over 7 days |
chat_identity_in_room_count |
number | distinct chat identities Switch has seen in a room: a member of at least one unarchived room of any origin, or anyone who said anything in the last 7 days. Not a channel's whole audience — see "Tiers of activity" |
room_count |
number | the headline figure — unarchived rooms a person created |
room_agent_created_count |
number | unarchived rooms an agent created for itself |
room_system_created_count |
number | unarchived channels Switch adopted after being invited to them on a platform |
room_active_1d |
number | rooms of any origin with an interaction in 24h |
room_active_7d |
number | same over 7 days |
room_archived_count |
number | archived rooms, both kinds |
room_internal_only_count |
number | rooms with no external channel |
room_membership_total |
number | user–room memberships summed over rooms |
room_users_mean |
number | mean human members per room |
room_users_max |
number | largest human membership of any one room |
agent_count |
number | registered agents |
agent_active_7d |
number | agents that interacted in 7 days |
agent_claude_code_count |
number | agents by runtime |
agent_codex_count |
number | |
agent_opencode_count |
number | |
agent_other_count |
number | including agents with no known runtime |
session_live_count |
number | connections open at snapshot time |
connector_<platform>_count |
number | configured bridges by platform: one property per platform this build registers (connector_slack_count, connector_teams_count, …), so a new platform adds its own |
connector_configured_count |
number | configured, whether or not connected |
message_count_1d |
number | messages in 24h |
message_from_human_1d |
number | of those, sent by humans |
message_from_agent_1d |
number | of those, sent by agents |
turn_human_to_agent_1d |
number | agent messages answering a person |
turn_agent_to_human_1d |
number | person messages answering an agent |
turn_agent_to_agent_1d |
number | agent messages answering another agent |
attachment_count_1d |
number | attachments in 24h |
reference_count |
number | references the tenant owns |
reference_attached_count |
number | of those, attached to at least one room |
document_count |
number | documents |
document_attached_count |
number | of those, attached to at least one room |
package_count |
number | packages |
room_group_count |
number | room groups |
api_key_count |
number | API keys |
Per-platform counts are separate properties rather than one map because the
platform set is closed and small, and because Amplitude charts a property far
more easily than it charts a nested object. They count configured bridges,
whether or not each is currently connected — which is up is process state, and
bridge_connected / bridge_disconnected are how that is reported.
People, bots and accounts. A messaging platform relays posts from more
than people: an alerting or CI integration, a workflow, and another Switch
server's agents sharing the channel all post there. Switch relays them into
the room like any post, through the same kind of chat identity a person gets,
so chat_identity_active_* counted them as people. Where the platform says a
post came from an app (a Slack app, a Discord bot or a webhook that is not
Switch's own, a Mattermost bot account or incoming webhook), the bridge marks
it, and that identity counts in bot_identity_active_* rather than
person_identity_active_* for the whole window. Telegram never delivers
another bot's posts and Teams does not mark them, so nothing there is counted
as a bot. A post relayed before its bridge marked app posts carries no mark,
so for the first week after upgrading, an integration that has not posted
since can still count as a person. account_active_* is the floor:
integrations never link a Switch account, and most people never link one
either.
What counts as a message. Every durable event is a row in the message log:
arrivals, tool- and LLM-call reports and task transitions sit beside the
conversation. The message counts, the turn counts and every "interacted" figure
above (user_active_*, room_active_*, agent_active_7d) read only what a
participant said: chat messages, and commands a person typed on a platform.
The automatic notice Switch posts under an agent's name when it cannot take a
request is excluded as well — the agent did not say it.
Tiers of activity. chat_identity_in_room_count,
chat_identity_posted_7d and chat_identity_active_7d nest: everyone Switch
has seen in a room, those who said anything, and those who said something in a
room with an agent. The nesting holds by construction — anyone who posted in
the last 7 days counts as seen, even if they have since left the room or it
was archived. chat_identity_posted_7d - chat_identity_active_7d is people
talking only to each other. All three count chat identities, so someone on both
Slack and Teams counts twice; only the top tier is also counted as accounts
(user_active_*). "In a room with an agent" stands in for "talked to an
agent": whether a message addressed one is decided per agent as it is
delivered, and is not stored where a count can read it.
agent_message_received is the per-message measure of that.
What "seen in a room" cannot see. Switch records a person in a room only
when they post, are added by name, or join the channel after Switch adopted
it. Nothing lists the members a channel already had, so someone who has only
ever read an adopted channel is in no count here, and
chat_identity_in_room_count - chat_identity_posted_7d is not the passive
audience: it is the people Switch happens to know about who stayed quiet,
usually a small fraction of the real one. Counting readers would take a
member sync on each platform, which no bridge does today.
Turns rather than senders. A turn is one message classified by who sent the
message before it in the same room. That is the only way to tell an agent
answering a person from two agents talking among themselves: a sender-only count
reports both as "from an agent" and hides the difference that matters. The
pairing reads off seq, which is a total order within a room with no ties;
human-to-human is not counted, and neither is a turn whose predecessor was a
bridge relay or the admin client.
No count of sessions started. Nothing durable records a session opening, so
the snapshot could only report an in-process tally that a restart silently
resets — a number that looks like a count and is not one.
agent_session_started is emitted per occurrence instead.
The three message_*_1d figures come from the message table, which is
deliberately a parallel record of the bus rather than the authoritative one: a
write that fails after a successful send leaves a gap, so that a database
problem can never make messaging less reliable. These counts are therefore
near-complete, not exact. That is fine for "how much, and is it growing", and it
should be said plainly wherever the number is presented rather than discovered
later.
usage_period — once per finished day, week and month
The snapshot's *_7d counts are a trailing week, sent every day. A chart that
adds them up at a weekly interval counts a room once for every day it was in
the window, up to seven times. A daily interval avoids that, but a server that
is off on a given day, as laptops often are, sends nothing for it. usage_period is counted over a fixed
calendar period instead, and sent once per period, so at the matching interval
the sum across deployments is the real figure.
| Property | Type | Meaning |
|---|---|---|
period |
day / week / month |
a UTC day, an ISO week (Monday to Monday, UTC), or a calendar month |
room_active |
number | distinct rooms a person used with an agent in the period: room_active_*'s definition |
person_identity_active |
number | distinct people who did, bots excluded: person_identity_active_*'s definition |
account_active |
number | distinct Switch accounts among them: account_active_*'s definition, deduplicated across tenants |
tenant_failed_count |
number | tenants whose counts could not be read, left out of the three above, as on the snapshot |
Chart it at its own interval. Filter on one period, set the interval to
match, and sum each property: weekly active rooms is the sum of
room_active over usage_period where period = week, at a weekly interval.
At any other interval the sum is wrong again — weeks summed into a month count a
room once per week — so each interval has its own chart. Across deployments the
sum counts a person who uses two servers twice, as every per-deployment figure
does.
Dated to the middle of the period, not to when it was sent: noon for a day, Thursday noon for a week, the middle of the month. A server that was off sends what it missed when it next runs, and an event dated "now" would land in a later bucket than the period it describes. The middle is inside the same day, week and month whichever day a chart starts its weeks on and in any timezone it is drawn in. Datadog's log intake refuses records dated more than 18 hours back, so its copy of the relay's events has few of these; Amplitude takes them.
Sent with the snapshot, for every period that ended since the previous
snapshot, so each is sent once. Not on a deployment's first pass, which has no
previous snapshot to measure from. A server back after a long time off sends
only the periods that ended in the last 35 days, which still covers the month
before for a laptop that was off for most of the month after. Like
room_became_active, a server whose telemetry was switched off and on again
sends the periods that ended in between, within those 35 days.
Accounts, workspaces and cloud machines
Switch Cloud's funnel: someone signs up, makes a workspace, and gets a cloud
machine for their agents. Any server that does these sends the events, so read
them with deployment_kind (on every event) to look at Cloud alone. Each is
sent once the change is committed: a machine change made in a transaction that
then rolls back is never reported.
| Event | Properties | Sent when |
|---|---|---|
account_created |
method: signup (the sign-up page) / oidc (a first single sign-on sign-in) / admin (an admin created it) |
a new account exists. A single sign-on sign-in that links an existing account is not one |
signup_refused |
reason: disabled / rate_limited (the hourly cap) / email_taken |
the sign-up page was refused |
workspace_created |
new_organization (boolean): an organization was created with it |
a workspace and its owner's membership exist |
cloud_machine_requested |
change: new / joined_workspace (the owner's machine now serves another workspace) / unretained (a machine kept after its agents left, running again) / restarted (a stopped machine started by a claim) |
a claim changed something; a claim on a machine already running is not reported. One event per claim, naming the first of these that applies, so a retained machine joined from another workspace is joined_workspace though it also runs again |
cloud_machine_ready |
new_machine (boolean) · provisioning_seconds: from the claim to the first controller report for a new machine, -1 for a later start |
the machine's controller reported at its current revision |
cloud_machine_failed |
reason: not_scheduled / never_started / never_connected (each after 10 minutes) / owner_left (its owner is in none of its workspaces) / needs_attention / reported (any other error the machine reported) |
the machine went into error; not again while it stays there |
cloud_machine_woken |
trigger: message (its agent was addressed) / agent_placed / owner · stopped_by: idle / owner / unknown |
a stopped machine was started again |
cloud_machine_stopped |
reason: idle / owner |
a running machine was told to stop |
Milestone events — at most once per deployment
Each carries seconds_since_install (number). Together with
deployment_installed they form the activation funnel. Emitted only by
deployments installed after this ships — see
Deployment identity.
| Event | Emitted when | Extra properties |
|---|---|---|
deployment_installed |
the deployment id is generated on an empty database | — |
first_connector_added |
the first bridge a person added reaches connected | bridge_platform |
first_room_created |
the first user-created room is created | channel_type, bridge_platform |
first_room_active |
that room sees its first interaction | bridge_platform, seconds_since_room_created |
first_agent_registered |
the first agent registers | known_agent_type |
first_session_started |
the first agent comes online: its first live connection. Superseded by first_agent_connected, the same moment; sent for one more stable release |
known_agent_type |
first_agent_connected |
the first agent comes online | known_agent_type |
first_agent_session |
a host reports the first coding-agent session (session_started): an agent doing work |
known_agent_type, start_source |
first_agent_connected and first_agent_session were added after deployments
were already running. One that had already passed them claims them without
reporting, once, at the first boot of a version that has them, so it is never
reported as doing for the first time what it did long ago: first_agent_connected once first_session_started was claimed,
and first_agent_session once first_room_active was claimed or a session was
reported in the last 7 days. A deployment whose only sessions were started
from Switch Console, more than a week before upgrading, with no person ever
using a room with an agent, reports first_agent_session late.
The two room milestones track user-created rooms only, for the reason given under Definitions: a room an agent made for itself is not the moment a customer got started, and counting it would report activation that never happened.
first_room_active is the one that matters most: it is "install to seeing
value" end to end, and its seconds_since_room_created separates the two halves
of that journey — whether the time went on getting a room set up, or on getting
anyone to use it once it existed.
Emitted once ever, not once per process. Each needs a persisted marker, so a restart cannot re-emit one and a deployment that passes a milestone while telemetry is switched off does not emit it later as though it had just happened.
Lifecycle events
connector_added — every connector, not only the first.
| Property | Type |
|---|---|
bridge_platform |
platform |
seconds_since_install |
number |
seconds_since_configured |
number — configuration saved to first connect |
is_preconfigured |
boolean — registered by the deployment's setup step, not a person |
is_first_connector |
boolean — the first connector a person added |
failed_attempts_before_success |
number |
Preconfigured connectors. The standalone stack, the Helm chart and every
Console-managed local server run a setup step that registers the bundled
Mattermost seconds after install. That connector reports is_preconfigured: true, is never is_first_connector, and never claims first_connector_added
— so that milestone is the first connector a person added, not the deployment
booting. Filter connector_added on is_preconfigured = false to measure
onboarding. A bundled connector registered before the flag existed is marked
on the setup step's next run; if it first connects before that, its one
connector_added reports false.
connector_added fires only for a first connect that was seen. A
connector's first connect is recorded whether telemetry is on or not, so one
that first connected while telemetry was off never reports connector_added:
its setup went unmeasured, and reporting it later would report its whole age.
Connectors that already existed when this tracking arrived are recorded by a
migration and never report either. Servers released before it reported an old
connector's age instead, often millions of seconds; filtering to
seconds_since_install >= 0 drops most of those.
seconds_since_configured and failed_attempts_before_success are what answer
"is one platform too hard". Elapsed time from install mostly measures when
somebody got round to it; time from configuring a bridge to it actually
working, and how many failures came first, measures the platform. Teams needing
six attempts and Slack needing one is the finding worth having.
The honest limitation: much of connector setup happens in the platform's own admin UI, which the server cannot see. These metrics cover the part that starts when Switch is first told about the bridge.
room_created
| Property | Type |
|---|---|
channel_type |
channel_public | channel_private | direct | none |
bridge_platform |
platform, or none for internal-only, or unknown for a bridge whose platform is not registered in this build |
agent_count |
number |
human_count |
number |
has_instructions |
boolean |
created_by_kind |
user | agent | system |
from_template |
boolean |
room_became_active — the first interaction in a room, once per room.
| Property | Type |
|---|---|
seconds_since_room_created |
number |
bridge_platform |
platform |
channel_type |
channel type |
agent_count |
number |
created_by_kind |
user | agent | system |
created_by_kind rides along rather than agent-created rooms being dropped, so
the headline chart can filter to user-created rooms while the question "do
agent-made rooms ever get used?" stays answerable from the same event.
This is "time to create an active room" for every room, not only the first. The distribution is the interesting part: if rooms created in week one go active in minutes and rooms created in week six never do, that is a different problem from a slow average.
room_archived — bridge_platform, age_days (number), was_ever_active
(tri-state: true | false | unknown — unknown when the activity count
itself could not be run, which is not evidence the room was never used).
room_agents_added — agent_count (number), added_by_kind (user | agent | system).
room_agents_removed — agent_count (number), removed_by_kind (as above).
Removals
Every count in the snapshot can fall, and on its own a falling line says
nothing about why. A drop in room_count is a customer tidying up, a bridge
being disconnected, or a deployment being abandoned — three opposite readings,
and the difference is only recoverable if the removal was reported when it
happened.
Each carries the lifespan of the thing removed, because "deleted after an hour" and "deleted after a year" are opposite signals: the first is a mistake or an experiment, the second a deliberate clean-up.
room_deleted — bridge_platform, channel_type, created_by_kind,
age_days, was_ever_active (tri-state, see room_archived above),
agent_count. The activity flag is read before the delete, because the
cascade takes the room's messages with it and afterwards every room looks like
it was never used.
agent_deleted — known_agent_type, age_days, room_count,
had_parent.
connector_removed — bridge_platform, age_days, was_ever_connected
(tri-state: true | false | unknown), room_count. was_ever_connected is
the one that matters: a connector removed having never connected is a failed
setup, and one removed after months of service is a decision. Reporting both
as "removed" would hide the first, which is the one worth acting on.
unknown when the durable record backing it could not be read — reporting
that as false would misfile a lookup failure as a failed setup.
agent_registered
| Property | Type |
|---|---|
agent_type |
always_on | session_addressable | session_passive | auto_session |
known_agent_type |
claude-code | codex | opencode | other | none |
registration_path |
bootstrap | personal_key | gateway | other |
has_parent |
boolean — a subagent rather than a top-level agent |
agent_connected — known_agent_type, and agent_disconnected —
the properties of agent_session_ended below. The same two events as
agent_session_started and agent_session_ended, under names that say what
they measure. Both pairs are sent for one more stable release.
agent_session_started — known_agent_type. An agent coming online: its
first live connection, not a session a person began. Sessions share their
agent's one connection, held by Switch Console or a remote host's sidecar, so
this fires when that connection opens and not again when a session starts on
it. Deliberately nothing about how: the server cannot tell, and a property
that takes the same value on every emission cannot segment anything.
session_started — start_source (user | room | automation |
unknown), known_agent_type. A coding-agent session starting, reported once
by the host that runs it when the session is new — never on a resume. The
launcher stamps start_source: user is a person starting one in Switch
Console, room the agent being addressed in a room, automation Console's
local automation API. unknown is a launcher that said nothing, reported
rather than dropped so an unstamped launch path is a visible gap. "Sessions a
person started" is start_source = user. It is the launcher's claim, not proof
a person clicked, and hosts older than this report nothing.
Guarded against a caller inventing sessions: the id must be a UUID (every
launcher mints one), and an agent reporting more than 120 starts in an hour is
not counted until the rate drops, with a warning logged. The claim that makes a
retried report count once is a row in telemetry_milestones, pruned after 7
days by the daily snapshot pass; a report retried later than that, whose first
attempt did arrive, counts twice.
agent_session_ended — duration_seconds (number), reason (normal |
heartbeat_lapsed | replaced | room_claimed | error). No runtime: the
connection registry is the only thing that knows a session ended and it holds
none, the client's self-declared artifact is free text and may not be sent, and
looking the agent up would put a query on the connection sweep. Session starts
carry the runtime, so the mix is available from those.
The connection registry already records a reason on every close, which is where these values come from; the set is closed here so a new reason string added in the code does not silently become a new Amplitude value.
bridge_connected — bridge (collaboration | agent), bridge_platform,
outcome, failure_reason, duration_ms. bridge is always collaboration
today; agent is declared so the agent bridge can report the same events.
Fires for every attempt, including the ones that fail before the bridge's task is ever scheduled — an unregistered adapter type, a stored config that no longer validates, a port another bridge already holds. Those used to emit nothing at all, so the connect success rate was computed over a denominator that excluded the attempts that failed hardest.
duration_ms is how long the attempt took, in whole milliseconds on a
monotonic clock, spanning both halves of it: the synchronous setup and the task
that actually reaches the platform. Nothing else times this — a bridge comes up
on a background task rather than inside a request the server serves — and the
failure half is the more interesting one, because a timeout and a refusal carry
the same failure_reason and nothing alike in the time. -1 if no reading was
taken, following the convention below.
bridge_disconnected — bridge (as above), bridge_platform, reason
(shutdown | restart | auth_failed | network | platform_error |
config_invalid | unknown).
Bridge drops are worth having as events rather than only as a snapshot count: the snapshot says two bridges are down right now, the events say one platform has flapped forty times today. That is the difference between noticing and diagnosing.
deployment_started — tenant_count. The version is already a resource
attribute, so this gives an upgrade curve across installations: which versions
are actually running. Deliberately no "did this boot apply migrations" flag:
migrations run in a different event loop from the server, so the answer would
have to be carried across on a module global, and it is operational trivia
rather than something the product wants to know.
Message events — one per message
All three come from telemetry/messages.py, reported off the sender's path as
described above. A post with
several files is one message. Room facts are cached for fifteen minutes, so a
member count can be that far behind; who a sender is and an agent's runtime,
which do not change, for an hour. A room, sender or agent whose lookup
fails is not looked up again for five seconds, and its events report it as
unknown meanwhile; every other room carries on. Three failures in a row,
with no lookup succeeding between them, pause every lookup for five seconds.
Either way a database incident shows in the charts as a burst of unknown
rather than as missing messages.
room_message_sent — everything a participant chose to say in a room: the
population the tenant is metered for, reported by the transport after the
write commits. What Switch posts on a participant's behalf — greetings, command
replies, offline and refusal notices, a template's kickoff — is not in it.
Neither is a command a person types (!reset, a slash command): commands are
not metered, although the snapshot's activity counts treat one as something
the person said.
| Property | Type |
|---|---|
sender_kind |
user | bot | agent — only participants are metered, so platform does not occur here. bot is an integration's post (see "People, bots and accounts"); before that value existed those were user |
bridge_platform |
platform, none for an internal room, unknown if the room could not be read |
channel_type |
channel type, or unknown if the room could not be read |
room_user_count |
number — human members of the room, -1 if it could not be read |
room_agent_count |
number — agent members, -1 if it could not be read |
has_attachment |
boolean |
in_thread |
boolean |
The average of room_user_count over these events is the room size a typical
message is said to — weighted by messages, not by rooms. Filter out
bridge_platform = unknown before averaging: those are rooms that could not
be read, and their -1 would pull the mean down. Every property is required on
every event and the catalogue has no empty value, so -1 is the marker. The
snapshot's room_users_mean is the per-room figure.
agent_message_received — a message an agent was asked to act on:
addressed to it (by name, alias, role, or a direct room) and let through its
addressing policy and budget, whether or not the agent was there to take it.
Reported by the agent's consumer, where that is decided, so a message naming
two agents is two of these and one room_message_sent. Switch's own
auto-replies are excluded; a request Switch carries on a person's behalf is
included, as platform. A message a hosted agent's mailbox already holds — the
same message seen again — is not counted twice, and nor is a multi-file post
whose files arrive too far apart to be delivered together: it is counted with
its first file. A typed command addressed to an agent is not counted.
agent_live splits being asked from being there: filter on it to count only
the requests an agent could act on as they arrived.
| Property | Type |
|---|---|
sender_kind |
user | bot | agent | platform | unknown — bot as for room_message_sent |
known_agent_type |
the receiving agent's runtime |
bridge_platform |
platform |
channel_type |
channel type |
has_attachment |
boolean |
agent_live |
boolean — the agent had a live session for the room when the message arrived. False when it was offline, still starting, or its cloud worker refused the message (stopped, broken, or a full mailbox); always false for a session_passive agent, which reads its messages later rather than live |
agent_message_sent — a message an agent posted: its replies, status
updates, anything it chose to say. Every one is also a room_message_sent with
sender_kind = agent; this one carries the runtime as well. room_user_count
separates an agent answering people from agents talking among themselves.
| Property | Type |
|---|---|
known_agent_type |
the sending agent's runtime, or unknown if the agent could not be looked up |
bridge_platform |
platform |
channel_type |
channel type |
room_user_count |
number, -1 if the room could not be read |
has_attachment |
boolean |
in_thread |
boolean |
Decision routing — one per decision
One per message auto-route asked a decision service about
(decision/client.py). Neither says which room, agent or message: only
whether an agent was picked, how sure the service was, how long it took, and
which kind of backend answered, so the share of decisions that chose nobody,
failures by reason and latency percentiles can be read per backend.
decision_made — the service answered, with an agent or with nobody.
| Property | Type |
|---|---|
backend |
server_default | endpoint | haiku_anthropic | haiku_bedrock — the server's own decision service as a workspace's default, a workspace's own endpoint, or Haiku |
outcome |
agent | none |
confidence |
none | lt_0.5 | 0.5_0.6 | 0.6_0.7 | 0.7_0.8 | 0.8_0.9 | 0.9_1.0 — the service's confidence in its choice, in tenths above one half; none when it gave none |
latency_ms |
number — measured by Switch around the whole request |
decision_failed — the service gave no usable answer, so the message went
to nobody or to the room's triage agent.
| Property | Type |
|---|---|
backend |
as above |
reason |
timeout | unreachable | error_status | bad_answer (not a decision, or an agent that was not a candidate) | key_unreadable (a workspace key the server can no longer decrypt) | endpoint_refused (a workspace endpoint the server's outbound policy does not allow: link-local, or private and not in OUTBOUND_ALLOWED_PRIVATE_HOSTS) |
Resources, keys, groups and the rest
What each one is for, and how to make it fire, is under Every event, and how to make it fire. This is what each carries.
| Event | Properties |
|---|---|
reference_created |
reference_type; read_visibility (private | public); created_by_kind (user | agent | system) |
reference_attached_to_room |
reference_type |
reference_detached_from_room |
reference_type |
reference_deleted |
reference_type; age_days (number) |
document_created |
scope (library | room); created_by_kind (user | agent | system); has_instructions (boolean) |
document_attached_to_room |
none |
document_detached_from_room |
none |
document_deleted |
scope (library | room); age_days (number) |
package_created |
created_by_kind (user | agent | system) |
package_attached_to_room |
reference_count (number); document_count (number) |
package_detached_from_room |
none |
package_deleted |
age_days (number) |
reference_type_created |
none |
reference_type_deleted |
age_days (number) |
api_key_created |
key_type (agent | registration | bootstrap | other) |
api_key_revoked |
key_type (agent | registration | bootstrap | other); age_days (number) |
room_group_created |
has_parent (boolean) |
room_group_deleted |
room_count (number); age_days (number) |
template_created |
template_kind (room | group | agent | other) |
template_deleted |
template_kind (room | group | agent | other); age_days (number) |
agent_request_refused |
operation (list_templates | get_template | run_template | save_template | update_template | delete_template | create_room | create_room_from_yaml); reason (not_found | not_yours | name_taken | visibility_not_allowed | invalid | too_large | has_warnings | missing_agents | agent_creation_console_only | agents_not_created | run_undone | busy | run_paused | run_stopped | repeat | kickoff_ignored) |
room_link_created |
none |
room_link_removed |
none |
room_role_defined |
exclusive (boolean) |
room_role_deleted |
none |
room_users_added |
user_count (number) |
connector_configured |
bridge_platform; is_preconfigured (boolean) |
invitation_sent |
delivery (sent | not_configured | failed | not_requested) |
invitation_accepted |
age_hours (number) |
Closed value sets
bridge_platform: a platform this build registers — today slack |
mattermost | discord | teams | telegram — or none | unknown. The
set is read from the platform registry when an event is checked, so a new
platform adds its own value; a platform key is code, a short lowercase name,
never anything an operator typed. none is "no bridge" (an internal-only
room); unknown is "there is one and it could not be named", because the
lookup failed or its platform is no longer registered. The two are kept apart
because collapsing them would misreport a Slack-bridged room as internal-only
whenever that lookup has a transient error.
channel_type: channel_public | channel_private | direct | none |
unknown, with unknown meaning what it does for bridge_platform. Every
event with a channel_type accepts unknown, but only the message events send
it today; the room events read the type from a row they already hold.
reference_type: google_drive | confluence | github | jira | other. The
four built-in types; a user-defined type's slug is free text, so it reports as
other.
sender_kind: user | bot | agent | platform | unknown. user is a
person on a messaging platform and bot an integration posting there (see
"People, bots and accounts"); platform is Switch itself speaking; unknown a
sender whose client could not be looked up.
outcome: success | failure. failure_reason is an enumerated code per
event, none on success — never an exception message.
bridge_connected.failure_reason is none | auth_failed | network |
platform_error | config_invalid | unknown. bridge_disconnected.reason
takes the same failure codes without none, plus shutdown and restart. The
failure codes are shared because one classifier feeds both: a value that
classifier can produce and only one of the two declares is an event that fails
validation at the moment a bridge drops — which is precisely the event worth
not losing.
Tri-state facts: true | false | unknown, for a yes/no property the
server can fail to establish (room_archived/room_deleted.was_ever_active,
connector_removed.was_ever_connected). Not a boolean, deliberately — a
property that can be unknown is a three-valued fact, and collapsing the failed
case into false reports a guess as a claim the code has no evidence for.
Where a duration or an age cannot be known — a deployment with no install
clock, a bridge whose configuration timestamp is unreadable, a row whose
created_at could not be read — the property carries -1 rather than 0, so
"we could not tell" is distinguishable from "it happened instantly" or
"created just now".
Any property whose value is not in its declared set is a bug. It should raise
where the event is built rather than be coerced, dropped, or silently widened
to a value nobody added to the catalogue. This is a different statement from
the tri-states above: unknown is fine as a value the catalogue itself
declares for the handful of properties that need it — what must never happen
is a value reaching the wire that the catalogue does not know about.
Consent
A Switch server reporting its usage to a vendor relay is a different question from a desktop app doing it, because the deployment may be a customer's and the usage may be theirs.
The Console's answer is opt-in, defaulting to off, gated on an explicit choice having been made, and re-read on every event so revoking takes effect immediately. The server takes the same position: telemetry is off unless switched on, it is one setting, and when it is off no request is made at all.
Who sets that one setting depends on who deployed the server. On a stack an
operator brought up themselves, they set TELEMETRY_ENABLED — in the .env for
the standalone compose file, or in the chart's values. On a stack Switch
Console runs for a user, the Console sets it from that user's "Share usage
data" answer at every start, in both directions, so the person running the
server and the person answering are the same person and answer once
(CHOO-2890). Because the gate is read at boot, a change to the answer reaches
a running server only when it restarts; the Console says so on the server's page
and offers the restart rather than taking it.
This interacts with the milestone events in a way worth stating: a deployment that enables telemetry three months in has already passed most of its activation funnel. Milestones are emitted only when they actually occur, never retroactively, so such a deployment simply contributes nothing to time-to-value — which is correct, and better than a backfilled figure that would read as an instant activation.
This is a setting an operator controls, and it must be documented where they will see it before they deploy — not only in this note. What is sent, where it goes, and how to turn it off belongs in the deployment documentation.
What this needs from the export path
The seam with CHOO-2807. The catalogue above needs the export path to provide:
- A send taking an event name and a flat map of properties, emitting one
OTLP log record with the resource attributes above, the
switch_core.prefix, and the name in both required places. - Non-blocking emission. A slow or unreachable relay must never delay a request, a message send, or a bridge event. A failed send is logged and dropped; telemetry is never worth a user-visible stall.
- The consent gate inside the send, so that no call site can bypass it and no new event can forget it.
- The deployment id and
installed_at, generated and persisted once. - A closed catalogue with the property allow-list enforced at the boundary, so an event carrying an undeclared property fails rather than shipping it.
Nothing on that list is specific to product events; each is equally needed for operational ones, which is why it belongs to the shared path rather than here.
Checking it works
Three layers, and they fail differently — a green one above does not prove the one below it.
What Switch would send. Start the local stand-in for the relay and point a development server at it:
python scripts/otlp_sink.py
# then, in the server's environment:
TELEMETRY_ENABLED=true
TELEMETRY_ENDPOINT=http://localhost:4318
TELEMETRY_SNAPSHOT_INTERVAL_HOURS=0.02
The endpoint is the base URL — /v1/logs is appended, the same convention
the operational export follows. A value carrying the signal path is refused at
startup, because posting to /v1/logs/v1/logs would be a 404 the relay reports
once per event into a log nobody is reading.
Product events are batched: they arrive at the sink up to five seconds after they happen, several to a request. Whatever is buffered at shutdown is posted on the way out, several batches at once, within a one-second shutdown budget: the message worker's drain takes at most 0.4 seconds of it and the sink has the rest. What cannot be posted in that time is lost, and the server log says how many events that was.
The same sink serves the operational export, so one process shows both streams. Every event is printed as it arrives, decoded, with all of its properties. Create a room, register an agent, connect a bridge, send a message, and watch. The first snapshot lands about a minute after boot, so the whole catalogue is exercisable in a few minutes without anything leaving the machine.
That the numbers are right. Each snapshot pass logs a one-line summary at
INFO before sending — rooms, active rooms, users, agents, messages. Compare
it against the same counts taken straight from the database. If they disagree,
the snapshot's query is wrong and the relay would have accepted the wrong
answer without complaint.
That the relay accepts it. This is the layer that fails silently, and the
only one that cannot be checked locally. A 200 does not mean a record was
kept: OTLP reports partial success in the response body, so
python scripts/otlp_sink.py --reject 1 is how to check Switch notices — it
should log a warning naming the event. --fail 503 checks the other
direction, that a refused send is logged and dropped rather than raising into
whatever was happening at the time.
Against the real relay, the only proof is a staging deployment with reporting on for one interval, and the events appearing downstream. Nothing short of that tests the vendor's own filtering.
Every event, and how to make it fire
Work down the list against a local sink
(python scripts/otlp_sink.py) and each one prints as it arrives with all of
its properties.
Two things to set up first, or a third of the list cannot fire at all:
- Start from an empty database. Milestones are armed only when the identity
migration runs against one with no rooms, agents or messages. On a database
that already has content
installed_atis null and the sixfirst_*events are suppressed for good — correctly, but it means an upgraded dev box can never be used to test them. - Shorten the snapshot interval.
TELEMETRY_SNAPSHOT_INTERVAL_HOURS=0.02. The first pass is 60s after boot and it polls every 5 minutes, so with the default of 24h you would see one snapshot and nothing else.
At boot, with no action at all
deployment_installed— fires once, on the first boot of a fresh install.main.py, after the migration. Absent on an upgraded database, by design.deployment_started— every boot. Same place.usage_snapshot— 60s after boot, then each interval.telemetry/reporter.py→run_once.
Rooms — room_service.py throughout; gateway routes under /gateway/rooms
room_created—POST /gateway/rooms. Checkcreated_by_kindisuserhere,agentwhen an agent creates one through its MCP tool, andsystemwhen Switch is invited to a channel on a bridged platform. Those three paths are the whole point of the property; test at least the first two.first_room_created— the same call, first time only, and only for a user-created room.room_agents_added—POST /gateway/rooms/{id}/agents. Adding an agent already in the room correctly emits nothing.room_agents_removed—DELETE /gateway/rooms/{id}/agents/{agent_id}.room_archived— archiving from the gateway, and from an agent'sarchive_roomtool. Unarchiving emits nothing.room_deleted—DELETE /gateway/rooms/{id}. Checkwas_ever_activeis true when someone had spoken in it: it is read before the delete, because the cascade takes the messages.room_became_active— needs two snapshot passes. Create a room with an agent in it, have a human post, then wait for the pass after the one that first saw it. Derived from the message table rather than emitted at send time.first_room_active— the same pass, once ever, user-created rooms only.
Agents — bridges/agent/protocol/service.py
agent_registered— registering a new agent.registration_pathshould begatewayfrom the dashboard or Console,personal_keyfrom a user's own registration key,bootstrapfrom the deployment-wide token. Re-registering an existing agent correctly emits nothing.first_agent_registered— the same call, first time only.agent_deleted—DELETE /gateway/agents/{id}. Carries how old it was and how many rooms it was in, both read before the row goes.
Sessions — bridges/agent/api/handlers.py, and the connection registry
agent_session_startedandagent_connected— an agent opening its event stream; both are sent. A supervisor reattaching to a connection it already had correctly emits nothing.first_session_startedandfirst_agent_connected— the same, once ever. On a deployment that claimedfirst_session_startedbefore this release,first_agent_connectedis claimed at boot and never sent.agent_session_endedandagent_disconnected— kill an agent and wait for the heartbeat sweep (a few seconds). Reported through a listener on the registry, so every path that closes a connection reports, not just the sweep.session_started—POST /agent-sessions/{id}/startedfrom a session host (bridges/agent/api/activity_routes.py), with a UUID id. A repeat for the same agent and session emits nothing, across restarts, for 7 days.first_agent_session— the firstsession_starteda deployment sends, once ever; claimed at boot without sending on a deployment that already had sessions (see the milestone table).
Messages — telemetry/messages.py, fed by transport/postgres.py and
delivery/recipient.py
room_message_sent— any person or agent posting in any room. A post with three files is one event. A command reply or an offline notice is none.agent_message_sent— an agent posting, through its MCP tool or the HTTP API. Arrives beside aroom_message_sentfor the same message.agent_message_received— tag an agent, or write in a direct room with one. Tag two agents and there are two. Tag an agent whose policy refuses you and there are none.
Decision routing — decision/client.py
decision_made— withdecision_routingon and a decision service set up,!auto-route onin a room and post an untagged question. "thanks!" is not asked about, so it emits nothing.decision_failed— the same with the decision service stopped (unreachable), or slower thanDECISION_TIMEOUT_SECONDS(timeout).
Connectors — bridges/collaboration/lifecycle_service.py
bridge_connected— a bridge reaching its platform. Also fires withoutcome: failurewhen it cannot; try bad credentials.connector_added— the first successful connect for that bridge, ever. Restarting a working bridge correctly emits nothing.first_connector_added— the first connector a person added on the deployment. The bundled Mattermost the setup step registers never claims it.bridge_disconnected— stopping a bridge (reason: shutdown), restarting one (restart), or a live bridge crashing.connector_removed—DELETE /gateway/collaborations/{id}. Checkwas_ever_connected: it reads the durable record, so a connector that worked months ago and was down at removal still reports true.
Resources, keys and groups — bridges/resource/service.py, and the
gateway routes under /gateway
reference_created/reference_attached_to_room/reference_deleted— make a reference, attach it to a room, delete it. Only the four built-in types are named; a user-defined type reports asother, because its slug is free text somebody chose.document_created/document_attached_to_room/document_deleted—scopeislibraryfor one in the shared library androomfor one an agent authored inside a room.package_created/package_attached_to_room/package_deleted. The attach carries how many references and documents came with it.api_key_created/api_key_revoked— mint and delete a key. The label is never sent, only what the key is for.room_group_created/room_group_deleted— the delete carries how many rooms were filed under it, read before the delete.invitation_sent/invitation_accepted— invite someone to a tenant and accept it. Accepting an invitation you already hold reports nothing, because nobody joined.
Creating is intent; attaching is use. Both are reported, and the distance
between them is the signal: a library of references nobody ever attached says
something quite different from one attached constantly. The snapshot carries
reference_count and reference_attached_count side by side for the same
reason.
Everything else with a lifecycle
reference_type_created/reference_type_deleted— registering a type, which is an owner extending what Switch can point at, not making a reference.template_created/template_deleted—template_kindnames the three the product uses and reports anything an operator invents asother.agent_request_refused: an agent asked for something a rule says no to: a template it did not save, a run that would need a new agent, a room in a paused or stopped run.operationandreasonare fixed lists; which agent and which template stay in the server log.room_link_created/room_link_removed,room_role_defined/room_role_deleted,room_users_added.reference_detached_from_room/document_detached_from_room/package_detached_from_room— the inverse of the attach events, so a resource tried and dropped is distinguishable from one never used.connector_configured— the bridge row being written, which is not the same as it connecting.is_preconfiguredseparates the setup step's own connector from one a person added. Many of these and fewbridge_connectedis a deployment whose setup is failing, and only the pair shows it.
Deliberately not reported, so the boundary is stated rather than discovered: edits that change a setting rather than create or remove something — an agent's icon, display name or addressing policy, a room's visibility, protection or observe config, moving a room between groups, renaming anything. They are configuration, not adoption, and each would be an event that fires constantly and answers nothing. Ask if one of them turns out to matter.
What a pass has not proved
Every event firing locally says the call sites are wired and the payloads are well-formed. It says nothing about whether the relay accepts them — that needs one event watched arriving downstream, which no local check can substitute for.
Open questions
- Query cost at scale. The snapshot is roughly twenty queries per tenant,
including two seven-day
DISTINCTscans overmessagesand a window function over the message table. Nobody has run it against a production-sized dataset. That is the open question most worth answering before this is switched on for a large deployment. - Cost of the snapshot. Several of its counts are distinct-count queries over the message table across a seven-day window. On a large deployment that is not free, and it should be measured before it runs daily on a live instance.
- Self-hosted versus hosted. The consent default is right for both, but a customer-operated deployment may warrant saying more in the docs than a pilot instance does.
- Retention and deletion. Owned by the relay rather than by Switch, but an operator who turns telemetry off will reasonably ask what happens to what was already sent. The answer should exist before someone asks.