Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
feat(telemetry): product usage telemetry for switch-core (CHOO-2806) (#487)
Christian McDermott83c5fbe160d8
diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.pyindex 6069d9511..1509ebdd7 100644--- a/core/switch_core/bridges/agent/api/handlers.py+++ b/core/switch_core/bridges/agent/api/handlers.py@@ -2,6 +2,7 @@ from __future__ import annotationsimport hashlibimport logging+from contextvars import ContextVarfrom datetime import UTC, datetimefrom typing import Annotated, Any, cast@@ -91,6 +92,7 @@ from switch_core.bridges.agent.protocol.connections import (from switch_core.bridges.agent.protocol.service import AgentExistsError, ProtocolServicefrom switch_core.bridges.agent.protocol.stream import event_streamfrom switch_core.bridges.agent.registration_bootstrap import (+ BOOTSTRAP_KEY_TYPE,REGISTRATION_KEY_TYPES,resolve_registration_owner_id,)@@ -151,6 +153,13 @@ async def _resolve_registration_user_id(key = await api_key_store.get_by_hash(session, token_hash)if key is None or key.type not in REGISTRATION_KEY_TYPES:raise HTTPException(status_code=401, detail="Invalid registration token")+ # Which credential this was is worth keeping: a deployment bootstrapping+ # its first agents through the shared key and a user minting a key of+ # their own are different moments in adoption, and the key type is the+ # only place that distinction exists.+ _REGISTRATION_PATH.set(+ "bootstrap" if key.type == BOOTSTRAP_KEY_TYPE else "personal_key"+ )try:return await resolve_registration_owner_id(session, protocol.user_store, key)except RuntimeError as exc:@@ -160,6 +169,18 @@ async def _resolve_registration_user_id() from exc+# How the current registration authenticated. A contextvar rather than a+# parameter because the owner-id dependency is where the credential is+# resolved and the endpoint body is where the agent is registered — threading+# it would mean changing the dependency's return type and every caller of it.+_REGISTRATION_PATH: ContextVar[str] = ContextVar("switch_registration_path")+++def registration_path() -> str:+ """How this registration authenticated, or `other` outside one."""+ return _REGISTRATION_PATH.get("other")++# Registration endpoints@@ -171,6 +192,7 @@ async def register_agent_endpoint() -> RegisterAgentResponse:try:result = await protocol.register_agent(+ registration_path=registration_path(),name=req.name,description=req.description,icon_url=req.icon_url,@@ -231,6 +253,7 @@ async def _register_known(try:result = await protocol.register_agent(+ registration_path=registration_path(),name=name,description=description,icon_url=icon_url,@@ -829,6 +852,17 @@ async def _open_event_stream(protocol.connections.close(conn.id, "room already claimed")raise HTTPException(status_code=409, detail=str(exc)) from exc+ # Every claim succeeded and the stream is about to be returned, so this is+ # the first moment a session exists. Reporting it where the connection was+ # created instead counted every rejected attempt as a session that began+ # and ended at once, which a retrying client repeats indefinitely.+ #+ # `stream_generation == 0` keeps a supervisor reattaching to a connection+ # it already had from reading as a new session: `open()` hands back the+ # existing Connection and bumps the generation rather than making another.+ if conn.stream_generation == 0:+ await protocol.sessions.started(agent, conn)+return StreamingResponse(event_stream(conn=conn,diff --git a/core/switch_core/bridges/agent/api/session_reporter.py b/core/switch_core/bridges/agent/api/session_reporter.pynew file mode 100644index 000000000..d4ed0ddef--- /dev/null+++ b/core/switch_core/bridges/agent/api/session_reporter.py@@ -0,0 +1,151 @@+"""Reporting an agent session, which is not the same as a connection.++Two ordinary things make an agent hold a succession of short connections while+being continuously present: a stream rejected at the room claim and retried,+and a stream whose heartbeat lapsed (six seconds) closing itself so the client+reopens. Per connection, both read as a session every few seconds.++So this reports on the **agent**: a session begins when one that had no live+connection acquires its first, and ends only once it has had none for+`_RECONNECT_GRACE_SECONDS`. The duration is the whole span.+"""++from __future__ import annotations++import asyncio+import logging+import time++from switch_core.bridges.agent.protocol.connections import (+ HEARTBEAT_TTL_SECONDS,+ Connection,+ ConnectionRegistry,+)+from switch_core.db.models import Agent+from switch_core.telemetry import TelemetryService, emit_safely+from switch_core.telemetry.snapshot import normalise_known_agent_type++logger = logging.getLogger(__name__)++# Several times the heartbeat TTL, because the reconnect this absorbs is+# triggered by that TTL lapsing. Too tight and every lapse is a new session.+_RECONNECT_GRACE_SECONDS = HEARTBEAT_TTL_SECONDS * 4++# The registry's reasons are prose. Anything unmapped reports `error` rather+# than failing validation at the moment a session drops.+_SESSION_END_REASONS = {+ "heartbeat lapsed": "heartbeat_lapsed",+ "room already claimed": "room_claimed",+ "invalid room subscription": "error",+ "replaced": "replaced",+ "shutdown": "normal",+}+++class _Session:+ __slots__ = ("started_at", "runtime", "ending")++ def __init__(self, started_at: float, runtime: str) -> None:+ self.started_at = started_at+ self.runtime = runtime+ # The task waiting out the grace period, if the agent currently holds+ # no connection. Cancelled by a reconnect.+ self.ending: asyncio.Task[None] | None = None+++class SessionReporter:+ """Reports agent sessions, coalescing the connections they are made of."""++ def __init__(+ self,+ telemetry: TelemetryService | None,+ connections: ConnectionRegistry | None = None,+ ) -> None:+ self._telemetry = telemetry+ self._connections = connections+ # Connection ids whose stream was actually handed back. A connection+ # closed before that — a rejected room claim — is not part of any+ # session and must not end one.+ self._streaming: set[str] = set()+ self._sessions: dict[str, _Session] = {}++ async def started(self, agent: Agent, conn: Connection) -> None:+ """A stream is about to be returned on `conn`."""+ self._streaming.add(conn.id)+ session = self._sessions.get(conn.agent_id)++ if session is not None:+ # Already in a session: another connection, or the reconnect the+ # pending end was waiting for. Either way it continues.+ if session.ending is not None:+ session.ending.cancel()+ session.ending = None+ return++ runtime = normalise_known_agent_type(agent.metadata_)+ self._sessions[conn.agent_id] = _Session(time.monotonic(), runtime)+ emit_safely(+ self._telemetry, "agent_session_started", {"known_agent_type": runtime}+ )+ if self._telemetry is not None:+ await self._telemetry.emit_milestone(+ "first_session_started", known_agent_type=runtime+ )++ def on_close(self, conn: Connection) -> None:+ """The registry's close listener, for every path that closes."""+ if conn.id not in self._streaming:+ # A refused room claim closed it on the way out; nothing began.+ return+ self._streaming.discard(conn.id)++ session = self._sessions.get(conn.agent_id)+ if session is None or session.ending is not None:+ return+ if self._connections is not None and self._connections.for_agent(conn.agent_id):+ # Still connected by another stream; the session did not end.+ return++ reason = _SESSION_END_REASONS.get(conn.closed_reason or "", "error")+ try:+ session.ending = asyncio.get_running_loop().create_task(+ self._end_after_grace(conn.agent_id, reason)+ )+ except RuntimeError:+ # Synchronous teardown. The grace period is an optimisation.+ self._report_end(conn.agent_id, reason)++ async def _end_after_grace(self, agent_id: str, reason: str) -> None:+ try:+ await asyncio.sleep(_RECONNECT_GRACE_SECONDS)+ except asyncio.CancelledError:+ # The agent came back. `started` already cleared the pending end.+ return+ if self._connections is not None and self._connections.for_agent(agent_id):+ session = self._sessions.get(agent_id)+ if session is not None:+ session.ending = None+ return+ self._report_end(agent_id, reason)++ def _report_end(self, agent_id: str, reason: str) -> None:+ session = self._sessions.pop(agent_id, None)+ if session is None:+ return+ emit_safely(+ self._telemetry,+ "agent_session_ended",+ {+ "duration_seconds": max(time.monotonic() - session.started_at, 0.0),+ "reason": reason,+ },+ )++ async def aclose(self) -> None:+ """Cancel any pending ends at shutdown, without reporting them: every+ agent disconnects at once, so a burst of ends is noise."""+ for session in self._sessions.values():+ if session.ending is not None:+ session.ending.cancel()+ self._sessions.clear()+ self._streaming.clear()diff --git a/core/switch_core/bridges/agent/app.py b/core/switch_core/bridges/agent/app.pyindex 91b80c68c..263b4df1f 100644--- a/core/switch_core/bridges/agent/app.py+++ b/core/switch_core/bridges/agent/app.py@@ -13,7 +13,7 @@ from switch_core.bridges.agent.api.version_routes import router as version_routefrom switch_core.bridges.agent.api_key_cache import ApiKeyCachefrom switch_core.bridges.agent.auth import BearerAuthMiddlewarefrom switch_core.bridges.agent.deeplink import router as deeplink_router-from switch_core.bridges.agent.dependencies import init_dependencies+from switch_core.bridges.agent.dependencies import get_protocol, init_dependenciesfrom switch_core.bridges.agent.mcp import create_mcp_appfrom switch_core.bridges.agent.protocol.connections import ConnectionRegistryfrom switch_core.bridges.agent.protocol.event_buffer import EventBuffer@@ -36,6 +36,7 @@ from switch_core.request_context import RequestContextMiddlewarefrom switch_core.room_service import RoomServicefrom switch_core.sessions.http import session_error_responsefrom switch_core.sessions.service import SessionError+from switch_core.telemetry import TelemetryServicelogger = logging.getLogger(__name__)@@ -57,6 +58,7 @@ def create_agent_bridge_app(session_factory: object,config: SwitchConfig,connections: ConnectionRegistry | None = None,+ telemetry: TelemetryService | None = None,) -> tuple[FastAPI, ProtocolService]:# One registry for the whole process: the live connection set is the source# of truth for reachability, so every service must see the same one. The@@ -90,26 +92,15 @@ def create_agent_bridge_app(bridge_store=bridge_store,session_factory=session_factory,config=config,+ telemetry=telemetry,)- protocol = ProtocolService(- agent_store=agent_store,- agent_session_store=agent_session_store,- room_store=room_store,- room_service=room_service,- client_lifecycle=client_lifecycle,- collab_lifecycle=collab_lifecycle,- event_buffer=event_buffer,- connections=connections,- task_store=task_store,- resource_service=resource_service,- api_key_store=api_key_store,- api_key_cache=api_key_cache,- external_user_store=external_user_store,- bridge_store=bridge_store,- session_factory=session_factory, # type: ignore[arg-type]- config=config,- )+ # The one `init_dependencies` just built, not a second of its own. Every+ # HTTP handler resolves that instance through `Depends(get_protocol)`, so+ # a second one here is an object whose wiring no request ever sees — which+ # is how the agent bridge came to emit every session event into a+ # telemetry service that was None.+ protocol = get_protocol()app = FastAPI(title="Switch Agent Bridge API")diff --git a/core/switch_core/bridges/agent/dependencies.py b/core/switch_core/bridges/agent/dependencies.pyindex da5cc5e37..4e916a525 100644--- a/core/switch_core/bridges/agent/dependencies.py+++ b/core/switch_core/bridges/agent/dependencies.py@@ -23,6 +23,7 @@ from switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.db.stores.task_store import TaskStorefrom switch_core.room_service import RoomService+from switch_core.telemetry import TelemetryService_state: dict[str, Any] = {}@@ -45,6 +46,7 @@ def init_dependencies(bridge_store: CollaborationBridgeStore,session_factory: Any,config: Any,+ telemetry: TelemetryService | None = None,) -> None:_state["agent_store"] = agent_store_state["agent_session_store"] = agent_session_store@@ -62,6 +64,7 @@ def init_dependencies(_state["bridge_store"] = bridge_store_state["session_factory"] = session_factory_state["config"] = config+ _state["telemetry"] = telemetry_state["protocol"] = ProtocolService(agent_store=agent_store,@@ -80,6 +83,7 @@ def init_dependencies(bridge_store=bridge_store,session_factory=session_factory,config=config,+ telemetry=telemetry,)diff --git a/core/switch_core/bridges/agent/protocol/connections.py b/core/switch_core/bridges/agent/protocol/connections.pyindex 228872470..fcf09ca3e 100644--- a/core/switch_core/bridges/agent/protocol/connections.py+++ b/core/switch_core/bridges/agent/protocol/connections.py@@ -25,7 +25,7 @@ from __future__ import annotationsimport asyncioimport loggingimport time-from collections.abc import Iterable+from collections.abc import Callable, Iterablefrom dataclasses import dataclass, fieldfrom typing import Literal@@ -230,6 +230,12 @@ class ConnectionRegistry:"""The live set of agent connections. Authoritative, in memory."""def __init__(self) -> None:+ # Called with every Connection this registry closes, whoever closed it.+ # A callback rather than a report at each call site: `close` is reached+ # from five places — the sweep, the stale-connection check, the stream,+ # and two room-claim failures — and a sixth added later would silently+ # report nothing. The registry stays unaware of what the callback does.+ self._on_close: Callable[[Connection], None] = lambda conn: Noneself._by_id: dict[str, Connection] = {}self._by_agent: dict[str, set[str]] = {}@@ -347,6 +353,16 @@ class ConnectionRegistry:conn.id,)+ def set_close_listener(self, listener: Callable[[Connection], None]) -> None:+ """Observe every connection this registry closes.++ One listener, set once at wiring time. It must not raise — a bad+ observer cannot be allowed to leave a connection half-closed — and it+ is called after the registry's own bookkeeping, so what it sees is the+ closed state rather than a connection mid-teardown.+ """+ self._on_close = listener+def close(self, connection_id: str, reason: str) -> Connection | None:conn = self._by_id.pop(connection_id, None)if conn is None:@@ -372,6 +388,19 @@ class ConnectionRegistry:conn.beats,time.monotonic() - conn.last_beat,)+ # After the bookkeeping and the log, so an observer sees the closed+ # state. Guarded because the registry's own contract — the connection+ # is closed and the caller gets it back — must not depend on whoever+ # is watching.+ try:+ self._on_close(conn)+ except Exception:+ logger.warning(+ "A close listener raised for connection %s; the connection is "+ "closed regardless.",+ connection_id,+ exc_info=True,+ )return conndef sweep(self) -> list[Connection]:@@ -565,6 +594,18 @@ class ConnectionRegistry:for conn in self.for_agent(agent_id))+ def live_connection_count(self) -> int:+ """How many connections are open right now.++ Distinct from `live_agent_ids`, which answers how many *agents* hold+ one: an agent may hold several (the cap is+ `MAX_CONNECTIONS_PER_AGENT`), so ten people running two windows each+ against one agent is twenty connections and one agent. Telemetry+ reports sessions, and a session is a connection.+ """+ now = time.monotonic()+ return sum(1 for conn in self._by_id.values() if conn.is_alive(now))+def live_agent_ids(self) -> set[str]:"""Every agent with at least one live connection.diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.pyindex b8a4752ea..28e3c8730 100644--- a/core/switch_core/bridges/agent/protocol/service.py+++ b/core/switch_core/bridges/agent/protocol/service.py@@ -22,6 +22,7 @@ from switch_core.agent_icon import normalise_icon_url, validate_icon_urlfrom switch_core.aliases import check_alias_collisions, validate_alias_formatfrom switch_core.attachments import parse_attachment_groupfrom switch_core.authz import Action, Principal, require, require_manage+from switch_core.bridges.agent.api.session_reporter import SessionReporterfrom switch_core.bridges.agent.api_key_cache import ApiKeyCachefrom switch_core.bridges.agent.mediation import MediationServicefrom switch_core.bridges.agent.protocol.agent_detail import (@@ -99,6 +100,8 @@ from switch_core.events import ()from switch_core.messages.recorded_types import MEMBERSHIP_EVENT_TYPEfrom switch_core.sessions.attachments import normalise_mime_type+from switch_core.telemetry import TelemetryService, emit_safely+from switch_core.telemetry.snapshot import normalise_known_agent_typefrom switch_core.tenant_context import current_tenant_id, tenant_scopefrom switch_core.transport import (TransportError,@@ -127,6 +130,20 @@ if TYPE_CHECKING:logger = logging.getLogger(__name__)++def _age_days(created_at: object) -> float:+ """How old a row is, in days, for reporting. Zero if unknown.++ Takes `object` because the timestamp columns are annotated `Mapped[str]`+ while carrying real `datetime`s, so the honest signature is "whatever the+ column hands back", checked here rather than trusted.+ """+ if not isinstance(created_at, datetime):+ return 0.0+ moment = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - moment).total_seconds() / 86400.0, 0.0)++# \A and \Z rather than ^ and $: Python's $ also matches before a single# trailing newline, which would let an identifier carry a line break._VALID_NAME_RE = re.compile(r"\A[a-z0-9][a-z0-9._-]*\Z")@@ -238,6 +255,11 @@ def _describe_room(room: Room) -> RoomDescriptor:class ProtocolService:+ # Class-level defaults: several tests assemble a minimal instance without+ # `__init__`, and `emit_safely` treats None as "report nothing".+ telemetry: TelemetryService | None = None+ sessions: SessionReporter = SessionReporter(None)+def __init__(self,*,@@ -257,7 +279,13 @@ class ProtocolService:bridge_store: CollaborationBridgeStore,session_factory: async_sessionmaker[AsyncSession],config: SwitchConfig,+ telemetry: TelemetryService | None = None,) -> None:+ self.telemetry = telemetry+ # Pairs session start with session end. Held here because the handler+ # that starts a session and the registry listener that ends one must+ # be the same object — an end is reported only for a start this saw.+ self.sessions = SessionReporter(telemetry, connections)self.agent_store = agent_storeself.agent_session_store = agent_session_storeself.agent_runtime_state_store = AgentRuntimeStateStore()@@ -310,6 +338,7 @@ class ProtocolService:overwrite: bool = False,addressable_by_agent_ids: list[str] | None = None,owner_only: bool = True,+ registration_path: str = "other",) -> RegistrationResult:"""Register or re-register an agent.@@ -379,6 +408,11 @@ class ProtocolService:api_key_hash = hashlib.sha256(api_key.encode()).hexdigest()encrypted_key = encrypt_token(api_key, self.config.jwt_secret_key)+ # Reported only for a genuinely new agent: a re-registration rotates a+ # key on an agent that already existed, and counting it would make a+ # CLI that re-registers on every launch look like adoption.+ newly_registered = False+async with self.session_factory() as session:existing = await self.agent_store.get_by_name(session, name)if existing and not overwrite:@@ -445,6 +479,24 @@ class ProtocolService:),)logger.info("Registered agent: %s (%s)", name, agent_id)+ newly_registered = True++ if newly_registered:+ runtime = normalise_known_agent_type(metadata)+ emit_safely(+ self.telemetry,+ "agent_registered",+ {+ "agent_type": agent_type,+ "known_agent_type": runtime,+ "registration_path": registration_path,+ "has_parent": parent_agent_id is not None,+ },+ )+ if self.telemetry is not None:+ await self.telemetry.emit_milestone(+ "first_agent_registered", known_agent_type=runtime+ )await self._create_bridge_identities(tenant_id, name, description)@@ -538,6 +590,7 @@ class ProtocolService:overwrite=overwrite,addressable_by_agent_ids=addressable_by_agent_ids,owner_only=owner_only,+ registration_path="bootstrap",)async def _create_agent(@@ -885,6 +938,15 @@ class ProtocolService:client_id = agent.client_idresolved_id = agent.idresolved_name = agent.name+ # Captured before the row goes: afterwards there is nothing left to+ # describe what was removed, and "an agent was deleted" without its+ # runtime or its age says almost nothing.+ removed: dict[str, str | int | float | bool] = {+ "known_agent_type": normalise_known_agent_type(agent.metadata_),+ "age_days": _age_days(agent.created_at),+ "had_parent": agent.parent_agent_id is not None,+ }+ removed["room_count"] = await self._room_count_for(resolved_id)await self.client_lifecycle.stop(client_id)self.event_buffer.remove(resolved_id)@@ -897,6 +959,29 @@ class ProtocolService:await self.client_lifecycle.remove(client_id)+ emit_safely(self.telemetry, "agent_deleted", removed)++ async def _room_count_for(self, agent_id: str) -> int:+ """How many rooms an agent is in, for reporting only.++ Never raises, and skipped when nothing is listening: this exists to+ label an analytics event, and deleting an agent must not fail because+ a count did.+ """+ if self.telemetry is None:+ return 0+ try:+ async with self.session_factory() as session:+ return len(await self.room_store.get_rooms_for_agent(session, agent_id))+ except Exception:+ logger.warning(+ "Could not count rooms for agent %s while reporting its "+ "deletion; reporting 0.",+ agent_id,+ exc_info=True,+ )+ return 0+# ── Rooms ──────────────────────────────────────────────────────────────────async def get_room(self, room_id: str) -> RoomDescriptor:@@ -2359,6 +2444,7 @@ class ProtocolService:protection_config=security_config,instructions=instructions,created_by=agent.owner_id,+ created_by_kind="agent",owner_id=agent.owner_id,group_id=group_id,read_visibility=read_visibility,@@ -2454,7 +2540,10 @@ class ProtocolService:include_for = [target.id]try:await self.room_service.add_agents_to_room(- room_id, agent_names=[agent_name], include_subagents_for=include_for+ room_id,+ agent_names=[agent_name],+ include_subagents_for=include_for,+ added_by_kind="agent",)except ValueError as e:raise ValueError(f"Failed to invite agent: {str(e)}") from e@@ -3493,8 +3582,11 @@ class ProtocolService:await self.require_room_member(agent_id, room_id)async with self.session_factory() as session:await self._require_room_action(session, agent_id, room_id, "write")- await self.room_store.set_archived(session, room_id, archived)- await session.commit()+ # Through RoomService rather than straight at the store: archiving is+ # reported, and writing the row here instead would make an agent's+ # archive the one kind nothing observes while the snapshot's archived+ # count rose anyway.+ await self.room_service.set_room_archived(room_id, archived)return await self.get_room_detail(agent_id, room_id)async def list_all_agents(self, agent_id: str) -> list[Agent]:diff --git a/core/switch_core/bridges/agent/server_connectors/lifecycle.py b/core/switch_core/bridges/agent/server_connectors/lifecycle.pyindex ce5ad4fbe..5b5200d4a 100644--- a/core/switch_core/bridges/agent/server_connectors/lifecycle.py+++ b/core/switch_core/bridges/agent/server_connectors/lifecycle.py@@ -18,11 +18,25 @@ from switch_core.db.session_scope import tenant_sessionfrom switch_core.db.stores.api_key_store import ApiKeyStorefrom switch_core.db.stores.server_connector_store import ServerConnectorStorefrom switch_core.db.tenant_lookup import all_tenant_ids, tenant_of_server_connector+from switch_core.telemetry import TelemetryService, emit_safelylogger = logging.getLogger(__name__)+def _connector_kind(connector_type: str) -> str:+ """A connector type as the catalogue spells it.++ Registered types are a runtime registry rather than a fixed list, so only+ the one Switch ships is named and anything else reports `other`.+ """+ return connector_type if connector_type == "opencode" else "other"++class ServerSideConnectorLifecycleService:+ # Class-level default, as elsewhere: a test may build this without+ # `__init__`, and `emit_safely` treats None as "report nothing".+ _telemetry: TelemetryService | None = None+def __init__(self,*,@@ -30,12 +44,14 @@ class ServerSideConnectorLifecycleService:api_key_store: ApiKeyStore,protocol: ProtocolService,session_factory: async_sessionmaker[AsyncSession],+ telemetry: TelemetryService | None = None,encryption_secret: str,) -> None:self._connector_store = connector_storeself._api_key_store = api_key_storeself._protocol = protocolself._session_factory = session_factory+ self._telemetry = telemetryself._encryption_secret = encryption_secretself._connector_registry: dict[str, type[ServerSideConnector]] = {}@@ -132,6 +148,12 @@ class ServerSideConnectorLifecycleService:await self.start(record.id)+ emit_safely(+ self._telemetry,+ "server_connector_registered",+ {"connector_kind": _connector_kind(connector_type)},+ )+logger.info("Registered server-side connector %s (%s): %s (owner: %s)",record.id,@@ -228,7 +250,9 @@ class ServerSideConnectorLifecycleService:an error rather than as a second false success."""async with self._session_factory() as session:- if await self._connector_store.get(session, connector_id) is None:+ existing = await self._connector_store.get(session, connector_id)+ kind = existing.type if existing is not None else "other"+ if existing is None:raise ValueError(f"Connector not found: {connector_id}")core = self._cores.get(connector_id)@@ -241,6 +265,11 @@ class ServerSideConnectorLifecycleService:await self._connector_store.delete(session, connector_id)await session.commit()+ emit_safely(+ self._telemetry,+ "server_connector_removed",+ {"connector_kind": _connector_kind(kind)},+ )logger.info("Removed server-side connector %s", connector_id)def get_registered_types(self) -> list[str]:diff --git a/core/switch_core/bridges/collaboration/bridge_core.py b/core/switch_core/bridges/collaboration/bridge_core.pyindex 6f02ad57e..f2dc7774e 100644--- a/core/switch_core/bridges/collaboration/bridge_core.py+++ b/core/switch_core/bridges/collaboration/bridge_core.py@@ -331,6 +331,11 @@ class BridgeCore:def tenant_id(self) -> str:return self._bridge_tenant_id+ @property+ def bridge_type(self) -> str:+ """The collaboration platform this bridge talks to."""+ return self._bridge_type+@contextmanagerdef _counted_outbound(self, kind: str) -> Iterator[None]:"""Count one relay out to the platform, and its failure if it fails.@@ -1024,7 +1029,7 @@ class BridgeCore:logger.debug("Room already exist, add %s to channel", join.agent_name)room_id, _ = existingawait self._room_service.add_agents_to_room(- room_id, agent_names=[join.agent_name]+ room_id, agent_names=[join.agent_name], added_by_kind="system")return@@ -1182,6 +1187,9 @@ class BridgeCore:channel_type=channel_type,bridge_id=self._bridge_id,external_channel_id=channel_id,+ # Adopted from a channel that appeared on the platform, not asked+ # for by anyone in Switch.+ created_by_kind="system",)try:diff --git a/core/switch_core/bridges/collaboration/lifecycle_service.py b/core/switch_core/bridges/collaboration/lifecycle_service.pyindex 490b26e0d..bb68e0d12 100644--- a/core/switch_core/bridges/collaboration/lifecycle_service.py+++ b/core/switch_core/bridges/collaboration/lifecycle_service.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport asyncioimport loggingimport re+from datetime import UTC, datetimefrom typing import TYPE_CHECKINGfrom uuid import uuid4@@ -27,6 +28,13 @@ from switch_core.db.stores.session_request_post_store import SessionRequestPostSfrom switch_core.db.tenant_lookup import all_tenant_ids, tenant_of_collaboration_bridgefrom switch_core.deeplinks import gateway_url_warningfrom switch_core.provisioning import Provisioning+from switch_core.telemetry import TelemetryService, emit_safely+from switch_core.telemetry.deployment import (+ claim_milestone,+ milestone_claimed,+ seconds_since_install,+)+from switch_core.telemetry.snapshot import normalise_platformfrom switch_core.tenant_context import current_tenant_id, no_tenantif TYPE_CHECKING:@@ -36,6 +44,41 @@ if TYPE_CHECKING:logger = logging.getLogger(__name__)+def _failure_reason(exc: BaseException) -> str:+ """An enumerated reason for a bridge failure.++ Not the exception's message, which routinely carries a workspace name or a+ token fragment. Matched on the class name so no adapter has to be imported.+ """+ name = type(exc).__name__.lower()+ if any(word in name for word in ("auth", "unauthorized", "forbidden", "token")):+ return "auth_failed"+ if any(word in name for word in ("timeout", "connection", "socket", "dns")):+ return "network"+ if isinstance(exc, ValueError | KeyError):+ return "config_invalid"+ if any(word in name for word in ("api", "http", "server", "gateway")):+ return "platform_error"+ return "unknown"+++def _age_days(moment: object) -> float:+ """How old a row is, in days, for reporting. Zero if unknown."""+ if not isinstance(moment, datetime):+ return 0.0+ anchored = moment if moment.tzinfo else moment.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - anchored).total_seconds() / 86400.0, 0.0)+++def _seconds_since(moment: object) -> float:+ """Seconds since a timestamp column, or -1 when it is not one — so "could+ not tell" is distinguishable from "just now"."""+ if not isinstance(moment, datetime):+ return -1.0+ anchored = moment if moment.tzinfo else moment.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - anchored).total_seconds(), 0.0)++def _bridge_client_localpart(bridge_type: str, display_name: str) -> str:"""The Matrix localpart for a messaging app's own client.@@ -56,6 +99,12 @@ def _bridge_client_localpart(bridge_type: str, display_name: str) -> str:class CollaborationBridgeLifecycleService:+ # See RoomService: a test may assemble this without `__init__`.+ _telemetry: TelemetryService | None = None+ _connect_failures: dict[str, int] = {}+ _bridge_facts: dict[str, tuple[str, object]] = {}+ _connected: set[str] = set()+def __init__(self,*,@@ -72,6 +121,7 @@ class CollaborationBridgeLifecycleService:session_factory: async_sessionmaker[AsyncSession],config: SwitchConfig,client_factory: ClientFactory,+ telemetry: TelemetryService | None = None,) -> None:self._bridge_store = bridge_storeself._external_user_store = external_user_store@@ -81,6 +131,7 @@ class CollaborationBridgeLifecycleService:self._agent_store = agent_storeself._client_store = client_storeself._client_lifecycle = client_lifecycle+ self._telemetry = telemetryself._room_service = room_serviceself._matrix_admin = matrix_adminself._session_factory = session_factory@@ -91,6 +142,14 @@ class CollaborationBridgeLifecycleService:self._config_registry: dict[str, type[BridgeConnectionConfig]] = {}self._bridges: dict[str, BridgeCore] = {}self._tasks: dict[str, asyncio.Task[None]] = {}+ # How many times each bridge has failed to come up since this+ # process started. See `_note_connect_failure`.+ self._connect_failures: dict[str, int] = {}+ # Read off the row at start, so reporting never depends on what the+ # BridgeCore exposes.+ self._bridge_facts: dict[str, tuple[str, object]] = {}+ # Reached the platform, as opposed to merely started.+ self._connected: set[str] = set()# bridge_id -> the host resource it holds exclusively while running# (see CollaborationAdapter.exclusive_resource). Lets a second# claimant be refused by name instead of failing on the resource.@@ -440,6 +499,15 @@ class CollaborationBridgeLifecycleService:await self._bridge_store.create(session, bridge)await session.commit()+ # Configured, which is not the same as connected — `bridge_connected`+ # says the platform answered. A deployment with many of these and few+ # of those is one whose setup is failing, and only the pair shows it.+ emit_safely(+ self._telemetry,+ "connector_configured",+ {"bridge_platform": normalise_platform(bridge_type)},+ )+await self.start(bridge.id)logger.info(@@ -554,6 +622,9 @@ class CollaborationBridgeLifecycleService:transport_factory=self._client_factory.transport_for,)+ # Stashed rather than passed: `_run_bridge`'s signature is what the+ # tenant-binding tests patch.+ self._bridge_facts[bridge_id] = (bridge.type, bridge.created_at)task = asyncio.create_task(self._run_bridge(bridge_id, tenant_id, bridge_core, bridge_client))@@ -639,14 +710,21 @@ class CollaborationBridgeLifecycleService:which runs until shutdown — binds nothing at all, leaving eachdelivery to bind the tenant of the room it is for."""+ platform, configured_at = self._bridge_facts.get(bridge_id, ("none", None))with no_tenant():+ connected = Falsetry:await self._record_bridge_memberships(bridge_id, tenant_id, bridge_client.client_id)await bridge_core.start()+ # The one point that means "connected": `start()` only+ # launched this task and `bridge_client.start()` never returns.+ connected = True+ self._connected.add(bridge_id)+ await self._report_connector_up(bridge_id, platform, configured_at)await bridge_client.start()- except Exception:+ except Exception as exc:logger.exception("Bridge %s crashed", bridge_id)self._bridges.pop(bridge_id, None)self._tasks.pop(bridge_id, None)@@ -657,15 +735,109 @@ class CollaborationBridgeLifecycleService:endpoint = self._callback_endpoints.pop(bridge_id, None)if endpoint is not None:await endpoint.withdraw()+ # A failure before the adapter came up never connected at all.+ self._connected.discard(bridge_id)+ if connected:+ emit_safely(+ self._telemetry,+ "bridge_disconnected",+ {+ "bridge_platform": normalise_platform(platform),+ "reason": _failure_reason(exc),+ },+ )+ else:+ self._note_connect_failure(bridge_id)+ emit_safely(+ self._telemetry,+ "bridge_connected",+ {+ "bridge_platform": normalise_platform(platform),+ "outcome": "failure",+ "failure_reason": _failure_reason(exc),+ },+ )++ def _note_connect_failure(self, bridge_id: str) -> None:+ """Remember that this bridge failed to come up.++ In memory, so a restart forgets and `failed_attempts_before_success`+ under-reports a connector whose struggles spanned one. Still the only+ signal separating "hard to set up" from "nobody tried it until March".+ """+ self._connect_failures[bridge_id] = self._connect_failures.get(bridge_id, 0) + 1++ async def _report_connector_up(+ self, bridge_id: str, platform: str, configured_at: object+ ) -> None:+ """Report a bridge reaching the platform, and the effort it took.++ `bridge_connected` fires every time, so a flapping bridge shows up.+ `connector_added` fires only on the first ever connect.+ """+ emit_safely(+ self._telemetry,+ "bridge_connected",+ {+ "bridge_platform": normalise_platform(platform),+ "outcome": "success",+ "failure_reason": "none",+ },+ )++ # `enabled`, not just `is not None`: off is a real service with a+ # discarding sink, so testing for None alone spends the claim below on+ # a deployment reporting nothing.+ if self._telemetry is None or not self._telemetry.enabled:+ return+ # The first successful connect for this bridge, ever. Claimed against+ # the bridge id so restarting a working bridge does not re-report a+ # setup that happened months ago.+ if not await claim_milestone(+ self._session_factory, f"connector_added:{bridge_id}"+ ):+ # This bridge has reported, but the deployment-wide milestone may+ # not have. `emit_milestone` is itself once-ever.+ await self._telemetry.emit_milestone(+ "first_connector_added", bridge_platform=normalise_platform(platform)+ )+ return++ elapsed_since_install = seconds_since_install(self._telemetry.installed_at)+ emit_safely(+ self._telemetry,+ "connector_added",+ {+ "bridge_platform": normalise_platform(platform),+ # -1 where the deployment has no install clock, which is+ # distinguishable from "took no time" in a way that 0 is not.+ "seconds_since_install": (+ elapsed_since_install if elapsed_since_install is not None else -1.0+ ),+ "seconds_since_configured": _seconds_since(configured_at),+ "is_first_connector": not self._any_connector_before(bridge_id),+ "failed_attempts_before_success": self._connect_failures.pop(+ bridge_id, 0+ ),+ },+ )+ await self._telemetry.emit_milestone(+ "first_connector_added", bridge_platform=normalise_platform(platform)+ )++ def _any_connector_before(self, bridge_id: str) -> bool:+ """Whether another bridge was already connected when this one came up."""+ return any(other != bridge_id for other in self._bridges)- async def stop(self, bridge_id: str) -> None:+ async def stop(self, bridge_id: str, *, reason: str = "shutdown") -> None:# Before the adapter goes, so a press in flight is answered as gone# rather than handled by a bridge that is halfway shut down.endpoint = self._callback_endpoints.pop(bridge_id, None)if endpoint is not None:await endpoint.withdraw()-bridge_core = self._bridges.get(bridge_id)+ was_connected = bridge_id in self._connected+ self._connected.discard(bridge_id)if bridge_core:await bridge_core.stop()@@ -678,12 +850,25 @@ class CollaborationBridgeLifecycleService:self._started.discard(bridge_id)logger.info("Stopped collaboration bridge %s", bridge_id)+ # `_bridges` membership is set before the connection is attempted, so+ # on its own it would report a bridge that never connected.+ if bridge_core is not None and was_connected:+ platform, _ = self._bridge_facts.get(bridge_id, ("none", None))+ emit_safely(+ self._telemetry,+ "bridge_disconnected",+ {+ "bridge_platform": normalise_platform(platform),+ "reason": reason,+ },+ )+async def restart(self, bridge_id: str) -> None:"""Stop and start a bridge so it picks up its stored config.An adapter is built from the config it was given at start, so an editis inert until the bridge is rebuilt."""- await self.stop(bridge_id)+ await self.stop(bridge_id, reason="restart")await self.start(bridge_id)logger.info("Restarted collaboration bridge %s", bridge_id)@@ -707,10 +892,17 @@ class CollaborationBridgeLifecycleService:external-user rows point at them, so those go first or the foreign keysrefuse."""+ # The durable record, not `self._connected`: that is empty until a+ # connect succeeds *in this process*, so a connector that worked for+ # months and was down at removal would report "never connected".+ was_connected = await milestone_claimed(+ self._session_factory, f"connector_added:{bridge_id}"+ )await self.stop(bridge_id)async with self._session_factory() as session:bridge = await self._bridge_store.get(session, bridge_id)dependent_rooms = await self._room_store.get_by_bridge(session, bridge_id)+ room_count = len(dependent_rooms)if dependent_rooms:logger.warning("Detaching %d room(s) from collaboration bridge %s before removal; "@@ -745,6 +937,23 @@ class CollaborationBridgeLifecycleService:len(removed),)+ if bridge is not None:+ emit_safely(+ self._telemetry,+ "connector_removed",+ {+ "bridge_platform": normalise_platform(bridge.type),+ "age_days": _age_days(bridge.created_at),+ # A connector removed having never connected is a failed+ # setup; one removed after months of service is a+ # decision. Reporting both as "removed" would hide the+ # first, which is the one worth acting on.+ "was_ever_connected": was_connected,+ "room_count": room_count,+ },+ )+ self._bridge_facts.pop(bridge_id, None)+def get(self, bridge_id: str) -> BridgeCore | None:return self._bridges.get(bridge_id)diff --git a/core/switch_core/bridges/resource/service.py b/core/switch_core/bridges/resource/service.pyindex 3b685466f..f548c8416 100644--- a/core/switch_core/bridges/resource/service.py+++ b/core/switch_core/bridges/resource/service.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport loggingimport refrom dataclasses import dataclass+from datetime import UTC, datetimefrom typing import Any, Literalfrom sqlalchemy import select@@ -35,9 +36,33 @@ from switch_core.db.stores.package_store import PackageStorefrom switch_core.db.stores.reference_store import ReferenceStorefrom switch_core.db.stores.reference_type_store import ReferenceTypeStorefrom switch_core.db.stores.room_link_store import RoomLinkStore+from switch_core.telemetry import TelemetryService, emit_safelylogger = logging.getLogger(__name__)++def _reference_type(type_: str) -> str:+ """A reference type as the telemetry catalogue spells it.++ Only the builtins are named. A user-defined type's slug is free text+ chosen by whoever registered it, so it can never go on the wire — what is+ reportable is that it was not one of ours.+ """+ return type_ if is_builtin_type(type_) else "other"+++def _visibility(value: str) -> str:+ return value if value in ("private", "public") else "private"+++def _age_days(created_at: object) -> float:+ """How old a row is, in days, for reporting. Zero if unknown."""+ if not isinstance(created_at, datetime):+ return 0.0+ moment = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - moment).total_seconds() / 86400.0, 0.0)++ROOM_DOCUMENT_MAX_CONTENT_BYTES = 1_048_576REFERENCE_TYPE_SLUG_PATTERN = re.compile(r"^[a-z][a-z0-9_]{1,62}$")@@ -74,6 +99,10 @@ class ReferenceTypeRow:class ResourceService:+ # Class-level default: several tests build this without `__init__`, and+ # `emit_safely` treats None as "report nothing".+ _telemetry: TelemetryService | None = None+"""Business logic for References, Documents, and Packages.Used by:@@ -91,7 +120,9 @@ class ResourceService:package_store: PackageStore,room_link_store: RoomLinkStore,session_factory: async_sessionmaker[AsyncSession],+ telemetry: TelemetryService | None = None,) -> None:+ self._telemetry = telemetryself._references = reference_storeself._reference_types = reference_type_storeself._documents = document_store@@ -317,7 +348,12 @@ class ResourceService:instructions=instructions,value_hint=value_hint,)- return await self._reference_types.create(session, reference_type)+ created = await self._reference_types.create(session, reference_type)+ # No slug: the type's name is free text whoever registered it chose,+ # and that is exactly what a user-defined type is — the fact that one+ # was registered is the whole reportable content.+ emit_safely(self._telemetry, "reference_type_created", {})+ return createdasync def update_reference_type(self,@@ -377,7 +413,9 @@ class ResourceService:f"Reference type '{type_}' is used by {in_use} reference(s) ""and cannot be deleted")+ age = _age_days(reference_type.created_at)await self._reference_types.delete(session, type_)+ emit_safely(self._telemetry, "reference_type_deleted", {"age_days": age})async def log_builtin_shadowing(self, session: AsyncSession) -> None:"""Report every stored type a built-in shadows.@@ -509,7 +547,17 @@ class ResourceService:instructions=instructions,value=normalised_value,)- return await self._references.create(session, ref)+ created = await self._references.create(session, ref)+ emit_safely(+ self._telemetry,+ "reference_created",+ {+ "reference_type": _reference_type(type),+ "read_visibility": _visibility(read_visibility),+ "created_by_kind": "user",+ },+ )+ return createdasync def get_reference_for_user(self,@@ -606,7 +654,14 @@ class ResourceService:if ref is None:raise ValueError(f"Reference not found: {reference_id}")require(Principal(user_id, is_admin), "delete", ref)- return await self._references.delete(session, reference_id)+ kind, age = _reference_type(ref.type), _age_days(ref.created_at)+ detached = await self._references.delete(session, reference_id)+ emit_safely(+ self._telemetry,+ "reference_deleted",+ {"reference_type": kind, "age_days": age},+ )+ return detachedasync def attach_reference_to_room(self,@@ -622,11 +677,22 @@ class ResourceService:raise ValueError(f"Reference not found: {reference_id}")require(Principal(user_id, is_admin), "read", ref)await self._references.attach_to_room(session, room_id, reference_id)+ emit_safely(+ self._telemetry,+ "reference_attached_to_room",+ {"reference_type": _reference_type(ref.type)},+ )async def detach_reference_from_room(self, session: AsyncSession, room_id: str, reference_id: str) -> None:+ ref = await self._references.get(session, reference_id)await self._references.detach_from_room(session, room_id, reference_id)+ emit_safely(+ self._telemetry,+ "reference_detached_from_room",+ {"reference_type": _reference_type(ref.type) if ref else "other"},+ )async def list_room_references(self, session: AsyncSession, room_id: str@@ -735,6 +801,9 @@ class ResourceService:if await self._room_links.exists(session, source_room_id, target_room_id):raise ValueError(f"Room {source_room_id} already links to {target_room_id}")await self._room_links.attach(session, source_room_id, target_room_id, label)+ # No label: it is free text describing why two rooms relate, which is+ # exactly the kind of thing that names a customer's work.+ emit_safely(self._telemetry, "room_link_created", {})return {"target_room_id": target.id,"target_room_name": target.name,@@ -749,7 +818,11 @@ class ResourceService:source_room_id: str,target_room_id: str,) -> bool:- return await self._room_links.detach(session, source_room_id, target_room_id)+ detached = await self._room_links.detach(+ session, source_room_id, target_room_id+ )+ emit_safely(self._telemetry, "room_link_removed", {})+ return detached# ── Document CRUD (gateway) ───────────────────────────────────────────@@ -775,7 +848,17 @@ class ResourceService:instructions=instructions,content=content,)- return await self._documents.create(session, doc)+ created = await self._documents.create(session, doc)+ emit_safely(+ self._telemetry,+ "document_created",+ {+ "scope": "library",+ "created_by_kind": "user",+ "has_instructions": bool(instructions),+ },+ )+ return createdasync def get_document_for_user(self,@@ -841,7 +924,14 @@ class ResourceService:if doc is None:raise ValueError(f"Document not found: {document_id}")require(Principal(user_id, is_admin), "delete", doc)- return await self._documents.delete(session, document_id)+ age = _age_days(doc.created_at)+ detached = await self._documents.delete(session, document_id)+ emit_safely(+ self._telemetry,+ "document_deleted",+ {"scope": "library", "age_days": age},+ )+ return detachedasync def attach_document_to_room(self,@@ -862,11 +952,13 @@ class ResourceService:)require(Principal(user_id, is_admin), "read", doc)await self._documents.attach_to_room(session, room_id, document_id)+ emit_safely(self._telemetry, "document_attached_to_room", {})async def detach_document_from_room(self, session: AsyncSession, room_id: str, document_id: str) -> None:await self._documents.detach_from_room(session, room_id, document_id)+ emit_safely(self._telemetry, "document_detached_from_room", {})async def list_room_documents(self, session: AsyncSession, room_id: str@@ -919,7 +1011,17 @@ class ResourceService:instructions=instructions,content=content,)- return await self._documents.create(session, doc)+ created = await self._documents.create(session, doc)+ emit_safely(+ self._telemetry,+ "document_created",+ {+ "scope": "room",+ "created_by_kind": "agent",+ "has_instructions": bool(instructions),+ },+ )+ return createdasync def create_room_document_for_user(self,@@ -955,7 +1057,17 @@ class ResourceService:instructions=instructions,content=content,)- return await self._documents.create(session, doc)+ created = await self._documents.create(session, doc)+ emit_safely(+ self._telemetry,+ "document_created",+ {+ "scope": "room",+ "created_by_kind": "user",+ "has_instructions": bool(instructions),+ },+ )+ return createdasync def update_room_document(self,@@ -1095,7 +1207,9 @@ class ResourceService:description=description,instructions=instructions,)- return await self._packages.create(session, pkg)+ created = await self._packages.create(session, pkg)+ emit_safely(self._telemetry, "package_created", {"created_by_kind": "user"})+ return createdasync def get_package_for_user(self,@@ -1159,7 +1273,10 @@ class ResourceService:if pkg is None:raise ValueError(f"Package not found: {package_id}")require(Principal(user_id, is_admin), "delete", pkg)- return await self._packages.delete(session, package_id)+ age = _age_days(pkg.created_at)+ detached = await self._packages.delete(session, package_id)+ emit_safely(self._telemetry, "package_deleted", {"age_days": age})+ return detachedasync def attach_package_to_room(self,@@ -1175,11 +1292,26 @@ class ResourceService:raise ValueError(f"Package not found: {package_id}")require(Principal(user_id, is_admin), "read", pkg)await self._packages.attach_to_room(session, room_id, package_id)+ # What the package brought with it, which is the whole point of+ # attaching one rather than its parts.+ emit_safely(+ self._telemetry,+ "package_attached_to_room",+ {+ "reference_count": (+ await self._packages.get_reference_counts(session, [package_id])+ ).get(package_id, 0),+ "document_count": (+ await self._packages.get_document_counts(session, [package_id])+ ).get(package_id, 0),+ },+ )async def detach_package_from_room(self, session: AsyncSession, room_id: str, package_id: str) -> None:await self._packages.detach_from_room(session, room_id, package_id)+ emit_safely(self._telemetry, "package_detached_from_room", {})async def list_room_packages(self, session: AsyncSession, room_id: strdiff --git a/core/switch_core/config.py b/core/switch_core/config.pyindex e56b0cc2a..5c731ce95 100644--- a/core/switch_core/config.py+++ b/core/switch_core/config.py@@ -190,8 +190,49 @@ class SwitchConfig(BaseSettings):# a 200 — a deployment that omitted it would look configured and appear in# no dashboard. Not generated per process: a fresh id each restart makes# one deployment look like an endless population of installs.+ #+ # Both streams use this value, so a deployment reporting metrics and usage+ # is one subject downstream. Product telemetry falls back to an id in the+ # database, which also carries the install date no env var can supply.deployment_id: str | None = None+ # ── Product telemetry ────────────────────────────────────────────────────+ # Usage reporting, separate from the operational export above and+ # deliberately so. That one names *a collector* — often the customer's own+ # — and carries how the server is behaving. This one carries how the+ # product is being used, and goes to the analytics relay. A self-hosted+ # deployment pointing its metrics at its own Datadog must not thereby send+ # its usage analytics there too, and Flint must not receive a customer's+ # operational metrics. Same wire format, same client, two destinations.+ #+ # **Off unless switched on, and that default is deliberate.** A Switch+ # server may be a customer's, and the usage may be theirs, so reporting it+ # is a decision an operator makes rather than one they discover. When this+ # is false nothing is collected and no request is made.+ #+ # What is reported is fixed in `telemetry/catalogue.py` and explained in+ # `docs/old/telemetry-events.md`: counts and durations only, never an+ # identifier for a room, tenant, agent, user or message, and never free+ # text. The catalogue is enforced at the boundary rather than trusted.+ telemetry_enabled: bool = False++ # Base URL of the relay, no path — `/v1/logs` is appended, the same+ # convention `otlp_endpoint` above follows. Defaults to the company relay,+ # which is where Switch Console already reports, so one pipeline carries+ # both. Override to point a development run at a local sink.+ telemetry_endpoint: str = "https://telemetry.flintai.dev"++ # How long to wait on the relay before giving up on a single event.+ # Telemetry is never worth delaying real work for, and a send that is+ # already this late is not worth finishing.+ telemetry_timeout_seconds: float = 10.0++ # How often the daily usage snapshot is collected and sent. Hours rather+ # than a fixed clock time so a deployment does not have to care which+ # timezone it is in; the schedule is anchored to what was last sent, not+ # to how long this process has been up.+ telemetry_snapshot_interval_hours: float = 24.0+server_host: str = "0.0.0.0"server_port: int = 8000@@ -383,12 +424,94 @@ class SwitchConfig(BaseSettings):)if not self.tenant_id.strip():raise ValueError("TENANT_ID must not be empty.")+ # Checked whether or not telemetry is on, unlike the endpoint and the+ # timeout below: 0 is a plausible reading of "disable the snapshot" and+ # would instead mean "never not due", running the whole fan-out every+ # poll. A setting whose wrong value is a busy loop is worth refusing+ # even on a deployment that is not using it yet.+ if self.telemetry_snapshot_interval_hours <= 0:+ raise ValueError(+ "TELEMETRY_SNAPSHOT_INTERVAL_HOURS must be positive, got "+ f"{self.telemetry_snapshot_interval_hours!r}. Set "+ "TELEMETRY_ENABLED=false to switch reporting off."+ )+ if self.telemetry_enabled:+ # Checked only when telemetry is on: a deployment that never+ # reports should not be refused boot over the shape of a setting+ # it does not use.+ # The same checks `_validate_observability` applies to+ # OTLP_ENDPOINT, and for the same reasons: both are base URLs with+ # the signal path appended, and the relay answers a misdirected+ # post with a 404 that is logged once per event and read by nobody.+ if self.telemetry_endpoint != self.telemetry_endpoint.strip():+ raise ValueError(+ "TELEMETRY_ENDPOINT has leading or trailing whitespace: "+ f"{self.telemetry_endpoint!r}."+ )+ endpoint = urlsplit(self.telemetry_endpoint)+ if endpoint.scheme not in ("http", "https"):+ raise ValueError(+ "TELEMETRY_ENDPOINT must be an http(s) URL, got "+ f"{self.telemetry_endpoint!r}."+ )+ if not endpoint.netloc:+ raise ValueError(+ "TELEMETRY_ENDPOINT must include a host, got "+ f"{self.telemetry_endpoint!r}."+ )+ if endpoint.path.strip("/"):+ # `/v1/logs` is appended, so a value already carrying it posts+ # to `/v1/logs/v1/logs`. The full logs URL is the form most+ # people have seen written down, which makes pasting it here+ # the obvious mistake rather than an unlikely one.+ raise ValueError(+ "TELEMETRY_ENDPOINT is the relay's base URL and the signal "+ "path is appended to it, so it must have no path of its "+ f"own. Got {self.telemetry_endpoint!r} — drop the "+ f"{endpoint.path!r}."+ )+ if endpoint.query or endpoint.fragment:+ raise ValueError(+ "TELEMETRY_ENDPOINT must be a bare base URL: a query or "+ "fragment is dropped when the signal path is appended, so "+ "it would silently never be sent. Got "+ f"{self.telemetry_endpoint!r}."+ )+ if self.telemetry_timeout_seconds <= 0:+ raise ValueError(+ "TELEMETRY_TIMEOUT_SECONDS must be positive, got "+ f"{self.telemetry_timeout_seconds!r}."+ )+if self.template_max_bytes < 1:raise ValueError(f"TEMPLATE_MAX_BYTES must be at least 1, got {self.template_max_bytes}.")return self+ @model_validator(mode="after")+ def _validate_deployment_id(self) -> "SwitchConfig":+ """The id's shape, checked wherever it is set.++ Separate from `_validate_observability` because both streams now use+ this value: product telemetry prefers it over the id generated into the+ database, so a malformed one reaches the relay on a deployment that has+ named no collector at all and would never run that validator. The relay+ requires a canonical UUID and drops what arrives without one — with a+ 200, in silence — so the wrong shape here is not a degraded send, it is+ no send at all.+ """+ if self.deployment_id is None:+ return self+ try:+ uuid.UUID(self.deployment_id)+ except ValueError as error:+ raise ValueError(+ f"DEPLOYMENT_ID must be a UUID, got {self.deployment_id!r}. "+ "The relay's guard rejects anything else, silently."+ ) from error+ return self+@model_validator(mode="after")def _validate_observability(self) -> "SwitchConfig":if self.otlp_endpoint is None:@@ -436,14 +559,6 @@ class SwitchConfig(BaseSettings):"does so silently, so without one this server would report ""nothing while looking correctly configured.")- try:- uuid.UUID(self.deployment_id)- except ValueError as error:- raise ValueError(- f"DEPLOYMENT_ID must be a UUID, got {self.deployment_id!r}. "- "The collector's guard rejects anything else."- ) from error-for name, value in (("OTLP_TIMEOUT_SECONDS", self.otlp_timeout_seconds),("OTLP_EXPORT_INTERVAL_SECONDS", self.otlp_export_interval_seconds),diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.pyindex 3059836bd..25d536cef 100644--- a/core/switch_core/db/models.py+++ b/core/switch_core/db/models.py@@ -1825,6 +1825,71 @@ class SessionRequestPost(TenantScoped, Base):)+# ── Telemetry bookkeeping ────────────────────────────────────────────────────+++class DeploymentIdentity(Base):+ """Who this installation is to the telemetry relay, and when it began.++ Not tenant-scoped: a deployment running several tenants is one subject.+ Exactly one row, pinned by a check constraint — two would silently double+ every count derived from it.++ `client_id` is a random UUID, derived from nothing, kept across restarts.++ `installed_at` is null where the identity was created against a database+ that already held content; milestones are suppressed for such a deployment+ rather than measured from a guess. The daily counts are unaffected.+ """++ __tablename__ = "deployment_identity"+ __table_args__ = (+ CheckConstraint("id = 1", name="ck_deployment_identity_singleton"),+ )++ id: Mapped[int] = mapped_column(Integer, primary_key=True, default=1)+ client_id: Mapped[str] = mapped_column(Text, nullable=False, default=_uuid)+ installed_at: Mapped[datetime | None] = mapped_column(+ DateTime(timezone=True), nullable=True+ )+ created_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), nullable=False+ )+++class TelemetryMilestone(Base):+ """A once-ever telemetry event that has already been reported.++ A row rather than process state, so a restart cannot re-emit one. The name+ is the primary key, which makes the insert itself the guard.+ """++ __tablename__ = "telemetry_milestones"++ name: Mapped[str] = mapped_column(Text, primary_key=True)+ emitted_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), nullable=False+ )+++class TelemetrySnapshotWatermark(Base):+ """When the daily usage snapshot was last sent.++ Anchored to what was sent rather than to uptime, so restarts do not change+ the cadence. One row, pinned like the identity above.+ """++ __tablename__ = "telemetry_snapshot_watermark"+ __table_args__ = (+ CheckConstraint("id = 1", name="ck_telemetry_snapshot_watermark_singleton"),+ )++ id: Mapped[int] = mapped_column(Integer, primary_key=True, default=1)+ last_sent_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), nullable=False+ )++# ── Feature flags ────────────────────────────────────────────────────────────@@ -1876,6 +1941,10 @@ class Message(TenantScoped, Base):# is what a caller asking for a time window filters by, so it needs an# index of its own rather than a scan back along seq.Index("ix_messages_room_sent_at", "room_id", "sent_at"),+ # The usage snapshot's shape: one tenant's messages since a moment,+ # across every room. The index above leads on the room, so it cannot+ # serve that and each pass would scan the whole table.+ Index("ix_messages_tenant_sent_at", "tenant_id", "sent_at"),Index("ix_messages_thread_root","room_id",diff --git a/core/switch_core/db/rls_ddl.py b/core/switch_core/db/rls_ddl.pyindex fb433b245..d2667b52f 100644--- a/core/switch_core/db/rls_ddl.py+++ b/core/switch_core/db/rls_ddl.py@@ -118,7 +118,25 @@ POLICY_NAME = "tenant_isolation"# switch, and a flag that needs to vary per customer is a new scoped table# rather than a nullable column here. Alembic's `alembic_version` needs no# entry: Alembic owns that table and never registers it on this metadata.-GLOBAL_TABLES = frozenset({"users", "oidc_identities", "feature_flags"})+#+# The three telemetry tables are global because each records a fact about the+# *installation* rather than about anything inside it: which deployment this+# is to the analytics relay, when it was installed, which once-ever milestones+# it has already reported, and when its last usage snapshot went out. None+# holds customer data — that is the whole design of the telemetry catalogue,+# which reports counts and never an identifier — and scoping them would be+# incoherent: a deployment running three tenants has one identity, not three,+# and a milestone reported once per tenant would not be once-ever at all.+GLOBAL_TABLES = frozenset(+ {+ "users",+ "oidc_identities",+ "feature_flags",+ "deployment_identity",+ "telemetry_milestones",+ "telemetry_snapshot_watermark",+ }+)class UnscopedTableError(RuntimeError):diff --git a/core/switch_core/gateway/agents.py b/core/switch_core/gateway/agents.pyindex a2033b826..3c22733f8 100644--- a/core/switch_core/gateway/agents.py+++ b/core/switch_core/gateway/agents.py@@ -168,6 +168,7 @@ async def register_known_agent(try:result = await protocol.register_agent(+ registration_path="gateway",name=req.name,description=req.description,icon_url=req.icon_url,@@ -490,6 +491,7 @@ async def register_other_agent(try:result = await protocol.register_agent(+ registration_path="gateway",name=req.name,description=req.description,icon_url=req.icon_url,diff --git a/core/switch_core/gateway/api_keys.py b/core/switch_core/gateway/api_keys.pyindex abddc989e..d95825f1e 100644--- a/core/switch_core/gateway/api_keys.py+++ b/core/switch_core/gateway/api_keys.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport hashlibimport loggingimport secrets+from datetime import UTC, datetimefrom typing import Annotatedfrom fastapi import APIRouter, Depends, HTTPException@@ -14,6 +15,7 @@ from switch_core.db.models import ApiKey, Userfrom switch_core.db.stores.api_key_store import ApiKeyStorefrom switch_core.gateway.auth import get_current_userfrom switch_core.gateway.dependencies import (+ current_telemetry,get_api_key_store,get_config,get_protocol,@@ -25,9 +27,27 @@ from switch_core.gateway.schemas import (CreateApiKeyResponse,RevealKeyResponse,)+from switch_core.telemetry import emit_safelylogger = logging.getLogger(__name__)++def _key_type(value: str) -> str:+ """A key's type as the catalogue spells it.++ The label an operator gave the key never goes anywhere near this — only+ what the key is *for*, which is a fixed set the code chooses.+ """+ return value if value in ("agent", "registration", "bootstrap") else "other"+++def _age_days(created_at: object) -> float:+ if not isinstance(created_at, datetime):+ return 0.0+ moment = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - moment).total_seconds() / 86400.0, 0.0)++router = APIRouter()@@ -72,6 +92,9 @@ async def create_api_key(await session.commit()logger.info("Created API key '%s' for user %s", req.label, user.email)+ emit_safely(+ current_telemetry(), "api_key_created", {"key_type": _key_type(key.type)}+ )return CreateApiKeyResponse(id=key.id,label=key.label,@@ -116,4 +139,9 @@ async def delete_api_key(get_protocol().api_key_cache.invalidate(key_hash)logger.info("Deleted API key '%s' for user %s", key.label, user.email)+ emit_safely(+ current_telemetry(),+ "api_key_revoked",+ {"key_type": _key_type(key.type), "age_days": _age_days(key.created_at)},+ )return {"ok": True}diff --git a/core/switch_core/gateway/dependencies.py b/core/switch_core/gateway/dependencies.pyindex 5358de849..d9265fa2d 100644--- a/core/switch_core/gateway/dependencies.py+++ b/core/switch_core/gateway/dependencies.py@@ -32,6 +32,7 @@ from switch_core.db.stores.template_store import TemplateStorefrom switch_core.db.stores.user_store import UserStorefrom switch_core.room_service import RoomServicefrom switch_core.rooms_yaml import RoomYamlService+from switch_core.telemetry import TelemetryService_state: dict[str, Any] = {}@@ -221,6 +222,19 @@ def get_protocol() -> ProtocolService:return _state["protocol"] # type: ignore[no-any-return]+def current_telemetry() -> TelemetryService | None:+ """The telemetry service, or None where there is nothing wired.++ Reporting from a gateway route needs the service the app was built with,+ and `get_protocol()` raises when nothing has been initialised — which is+ the ordinary state in a route test. An analytics call must never be the+ reason a request fails, and it must never be the reason a test needs a+ protocol service it otherwise has no use for.+ """+ protocol = _state.get("protocol")+ return getattr(protocol, "telemetry", None) if protocol is not None else None++def get_install_store() -> MessagingInstallStore:"""Built here rather than threaded through `init_dependencies`.diff --git a/core/switch_core/gateway/room_groups.py b/core/switch_core/gateway/room_groups.pyindex dca17f78d..89ebd59e0 100644--- a/core/switch_core/gateway/room_groups.py+++ b/core/switch_core/gateway/room_groups.py@@ -1,5 +1,6 @@from __future__ import annotations+from datetime import UTC, datetimefrom typing import Annotatedfrom fastapi import APIRouter, Depends, HTTPException, Response@@ -11,6 +12,7 @@ from switch_core.db.stores.room_group_store import RoomGroupStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.gateway.auth import get_current_user, get_tenant_is_adminfrom switch_core.gateway.dependencies import (+ current_telemetry,get_room_group_store,get_room_store,get_session,@@ -22,6 +24,15 @@ from switch_core.gateway.schemas import (RoomGroupDetail,RoomGroupUpdateRequest,)+from switch_core.telemetry import emit_safely+++def _age_days(created_at: object) -> float:+ if not isinstance(created_at, datetime):+ return 0.0+ moment = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - moment).total_seconds() / 86400.0, 0.0)+router = APIRouter()@@ -67,6 +78,11 @@ async def create_room_group(except ValueError as e:raise HTTPException(status_code=400, detail=str(e)) from eawait session.commit()+ emit_safely(+ current_telemetry(),+ "room_group_created",+ {"has_parent": req.parent_group_id is not None},+ )return _to_detail(group, 0)@@ -148,8 +164,20 @@ async def delete_room_group(room_group_store: Annotated[RoomGroupStore, Depends(get_room_group_store)],_user: Annotated[User, Depends(get_current_user)],) -> Response:+ # Read before the delete: afterwards there is nothing left to say how much+ # was filed under it, which is the difference between tidying up an empty+ # group and dismantling a working one.+ group = await room_group_store.get(session, group_id)+ room_count = (await room_group_store.get_room_counts(session)).get(group_id, 0)+ age = _age_days(group.created_at) if group else 0.0+removed = await room_group_store.delete(session, group_id)if not removed:raise HTTPException(status_code=404, detail="Room group not found")await session.commit()+ emit_safely(+ current_telemetry(),+ "room_group_deleted",+ {"room_count": room_count, "age_days": age},+ )return Response(status_code=204)diff --git a/core/switch_core/gateway/rooms.py b/core/switch_core/gateway/rooms.pyindex 9486be951..cca27956f 100644--- a/core/switch_core/gateway/rooms.py+++ b/core/switch_core/gateway/rooms.py@@ -21,6 +21,7 @@ from switch_core.db.stores.room_store import RoomStorefrom switch_core.db.stores.user_store import UserStorefrom switch_core.gateway.auth import get_current_user, get_tenant_is_adminfrom switch_core.gateway.dependencies import (+ current_telemetry,get_bridge_store,get_collab_lifecycle,get_external_user_store,@@ -53,6 +54,7 @@ from switch_core.gateway.schemas import ()from switch_core.room_service import RoleSpec, RoomCreateConfig, RoomServicefrom switch_core.rooms_yaml import ProvisionResult, RoomYamlService, TemplateDocument+from switch_core.telemetry import emit_safelylogger = logging.getLogger(__name__)@@ -539,6 +541,9 @@ async def create_room_role() -> list[RoomRoleDetail]:await _require_room(session, room_store, room_id, user, "write", is_admin)try:+ emit_safely(+ current_telemetry(), "room_role_defined", {"exclusive": req.exclusive}+ )await protocol.room_role_store.define_role(session, room_id, req.name, req.instructions, req.exclusive)@@ -583,6 +588,7 @@ async def delete_room_role(await _require_room(session, room_store, room_id, user, "write", is_admin)try:await protocol.room_role_store.delete_role(session, room_id, name)+ emit_safely(current_telemetry(), "room_role_deleted", {})except ValueError as e:raise HTTPException(status_code=404, detail=str(e))await session.commit()diff --git a/core/switch_core/gateway/templates.py b/core/switch_core/gateway/templates.pyindex 44f9034b4..b1505708f 100644--- a/core/switch_core/gateway/templates.py+++ b/core/switch_core/gateway/templates.py@@ -14,6 +14,7 @@ already answered — agreeing right up until the day it did not.from __future__ import annotationsimport re+from datetime import UTC, datetimefrom typing import Annotatedfrom urllib.parse import quote@@ -31,6 +32,7 @@ from switch_core.db.stores.template_store import (from switch_core.db.stores.user_store import UserStorefrom switch_core.gateway.auth import get_current_user, get_tenant_is_adminfrom switch_core.gateway.dependencies import (+ current_telemetry,get_config,get_session,get_template_store,@@ -46,8 +48,26 @@ from switch_core.gateway.schemas import (TemplateValidateRequest,TemplateValidateResponse,)+from switch_core.telemetry import emit_safelyfrom switch_core.template_lint import lint_template++def _kind(value: str | None) -> str:+ """A template's kind as the catalogue spells it.++ The column is free text, so only the three the product uses are named and+ an operator's own kind reports as `other`.+ """+ return value if value in ("room", "group", "agent") else "other"+++def _age_days(created_at: object) -> float:+ if not isinstance(created_at, datetime):+ return 0.0+ moment = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - moment).total_seconds() / 86400.0, 0.0)++router = APIRouter()@@ -218,6 +238,12 @@ async def create_template(except TemplateNameTaken as e:raise HTTPException(status_code=409, detail=str(e)) from eawait session.commit()+ # What the template provisions, not what it is called. A template that+ # brings rooms and agents with it is a different thing from one that+ # carries neither, and that shape is reportable where the name is not.+ emit_safely(+ current_telemetry(), "template_created", {"template_kind": _kind(req.kind)}+ )return _detail(template, await _owner_name(session, user_store, user.id))@@ -343,10 +369,18 @@ async def delete_template(user: Annotated[User, Depends(get_current_user)],is_admin: Annotated[bool, Depends(get_tenant_is_admin)],) -> TemplateDeleteResponse:- await _load_for_management(session, template_store, template_id, user, is_admin)+ template = await _load_for_management(+ session, template_store, template_id, user, is_admin+ )+ kind, age = _kind(template.kind), _age_days(template.created_at)try:await template_store.delete(session, template_id)except ValueError as e:raise HTTPException(status_code=404, detail=str(e)) from eawait session.commit()+ emit_safely(+ current_telemetry(),+ "template_deleted",+ {"template_kind": kind, "age_days": age},+ )return TemplateDeleteResponse(deleted_id=template_id)diff --git a/core/switch_core/gateway/tenants.py b/core/switch_core/gateway/tenants.pyindex 45f84901c..ed30787a2 100644--- a/core/switch_core/gateway/tenants.py+++ b/core/switch_core/gateway/tenants.py@@ -36,6 +36,7 @@ from switch_core.gateway.auth import ()from switch_core.gateway.auth_routes import _session_responsefrom switch_core.gateway.dependencies import (+ current_telemetry,get_agent_store,get_api_key_store,get_client_lifecycle,@@ -58,10 +59,25 @@ from switch_core.gateway.schemas import (TenantCreateRequest,TenantMembershipResponse,)+from switch_core.telemetry import emit_safelyfrom switch_core.tenant_context import current_tenant_idlogger = logging.getLogger(__name__)++def _age_hours(created_at: object) -> float:+ """How long an invitation sat before it was accepted. Zero if unknown.++ Hours rather than days: the interesting range is "immediately" to "a+ couple of days", and a figure that reads 0.1 for most of it says less than+ one that reads 2.4.+ """+ if not isinstance(created_at, datetime):+ return 0.0+ moment = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - moment).total_seconds() / 3600.0, 0.0)++router = APIRouter()TENANT_MEMBER_ROLES = ("owner", "admin", "member")@@ -325,6 +341,7 @@ async def create_invitation(created_by=user.id,)await session.commit()+ emit_safely(current_telemetry(), "invitation_sent", {})return InvitationCreateResponse(token=token, **_invitation_fields(invitation))@@ -416,6 +433,15 @@ async def accept_invitation(await user_store.add_membership(session, tenant_id=tenant_id, user_id=caller.id, role=role)+ # Only on the branch that actually joined someone. A caller who+ # was already a member takes the `else` below and has accepted+ # nothing — reporting it there would count re-clicking a link as+ # onboarding.+ emit_safely(+ current_telemetry(),+ "invitation_accepted",+ {"age_hours": _age_hours(invitation.created_at)},+ )else:role = existing_rolediff --git a/core/switch_core/main.py b/core/switch_core/main.pyindex abc7fac56..8a24ae5ee 100644--- a/core/switch_core/main.py+++ b/core/switch_core/main.py@@ -10,6 +10,7 @@ from collections.abc import AsyncIteratorfrom contextlib import asynccontextmanagerfrom pathlib import Path+import httpximport uvicornfrom alembic import command as alembic_commandfrom alembic.config import Config as AlembicConfig@@ -136,6 +137,9 @@ from switch_core.observability.runtime import EventLoopLagfrom switch_core.provisioning import Provisioningfrom switch_core.provisioning.postgres import PostgresProvisioningfrom switch_core.room_service import RoomService+from switch_core.telemetry.reporter import SnapshotReporter+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.setup import build_telemetryfrom switch_core.tenant_context import no_tenantfrom switch_core.transport.ephemeral import EphemeralBusfrom switch_core.transport.invites import InviteBus@@ -214,6 +218,46 @@ async def _connection_sweep_loop(protocol: ProtocolService, lag: EventLoopLag) -logger.exception("Connection sweep failed")+# The innermost of three nested budgets: under+# `observability.logs.SHUTDOWN_FLUSH_SECONDS`, itself under+# `_FORCED_EXIT_GRACE_SECONDS`.+_TELEMETRY_DRAIN_SECONDS = 1.0+++async def _drain_telemetry(+ telemetry: TelemetryService, http_client: httpx.AsyncClient | None+) -> None:+ """Let in-flight product events finish, then close their client.++ Never raises and never overruns: a relay that stopped answering must not+ hold the process past the point where it is killed.+ """+ try:+ async with asyncio.timeout(_TELEMETRY_DRAIN_SECONDS):+ await telemetry.aclose()+ except TimeoutError:+ logger.warning(+ "Gave up waiting for in-flight telemetry after %.1fs; those events "+ "are lost.",+ _TELEMETRY_DRAIN_SECONDS,+ )+ except Exception:+ logger.warning("Telemetry shutdown failed; continuing.", exc_info=True)+ if http_client is not None:+ try:+ await http_client.aclose()+ except Exception:+ logger.warning("Telemetry HTTP client did not close.", exc_info=True)+++async def _snapshot_loop(reporter: SnapshotReporter) -> None:+ # `no_tenant` for the reason every other long-lived task does it: the+ # snapshot binds each tenant in turn as it counts, and must not inherit+ # whichever one happened to be bound when the task was created.+ with no_tenant():+ await reporter.run_forever()++class _QuietPollFilter(logging.Filter):_SUPPRESSED = ["/events?timeout=",@@ -342,6 +386,12 @@ async def run(config: SwitchConfig) -> None:event_buffer = EventBuffer()connector_store = ServerConnectorStore()+ # ── Product telemetry ────────────────────────────────────────────────────+ # Before the services that report through it, switched on or not.+ telemetry, installed_at, telemetry_http = await build_telemetry(+ config, session_factory, switch_core_version()+ )+# ── Resource service ─────────────────────────────────────────────────────resource_service = ResourceService(reference_store=reference_store,@@ -350,6 +400,7 @@ async def run(config: SwitchConfig) -> None:package_store=package_store,room_link_store=room_link_store,session_factory=session_factory,+ telemetry=telemetry,)# Once per tenant, not once for the deployment: `reference_types` is# scoped, so "every stored type a built-in shadows" is a question asked of@@ -441,6 +492,7 @@ async def run(config: SwitchConfig) -> None:session_factory=session_factory,config=config,client_factory=client_factory,+ telemetry=telemetry,)# ── Room service ─────────────────────────────────────────────────────────@@ -453,6 +505,7 @@ async def run(config: SwitchConfig) -> None:collab_bridge_store=bridge_store,resource_service=resource_service,session_factory=session_factory,+ telemetry=telemetry,)collab_lifecycle._room_service = room_service@@ -490,7 +543,12 @@ async def run(config: SwitchConfig) -> None:session_factory=session_factory,config=config,connections=connections,+ telemetry=telemetry,)+ # Every close reports, whichever of the five paths did it — and only for a+ # connection the handler saw start.+ connections.set_close_listener(protocol.sessions.on_close)+# ── Server-side connector lifecycle ─────────────────────────────────────connector_lifecycle = ServerSideConnectorLifecycleService(connector_store=connector_store,@@ -498,6 +556,7 @@ async def run(config: SwitchConfig) -> None:protocol=protocol,session_factory=session_factory,encryption_secret=config.jwt_secret_key,+ telemetry=telemetry,)connector_lifecycle.register_connector_type("opencode", OpenCodeConnector, OpenCodeConnectionConfig@@ -621,6 +680,14 @@ async def run(config: SwitchConfig) -> None:# ── Lifespan: start server-side connectors once HTTP is serving ────────original_lifespan = agent_bridge_app.router.lifespan_context+ snapshot_reporter = SnapshotReporter(+ telemetry=telemetry,+ session_factory=session_factory,+ interval_hours=config.telemetry_snapshot_interval_hours,+ installed_at=installed_at,+ live_session_count=connections.live_connection_count,+ )+@asynccontextmanagerasync def lifespan(app: object) -> AsyncIterator[None]:nonlocal observability@@ -636,13 +703,27 @@ async def run(config: SwitchConfig) -> None:connection_sweep_task = asyncio.create_task(_connection_sweep_loop(protocol, observability.lag))+ # Only when telemetry is on: the chart tells a customer that off+ # means nothing is collected, and the fan-out is not free.+ snapshot_task = (+ asyncio.create_task(_snapshot_loop(snapshot_reporter))+ if telemetry.enabled+ else None+ )await message_listener.start()try:yieldfinally:sweep_task.cancel()connection_sweep_task.cancel()+ if snapshot_task is not None:+ snapshot_task.cancel()await message_listener.stop()+ # Before the operational flush, and bounded: the whole+ # teardown runs inside `_FORCED_EXIT_GRACE_SECONDS` and a+ # product event is the least valuable thing in it.+ await protocol.sessions.aclose()+ await _drain_telemetry(telemetry, telemetry_http)await observability.aclose()# So a probe during teardown gets a 503 rather than the last# cached answer, which may still say ready.@@ -663,6 +744,10 @@ async def run(config: SwitchConfig) -> None:"Switch is running on http://%s:%d", config.server_host, config.server_port)+ telemetry.emit("deployment_started", tenant_count=len(tenant_ids))+ # The funnel's first step, and only for a deployment with an install date.+ await telemetry.emit_milestone("deployment_installed")+server_config = uvicorn.Config(agent_bridge_app,host=config.server_host,diff --git a/core/switch_core/migrations/versions/a7e1c4b90d23_telemetry_bookkeeping.py b/core/switch_core/migrations/versions/a7e1c4b90d23_telemetry_bookkeeping.pynew file mode 100644index 000000000..07eef0118--- /dev/null+++ b/core/switch_core/migrations/versions/a7e1c4b90d23_telemetry_bookkeeping.py@@ -0,0 +1,91 @@+"""telemetry bookkeeping: deployment identity, milestones, snapshot watermark++Three server-global tables, none tenant-scoped and none carrying row-level+security: each records a fact about the *installation*, which is the thing+above tenants rather than one of them.++`deployment_identity` is seeded here rather than at first use, because whether+a deployment is new decides whether it ever reports time-to-value and this is+the last moment that can be answered honestly. `installed_at` is set only when+the database is empty of product content; an existing deployment gets a null+install date and reports no milestones, rather than a date inferred from its+oldest row.++Revision ID: a7e1c4b90d23+Revises: 2d84b6f1c705+Create Date: 2026-09-16 00:00:00.000000++"""++from collections.abc import Sequence++import sqlalchemy as sa+from alembic import op++revision: str = "a7e1c4b90d23"+down_revision: str | None = "2d84b6f1c705"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None+++def upgrade() -> None:+ op.create_table(+ "deployment_identity",+ sa.Column("id", sa.Integer(), primary_key=True),+ sa.Column("client_id", sa.Text(), nullable=False),+ sa.Column("installed_at", sa.DateTime(timezone=True), nullable=True),+ sa.Column(+ "created_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ sa.CheckConstraint("id = 1", name="ck_deployment_identity_singleton"),+ )++ op.create_table(+ "telemetry_milestones",+ sa.Column("name", sa.Text(), primary_key=True),+ sa.Column(+ "emitted_at",+ sa.DateTime(timezone=True),+ server_default=sa.func.now(),+ nullable=False,+ ),+ )++ op.create_table(+ "telemetry_snapshot_watermark",+ sa.Column("id", sa.Integer(), primary_key=True),+ sa.Column("last_sent_at", sa.DateTime(timezone=True), nullable=False),+ sa.CheckConstraint("id = 1", name="ck_telemetry_snapshot_watermark_singleton"),+ )++ # The identity row, with the new-versus-existing decision made now.+ #+ # "Existing" is judged on product content — rooms, agents, messages — not+ # on rows the server seeds for itself at boot. A fresh deployment already+ # has a tenant, an admin user and a bootstrap key by the time anything+ # else runs, so testing for *any* row would classify every new install as+ # pre-existing and switch off the activation funnel everywhere.+ op.execute(+ """+ INSERT INTO deployment_identity (id, client_id, installed_at)+ SELECT+ 1,+ gen_random_uuid()::text,+ CASE+ WHEN EXISTS (SELECT 1 FROM rooms)+ OR EXISTS (SELECT 1 FROM agents)+ OR EXISTS (SELECT 1 FROM messages)+ THEN NULL+ ELSE now()+ END+ """+ )+++def downgrade() -> None:+ op.drop_table("telemetry_snapshot_watermark")+ op.drop_table("telemetry_milestones")+ op.drop_table("deployment_identity")diff --git a/core/switch_core/migrations/versions/b8f2d0c41e57_messages_tenant_sent_at_index.py b/core/switch_core/migrations/versions/b8f2d0c41e57_messages_tenant_sent_at_index.pynew file mode 100644index 000000000..1553b4699--- /dev/null+++ b/core/switch_core/migrations/versions/b8f2d0c41e57_messages_tenant_sent_at_index.py@@ -0,0 +1,50 @@+"""index messages on (tenant_id, sent_at) for the usage snapshot++The snapshot asks the message table several questions a day, all of the shape+"this tenant's messages since a moment": traffic in the last day, who sent it,+distinct humans who interacted over a week, the distinct rooms they interacted+in, and attachments. `ix_messages_room_sent_at` cannot serve any of them — its+leading column is `room_id` and none of these name a room — so each was a+sequential scan of the busiest table in the schema, once per tenant per pass.++Nothing else needed it: the read path pages within a room and the existing+index serves that.++**Not `CONCURRENTLY`, which is a judgement about when this lands.** Revisions+run in a transaction, so this holds `ACCESS EXCLUSIVE` on `messages` until the+migration commits — milliseconds at the size every deployment has today, and+one that later grows will have had the index since before it did.+`CONCURRENTLY` would need an `autocommit_block`, which cannot roll back.++For a deployment that already has a large `messages` table, build it by hand+first and this becomes a no-op:++ CREATE INDEX CONCURRENTLY ix_messages_tenant_sent_at+ ON messages (tenant_id, sent_at);++Revision ID: b8f2d0c41e57+Revises: a7e1c4b90d23+Create Date: 2026-09-17 00:00:00.000000++"""++from collections.abc import Sequence++from alembic import op++revision: str = "b8f2d0c41e57"+down_revision: str | None = "a7e1c4b90d23"+branch_labels: str | Sequence[str] | None = None+depends_on: str | Sequence[str] | None = None++_INDEX = "ix_messages_tenant_sent_at"+++def upgrade() -> None:+ # `IF NOT EXISTS` so the escape hatch above works: an operator who built it+ # concurrently ahead of the upgrade meets a no-op rather than a collision.+ op.execute(f"CREATE INDEX IF NOT EXISTS {_INDEX} ON messages (tenant_id, sent_at)")+++def downgrade() -> None:+ op.execute(f"DROP INDEX IF EXISTS {_INDEX}")diff --git a/core/switch_core/room_service.py b/core/switch_core/room_service.pyindex f8f748846..ebd75053a 100644--- a/core/switch_core/room_service.py+++ b/core/switch_core/room_service.py@@ -16,7 +16,8 @@ room Switch has no record of it being in.from __future__ import annotationsimport logging-from typing import TYPE_CHECKING, Any+from datetime import UTC, datetime+from typing import TYPE_CHECKING, Any, Literalfrom pydantic import BaseModelfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker@@ -36,6 +37,13 @@ from switch_core.db.stores.collaboration_bridge_store import CollaborationBridgefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.db.tenant_lookup import all_tenant_idsfrom switch_core.provisioning import Provisioning+from switch_core.telemetry import TelemetryService, emit_safely+from switch_core.telemetry.snapshot import (+ normalise_actor_kind,+ normalise_channel_type,+ normalise_platform,+ room_had_human_activity,+)from switch_core.tenant_context import tenant_scopeif TYPE_CHECKING:@@ -49,6 +57,19 @@ logger = logging.getLogger(__name__)SYSTEM_CLIENT_TYPES = ("observe", "admin")+def _age_days(created_at: object) -> float:+ """How many days old a room is, for reporting. Zero if unknown.++ Takes `object` because the timestamp columns on the models are annotated+ `Mapped[str]` while carrying real `datetime`s — so the honest signature is+ "whatever the column hands back", checked here rather than trusted.+ """+ if not isinstance(created_at, datetime):+ return 0.0+ moment = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - moment).total_seconds() / 86400.0, 0.0)++class LinkedRoomSpec(BaseModel):target_room_id: strlabel: str@@ -111,6 +132,11 @@ class RoomCreateConfig(BaseModel):aliases: dict[str, str] | None = Noneacting_user_id: str | None = Noneacting_is_admin: bool = False+ # Not derivable from `created_by`, which holds the *agent's owner* on the+ # agent path. Stamped into the room's metadata so it survives.+ created_by_kind: Literal["user", "agent", "system"] = "user"+ # Provisioned from a room template rather than created directly.+ from_template: bool = Falseclass RoomCreateResult(BaseModel):@@ -127,6 +153,12 @@ class RoomCreateResult(BaseModel):class RoomService:+ # Class-level default so a caller that builds this without `__init__` —+ # several tests assemble a minimal instance directly — still has the+ # attribute. Telemetry is genuinely optional here; `emit_safely` treats+ # None as "report nothing".+ _telemetry: TelemetryService | None = None+def __init__(self,*,@@ -138,6 +170,7 @@ class RoomService:collab_bridge_store: CollaborationBridgeStore,resource_service: ResourceService,session_factory: async_sessionmaker[AsyncSession],+ telemetry: TelemetryService | None = None,) -> None:self._matrix_admin = matrix_adminself._room_store = room_store@@ -147,6 +180,9 @@ class RoomService:self._collab_bridge_store = collab_bridge_storeself._resource_service = resource_serviceself._session_factory = session_factory+ # Optional because several tests and tooling build a RoomService+ # without one; `emit_safely` treats None as "report nothing".+ self._telemetry = telemetryasync def _resolve_agent_ids(self, config: RoomCreateConfig) -> list[str]:if config.agent_ids is not None:@@ -513,6 +549,8 @@ class RoomService:owner_id=config.owner_id,read_visibility=config.read_visibility,write_visibility=config.write_visibility,+ # Nothing else on the row can answer this afterwards.+ metadata_={"created_by_kind": config.created_by_kind},)async with self._session_factory() as session:@@ -603,6 +641,32 @@ class RoomService:len(system_clients),)+ # Never inside the argument list: an `await` there is evaluated before+ # `emit_safely` is entered, outside the guard meant to contain it.+ platform = await self._bridge_platform(bridge_id)++ emit_safely(+ self._telemetry,+ "room_created",+ {+ "channel_type": normalise_channel_type(channel_type),+ "bridge_platform": platform,+ "agent_count": len(agent_ids),+ "human_count": len(config.user_names or []),+ "has_instructions": config.instructions is not None,+ "created_by_kind": config.created_by_kind,+ "from_template": config.from_template,+ },+ )++ # Only a room a person made counts as activation.+ if self._telemetry is not None and config.created_by_kind == "user":+ await self._telemetry.emit_milestone(+ "first_room_created",+ channel_type=normalise_channel_type(channel_type),+ bridge_platform=platform,+ )+failed_attachments = unreachable_users + await self._attach_after_creation(room.id, config)@@ -651,6 +715,14 @@ class RoomService:bridge_id = room.bridge_idclient_ids = await self._room_store.get_client_ids(session, room_id)+ agent_count = (+ len(await self._room_store.get_agent_ids(session, room_id))+ if self._telemetry is not None+ else 0+ )++ # Before the delete: the cascade takes the messages with the room.+ was_ever_active = await self._was_ever_active(room.tenant_id, room_id)# `kick_user` and the delete below both write rows scoped to this# room's tenant (a membership removal, then the room itself), so both@@ -677,6 +749,23 @@ class RoomService:logger.info("Deleted room %s", room_id)+ if self._telemetry is None:+ return+ emit_safely(+ self._telemetry,+ "room_deleted",+ {+ "bridge_platform": await self._bridge_platform(bridge_id),+ "channel_type": normalise_channel_type(room.channel_type),+ "created_by_kind": normalise_actor_kind(+ (room.metadata_ or {}).get("created_by_kind")+ ),+ "age_days": _age_days(room.created_at),+ "was_ever_active": was_ever_active,+ "agent_count": agent_count,+ },+ )+async def _resolve_names_to_ids(self, agent_names: list[str]) -> list[str]:unique_names = list(dict.fromkeys(agent_names))async with self._session_factory() as session:@@ -694,6 +783,7 @@ class RoomService:agent_names: list[str] | None = None,include_subagents_for: list[str] | None = None,join_event_listeners: list[str] | None = None,+ added_by_kind: Literal["user", "agent", "system"] = "user",) -> None:by_name = agent_ids is None and agent_names is not Noneif by_name:@@ -763,7 +853,22 @@ class RoomService:logger.info("Added %d agents to room %s", len(agent_ids), room_id)- async def remove_agents_from_room(self, room_id: str, agent_ids: list[str]) -> None:+ emit_safely(+ self._telemetry,+ "room_agents_added",+ {+ # Added, not requested.+ "agent_count": len(new_agent_ids),+ "added_by_kind": added_by_kind,+ },+ )++ async def remove_agents_from_room(+ self,+ room_id: str,+ agent_ids: list[str],+ removed_by_kind: Literal["user", "agent", "system"] = "user",+ ) -> None:async with self._session_factory() as session:room = await self._room_store.get(session, room_id)if room is None:@@ -783,6 +888,12 @@ class RoomService:logger.info("Removed %d agents from room %s", len(agent_ids), room_id)+ emit_safely(+ self._telemetry,+ "room_agents_removed",+ {"agent_count": len(agent_ids), "removed_by_kind": removed_by_kind},+ )+async def _load_room(self, room_id: str) -> Room:"""A room row, read on the caller's session.@@ -881,11 +992,63 @@ class RoomService:Raises ValueError if the room does not exist."""- tenant_id = await self._room_tenant(room_id)- async with tenant_session(self._session_factory, tenant_id) as session:+ # The whole row: archiving reports its age and platform.+ room = await self._load_room(room_id)+ async with tenant_session(self._session_factory, room.tenant_id) as session:await self._room_store.set_archived(session, room_id, archived)await session.commit()+ if not archived or self._telemetry is None:+ return+ emit_safely(+ self._telemetry,+ "room_archived",+ {+ "bridge_platform": await self._bridge_platform(room.bridge_id),+ "age_days": _age_days(room.created_at),+ "was_ever_active": await self._was_ever_active(room.tenant_id, room_id),+ },+ )++ async def _bridge_platform(self, bridge_id: str | None) -> str:+ """The platform a bridge id names, as the telemetry catalogue spells it.++ `none` for an internal-only room and for a lookup that failed. Never+ raises: the operations this labels must not fail because it did.+ """+ if bridge_id is None or self._telemetry is None:+ return "none"+ try:+ async with self._session_factory() as session:+ bridge = await self._collab_bridge_store.get(session, bridge_id)+ except Exception:+ logger.warning(+ "Could not resolve the platform of bridge %s for telemetry; "+ "reporting it as unknown.",+ bridge_id,+ exc_info=True,+ )+ return "none"+ return normalise_platform(bridge.type if bridge else None)++ async def _was_ever_active(self, tenant_id: str, room_id: str) -> bool:+ """Whether a human ever posted in this room.++ Asked only on archive, so the cost lands on a rare operation. False on+ failure — an archive must not fail because a count did.+ """+ try:+ async with tenant_session(self._session_factory, tenant_id) as session:+ return await room_had_human_activity(session, tenant_id, room_id)+ except Exception:+ logger.warning(+ "Could not determine whether room %s was ever active; "+ "reporting it as inactive.",+ room_id,+ exc_info=True,+ )+ return False+async def add_users_to_room(self, room_id: str, user_names: list[str]) -> list[str]:"""Add users to a bridged room; returns the names that did not make it(added users are omitted from the result).@@ -923,6 +1086,12 @@ class RoomService:room_id,unresolved,)+ emit_safely(+ self._telemetry,+ # Resolved, not requested: an unknown name adds nobody.+ "room_users_added",+ {"user_count": max(len(user_names) - len(unresolved), 0)},+ )return unresolvedasync def link_bridge_to_room(diff --git a/core/switch_core/rooms_yaml.py b/core/switch_core/rooms_yaml.pyindex 64468557a..88f14611a 100644--- a/core/switch_core/rooms_yaml.py+++ b/core/switch_core/rooms_yaml.py@@ -586,6 +586,7 @@ class RoomYamlService:user_names=spec.users or None,bridge_id=bridge_id,created_by=user_id,+ from_template=True,owner_id=user_id,acting_user_id=user_id,acting_is_admin=is_admin,diff --git a/core/switch_core/telemetry/__init__.py b/core/switch_core/telemetry/__init__.pynew file mode 100644index 000000000..166831924--- /dev/null+++ b/core/switch_core/telemetry/__init__.py@@ -0,0 +1,23 @@+"""Product telemetry: what Switch reports about how it is used.++Counts and durations, never an identifier for a room, tenant, agent, user or+message, and never free text. Off unless an operator switches it on. The events+are declared in :mod:`switch_core.telemetry.catalogue` and explained in+``docs/old/telemetry-events.md``.++Call sites want two things from this package and nothing else: `emit_safely`,+to report an event from the middle of real work without a catalogue mistake+being able to break it, and the `TelemetryService` that gets handed around.+Everything else here is wiring.+"""++from switch_core.telemetry.catalogue import TelemetryCatalogueError+from switch_core.telemetry.service import TelemetryService, emit_safely+from switch_core.telemetry.setup import build_telemetry++__all__ = [+ "TelemetryCatalogueError",+ "TelemetryService",+ "build_telemetry",+ "emit_safely",+]diff --git a/core/switch_core/telemetry/catalogue.py b/core/switch_core/telemetry/catalogue.pynew file mode 100644index 000000000..40fc0df67--- /dev/null+++ b/core/switch_core/telemetry/catalogue.py@@ -0,0 +1,400 @@+"""Every event the server may report, and every property each one carries.++This is the privacy boundary, enforced rather than documented: an event or a+property not declared here cannot be sent, and no path forwards an arbitrary+string. :func:`validate` holds two rules — the property set is exact (a+property that does not apply carries an explicit ``none``, so a missing key is+always a bug) and values are closed.++``docs/old/telemetry-events.md`` says why each event exists; this says what is+allowed on the wire.+"""++from __future__ import annotations++from collections.abc import Mapping+from dataclasses import dataclass++# The wire prefix. One Amplitude project holds several products, so every event+# is namespaced by the one that sent it — the Console sends `switch_console.*`+# against the same relay.+EVENT_NAME_PREFIX = "switch_core"+++class PropertyType:+ """Base for the three kinds of value a property may take."""++ def check(self, value: object) -> str | None:+ """Return a human-readable reason the value is unacceptable, or None."""+ raise NotImplementedError+++@dataclass(frozen=True)+class _Number(PropertyType):+ def check(self, value: object) -> str | None:+ # bool is a subclass of int; a boolean where a count belongs is a+ # mistake worth naming rather than silently recording as 0 or 1.+ if isinstance(value, bool) or not isinstance(value, int | float):+ return f"expected a number, got {type(value).__name__}"+ if value != value or value in (float("inf"), float("-inf")):+ return "expected a finite number"+ return None+++@dataclass(frozen=True)+class _Boolean(PropertyType):+ def check(self, value: object) -> str | None:+ if not isinstance(value, bool):+ return f"expected a boolean, got {type(value).__name__}"+ return None+++@dataclass(frozen=True)+class _OneOf(PropertyType):+ values: frozenset[str]++ def check(self, value: object) -> str | None:+ if not isinstance(value, str):+ return f"expected one of {sorted(self.values)}, got {type(value).__name__}"+ if value not in self.values:+ return f"expected one of {sorted(self.values)}, got {value!r}"+ return None+++NUMBER = _Number()+BOOLEAN = _Boolean()+++def one_of(*values: str) -> _OneOf:+ return _OneOf(frozenset(values))+++class TelemetryCatalogueError(Exception):+ """An event does not match the catalogue.++ Always a programming error rather than a runtime condition: the event name,+ the property names and the set of values a property may take are all fixed+ at author time. Raised rather than logged so it fails in the test that+ builds the event, not in production as a silently malformed record.+ """+++# ── Shared value sets ────────────────────────────────────────────────────────++# The five collaboration platforms, plus the absence of one. `none` rather than+# omitting the property: see the module docstring on exact property sets.+BRIDGE_PLATFORM = one_of("slack", "mattermost", "discord", "teams", "telegram", "none")++CHANNEL_TYPE = one_of("channel_public", "channel_private", "direct", "none")++# All four connection models in `bridges/agent/protocol/types.py`. Missing one+# drops the registration event for every agent that uses it.+AGENT_TYPE = one_of(+ "always_on", "session_addressable", "session_passive", "auto_session"+)++# The runtime behind an agent, from `known_agent_type` in its metadata.+# `other` covers a runtime Switch has no special knowledge of; `none` covers an+# agent registered without declaring one at all.+KNOWN_AGENT_TYPE = one_of("claude-code", "codex", "opencode", "other", "none")++ACTOR_KIND = one_of("user", "agent", "system")++OUTCOME = one_of("success", "failure")++# The four built-in types. A user-defined type's slug is free text, so it+# reports as `other` rather than going on the wire.+REFERENCE_TYPE = one_of("google_drive", "confluence", "github", "jira", "other")++# Where a document lives. A room document is scoped to one room and never in+# the library; a library one can be attached to many.+DOCUMENT_SCOPE = one_of("library", "room")++# What a key is for. `agent` authenticates a registered agent, `registration`+# mints new ones, `bootstrap` is the deployment-wide key, `other` is anything+# a later type introduces.+API_KEY_TYPE = one_of("agent", "registration", "bootstrap", "other")++VISIBILITY = one_of("private", "public")++# What a template provisions. Free text in the schema; these are the three the+# product itself uses, and anything an operator invents reports as `other`.+TEMPLATE_KIND = one_of("room", "group", "agent", "other")++# Shared by the connect and disconnect events: one classifier feeds both, so a+# value only one of them declares fails validation when a bridge drops.+BRIDGE_FAILURE_REASON = one_of(+ "none", "auth_failed", "network", "platform_error", "config_invalid", "unknown"+)+++# ── The catalogue ────────────────────────────────────────────────────────────++_SNAPSHOT_COUNTS = (+ "tenant_count",+ "user_count",+ "user_active_1d",+ "user_active_7d",+ # `room_count` is the headline: rooms a *person* made. The other two keep+ # agent scratch rooms and adopted channels out of it.+ "room_count",+ "room_agent_created_count",+ "room_system_created_count",+ "room_active_1d",+ "room_active_7d",+ "room_archived_count",+ "room_internal_only_count",+ "room_membership_total",+ "room_users_mean",+ "room_users_max",+ "agent_count",+ "agent_active_7d",+ "agent_claude_code_count",+ "agent_codex_count",+ "agent_opencode_count",+ "agent_other_count",+ # Connections, not distinct agents: an agent may hold several. No+ # "sessions started today" — nothing durable records one, so it could only+ # be an in-process tally a restart resets. `agent_session_started` covers it.+ "session_live_count",+ "connector_slack_count",+ "connector_mattermost_count",+ "connector_discord_count",+ "connector_teams_count",+ "connector_telegram_count",+ "connector_configured_count",+ "message_count_1d",+ "message_from_human_1d",+ "message_from_agent_1d",+ # A turn is a message classified by who sent the one before it. A+ # sender-only count reports an agent answering a person and two agents+ # talking to each other identically.+ "turn_human_to_agent_1d",+ "turn_agent_to_human_1d",+ "turn_agent_to_agent_1d",+ "attachment_count_1d",+ # Stock rather than flow. The `*_attached_count` figures sit beside the+ # totals because the gap between made and used is the signal.+ "reference_count",+ "reference_attached_count",+ "document_count",+ "document_attached_count",+ "package_count",+ "room_group_count",+ "api_key_count",+)++# Every milestone answers "how long after install did this first happen", so+# they share a property and differ only in what else they carry.+_SINCE_INSTALL: Mapping[str, PropertyType] = {"seconds_since_install": NUMBER}+++CATALOGUE: Mapping[str, Mapping[str, PropertyType]] = {+ # ── The daily snapshot ───────────────────────────────────────────────────+ # Counted locally, where the ids are known; only totals are reported.+ "usage_snapshot": {name: NUMBER for name in _SNAPSHOT_COUNTS},+ # ── Milestones ───────────────────────────────────────────────────────────+ # At most once per deployment, and only for one installed after this+ # shipped. Together they are the activation funnel.+ "deployment_installed": dict(_SINCE_INSTALL),+ "first_connector_added": {**_SINCE_INSTALL, "bridge_platform": BRIDGE_PLATFORM},+ "first_room_created": {+ **_SINCE_INSTALL,+ "channel_type": CHANNEL_TYPE,+ "bridge_platform": BRIDGE_PLATFORM,+ },+ "first_room_active": {+ **_SINCE_INSTALL,+ "bridge_platform": BRIDGE_PLATFORM,+ "seconds_since_room_created": NUMBER,+ },+ "first_agent_registered": {+ **_SINCE_INSTALL,+ "known_agent_type": KNOWN_AGENT_TYPE,+ },+ "first_session_started": {**_SINCE_INSTALL, "known_agent_type": KNOWN_AGENT_TYPE},+ # ── Lifecycle ────────────────────────────────────────────────────────────+ # The version is a resource attribute, so this is the upgrade curve.+ "deployment_started": {"tenant_count": NUMBER},+ "room_created": {+ "channel_type": CHANNEL_TYPE,+ "bridge_platform": BRIDGE_PLATFORM,+ "agent_count": NUMBER,+ "human_count": NUMBER,+ "has_instructions": BOOLEAN,+ "created_by_kind": ACTOR_KIND,+ "from_template": BOOLEAN,+ },+ "room_became_active": {+ "seconds_since_room_created": NUMBER,+ "bridge_platform": BRIDGE_PLATFORM,+ "channel_type": CHANNEL_TYPE,+ "agent_count": NUMBER,+ "created_by_kind": ACTOR_KIND,+ },+ "room_archived": {+ "bridge_platform": BRIDGE_PLATFORM,+ "age_days": NUMBER,+ "was_ever_active": BOOLEAN,+ },+ "room_agents_added": {"agent_count": NUMBER, "added_by_kind": ACTOR_KIND},+ "room_agents_removed": {"agent_count": NUMBER, "removed_by_kind": ACTOR_KIND},+ # ── Removals ─────────────────────────────────────────────────────────────+ # Counts fall for several reasons and only these say which. Each carries+ # the lifespan: deleted after an hour and after a year mean opposite things.+ "room_deleted": {+ "bridge_platform": BRIDGE_PLATFORM,+ "channel_type": CHANNEL_TYPE,+ "created_by_kind": ACTOR_KIND,+ "age_days": NUMBER,+ "was_ever_active": BOOLEAN,+ "agent_count": NUMBER,+ },+ "agent_deleted": {+ "known_agent_type": KNOWN_AGENT_TYPE,+ "age_days": NUMBER,+ "room_count": NUMBER,+ "had_parent": BOOLEAN,+ },+ "connector_removed": {+ "bridge_platform": BRIDGE_PLATFORM,+ "age_days": NUMBER,+ # Removed having never connected is a failed setup; removed after+ # months is a decision.+ "was_ever_connected": BOOLEAN,+ "room_count": NUMBER,+ },+ "agent_registered": {+ "agent_type": AGENT_TYPE,+ "known_agent_type": KNOWN_AGENT_TYPE,+ # `gateway` is Console *and* the browser dashboard: they authenticate+ # identically, so the server cannot tell them apart.+ "registration_path": one_of("bootstrap", "personal_key", "gateway", "other"),+ "has_parent": BOOLEAN,+ },+ # No "start source": the server sees an authenticated connection whether a+ # person launched the session or Console spawned it.+ "agent_session_started": {"known_agent_type": KNOWN_AGENT_TYPE},+ # No runtime: the connection registry is the only thing that knows a+ # session ended and it holds none. Starts carry it.+ "agent_session_ended": {+ "duration_seconds": NUMBER,+ "reason": one_of(+ "normal", "heartbeat_lapsed", "replaced", "room_claimed", "error"+ ),+ },+ "connector_added": {+ "bridge_platform": BRIDGE_PLATFORM,+ "seconds_since_install": NUMBER,+ "seconds_since_configured": NUMBER,+ "is_first_connector": BOOLEAN,+ "failed_attempts_before_success": NUMBER,+ },+ "bridge_connected": {+ "bridge_platform": BRIDGE_PLATFORM,+ "outcome": OUTCOME,+ # `none` on success, so the property set stays exact either way.+ "failure_reason": BRIDGE_FAILURE_REASON,+ },+ # ── Resources, keys and groups ───────────────────────────────────────────+ # Creating is intent, attaching is use, and the gap between them is the+ # signal — hence both.+ "reference_created": {+ "reference_type": REFERENCE_TYPE,+ "read_visibility": VISIBILITY,+ "created_by_kind": ACTOR_KIND,+ },+ "reference_attached_to_room": {"reference_type": REFERENCE_TYPE},+ "reference_deleted": {"reference_type": REFERENCE_TYPE, "age_days": NUMBER},+ "document_created": {+ "scope": DOCUMENT_SCOPE,+ "created_by_kind": ACTOR_KIND,+ "has_instructions": BOOLEAN,+ },+ "document_attached_to_room": {},+ "document_deleted": {"scope": DOCUMENT_SCOPE, "age_days": NUMBER},+ "package_created": {"created_by_kind": ACTOR_KIND},+ "package_attached_to_room": {"reference_count": NUMBER, "document_count": NUMBER},+ "package_deleted": {"age_days": NUMBER},+ "api_key_created": {"key_type": API_KEY_TYPE},+ "api_key_revoked": {"key_type": API_KEY_TYPE, "age_days": NUMBER},+ "room_group_created": {"has_parent": BOOLEAN},+ "room_group_deleted": {"room_count": NUMBER, "age_days": NUMBER},+ # The schema, not an instance: registering one extends what Switch can+ # point at.+ "reference_type_created": {},+ "reference_type_deleted": {"age_days": NUMBER},+ "template_created": {"template_kind": TEMPLATE_KIND},+ "template_deleted": {"template_kind": TEMPLATE_KIND, "age_days": NUMBER},+ "room_link_created": {},+ "room_link_removed": {},+ "room_role_defined": {"exclusive": BOOLEAN},+ "room_role_deleted": {},+ "room_users_added": {"user_count": NUMBER},+ # The inverse of the attaches: tried and dropped, as against never used.+ "reference_detached_from_room": {"reference_type": REFERENCE_TYPE},+ "document_detached_from_room": {},+ "package_detached_from_room": {},+ # Switch reaching out to an agent host, rather than one connecting in.+ "server_connector_registered": {"connector_kind": one_of("opencode", "other")},+ "server_connector_removed": {"connector_kind": one_of("opencode", "other")},+ # Configured, not connected. Many of these and few `bridge_connected` is a+ # deployment whose setup is failing.+ "connector_configured": {"bridge_platform": BRIDGE_PLATFORM},+ "invitation_sent": {},+ "invitation_accepted": {"age_hours": NUMBER},+ "bridge_disconnected": {+ "bridge_platform": BRIDGE_PLATFORM,+ # Shutdown reasons plus every failure `bridge_connected` can carry.+ "reason": one_of(+ "shutdown",+ "restart",+ *sorted(BRIDGE_FAILURE_REASON.values - {"none"}),+ ),+ },+}+++PropertyValue = str | int | float | bool+++def wire_name(event: str) -> str:+ """The prefixed name as the relay sees it."""+ return f"{EVENT_NAME_PREFIX}.{event}"+++def validate(event: str, properties: Mapping[str, PropertyValue]) -> None:+ """Raise unless `properties` is exactly what `event` declares.++ Checks the three things that would each, on their own, let something+ unintended reach the relay: an event nobody declared, a property nobody+ declared, and a value outside the set its property allows. A missing+ property is checked too — not for privacy but for the charts, since an+ event whose keys vary between emissions cannot be grouped on them.+ """+ spec = CATALOGUE.get(event)+ if spec is None:+ raise TelemetryCatalogueError(+ f"{event!r} is not a telemetry event. Add it to CATALOGUE in "+ "telemetry/catalogue.py (and to docs/old/telemetry-events.md) "+ "rather than sending an undeclared one."+ )++ given = set(properties)+ declared = set(spec)+ if undeclared := sorted(given - declared):+ raise TelemetryCatalogueError(+ f"{event!r} does not declare {undeclared}. Every property must be "+ "in the catalogue: this is the check that stops an identifier or a "+ "free-text value reaching the relay by accident."+ )+ if missing := sorted(declared - given):+ raise TelemetryCatalogueError(+ f"{event!r} is missing {missing}. Every event of a name carries the "+ "same keys every time — pass the explicit 'none'/0/False rather "+ "than omitting one."+ )++ for name, value in properties.items():+ if reason := spec[name].check(value):+ raise TelemetryCatalogueError(f"{event!r}.{name}: {reason}.")diff --git a/core/switch_core/telemetry/deployment.py b/core/switch_core/telemetry/deployment.pynew file mode 100644index 000000000..de3ed0392--- /dev/null+++ b/core/switch_core/telemetry/deployment.py@@ -0,0 +1,118 @@+"""The deployment's identity, its install clock, and once-ever milestones.++Facts about the installation, not about any tenant in it — so these tables+carry no tenant column and no policy, and are read on a session with nothing+bound, the same shape `users` is read in (`db/session_scope.py`). The modules+are named in `tests/switch_core/db/test_tenant_exemption_allowlist.py`.++`installed_at` is null for a deployment that predates this, and+:func:`seconds_since_install` then returns `None`, which every milestone call+site treats as "do not report".+"""++from __future__ import annotations++import logging+from datetime import UTC, datetime++from sqlalchemy import select+from sqlalchemy.dialects.postgresql import insert as pg_insert+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import DeploymentIdentity, TelemetryMilestone++logger = logging.getLogger(__name__)+++class DeploymentIdentityMissingError(RuntimeError):+ """The singleton identity row is absent.++ Not repaired at runtime: the row records whether this deployment is new,+ and only the migration ran early enough to answer that.+ """+++async def load_deployment_identity(+ session_factory: async_sessionmaker[AsyncSession],+) -> tuple[str, datetime | None]:+ """The deployment's client id and install date.++ Returns `(client_id, installed_at)`, where `installed_at` is `None` for a+ deployment that predates this telemetry.+ """+ async with session_factory() as session:+ row = (+ await session.execute(select(DeploymentIdentity).limit(1))+ ).scalar_one_or_none()+ if row is None:+ raise DeploymentIdentityMissingError(+ "No deployment_identity row. It is seeded by the telemetry "+ "bookkeeping migration; run migrations before starting the "+ "server. It is not recreated here because only the migration ran "+ "early enough to tell a new deployment from an existing one."+ )+ return row.client_id, row.installed_at+++def seconds_since_install(installed_at: datetime | None) -> float | None:+ """Elapsed seconds since install, or `None` if that is not knowable.++ `None` propagates all the way to the call site, which then reports+ nothing. Time-to-value describes only deployments watched from their first+ boot.+ """+ if installed_at is None:+ return None+ if installed_at.tzinfo is None:+ installed_at = installed_at.replace(tzinfo=UTC)+ return max((datetime.now(UTC) - installed_at).total_seconds(), 0.0)+++async def milestone_claimed(+ session_factory: async_sessionmaker[AsyncSession], name: str+) -> bool:+ """Whether `name` has already been reported, without claiming it.++ For the places that need to know a thing once happened — a connector's+ removal asking whether it ever connected. False on failure.+ """+ try:+ async with session_factory() as session:+ found = await session.execute(+ select(TelemetryMilestone.name).where(TelemetryMilestone.name == name)+ )+ return found.scalar_one_or_none() is not None+ except Exception:+ logger.warning(+ "Could not read the %s telemetry milestone; treating it as unreported.",+ name,+ exc_info=True,+ )+ return False+++async def claim_milestone(+ session_factory: async_sessionmaker[AsyncSession], name: str+) -> bool:+ """Take the right to report `name`, once, for this deployment.++ The insert is the guard: the name is the primary key, so a second caller+ collides in the database rather than racing a read-then-write. Returns+ False on failure — a lost milestone beats a failed request.+ """+ try:+ async with session_factory() as session:+ result = await session.execute(+ pg_insert(TelemetryMilestone)+ .values(name=name)+ .on_conflict_do_nothing(index_elements=["name"])+ .returning(TelemetryMilestone.name)+ )+ claimed = result.scalar_one_or_none() is not None+ await session.commit()+ return claimed+ except Exception:+ logger.exception(+ "Could not record the %s telemetry milestone; not reporting it.", name+ )+ return Falsediff --git a/core/switch_core/telemetry/reporter.py b/core/switch_core/telemetry/reporter.pynew file mode 100644index 000000000..18d3e14a6--- /dev/null+++ b/core/switch_core/telemetry/reporter.py@@ -0,0 +1,169 @@+"""The background task that sends the daily snapshot.++Anchored to a watermark rather than to uptime, so restarts do not change the+cadence.++The first pass sends the snapshot but not the room-activation events: with no+watermark, "first interaction since then" means every room that ever went+active, arriving at once and all dated today.+"""++from __future__ import annotations++import asyncio+import logging+from collections.abc import Callable+from datetime import UTC, datetime, timedelta++from sqlalchemy import select+from sqlalchemy.dialects.postgresql import insert as pg_insert+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import TelemetrySnapshotWatermark+from switch_core.telemetry.deployment import claim_milestone+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.snapshot import (+ as_utc,+ collect_usage,+ newly_active_rooms,+ summarise,+)++logger = logging.getLogger(__name__)++# How long to wait before the first pass. Long enough that a restart loop+# cannot turn boot into a stream of snapshots, short enough that a developer+# switching telemetry on does not have to wait a day to see whether it works.+_FIRST_PASS_DELAY_SECONDS = 60.0++# How often to wake and ask whether a snapshot is due. Well under the interval+# itself, so a deployment that was down over its due time sends promptly on the+# next start rather than waiting a further full period.+_POLL_INTERVAL_SECONDS = 300.0+++class SnapshotReporter:+ """Collects and sends the usage snapshot on a schedule."""++ def __init__(+ self,+ *,+ telemetry: TelemetryService,+ session_factory: async_sessionmaker[AsyncSession],+ interval_hours: float,+ installed_at: datetime | None,+ live_session_count: Callable[[], int],+ ) -> None:+ self._telemetry = telemetry+ self._session_factory = session_factory+ self._interval = timedelta(hours=interval_hours)+ self._installed_at = installed_at+ # A callable rather than the registry: no business knowing what a+ # connection is.+ self._live_session_count = live_session_count++ async def run_forever(self) -> None:+ await asyncio.sleep(_FIRST_PASS_DELAY_SECONDS)+ while True:+ try:+ await self.run_once_if_due()+ except asyncio.CancelledError:+ raise+ except Exception:+ # One bad pass must not end the loop — a transient database+ # error would otherwise switch telemetry off for the life of+ # the process, silently.+ logger.exception("Usage snapshot pass failed")+ await asyncio.sleep(_POLL_INTERVAL_SECONDS)++ async def run_once_if_due(self) -> bool:+ """Send a snapshot if one is due. True if one was sent."""+ now = datetime.now(UTC)+ last_sent = await self._read_watermark()+ if last_sent is not None and now - last_sent < self._interval:+ return False+ await self.run_once(now=now, since=last_sent)+ await self._write_watermark(now)+ return True++ async def run_once(self, *, now: datetime, since: datetime | None) -> None:+ """Collect and report one snapshot, plus any room that just went live."""+ counts = await collect_usage(self._session_factory, now=now)++ # Skipped entirely on the first pass — see the module docstring.+ active = (+ await newly_active_rooms(self._session_factory, since=since, now=now)+ if since is not None+ else []+ )++ logger.info("Usage snapshot: %s", summarise(counts, active))++ self._telemetry.emit(+ "usage_snapshot",+ **counts.as_event_properties(+ session_live_count=int(self._live_session_count())+ ),+ )++ for room in active:+ self._telemetry.emit(+ "room_became_active",+ seconds_since_room_created=room.seconds_since_room_created,+ bridge_platform=room.bridge_platform,+ channel_type=room.channel_type,+ agent_count=room.agent_count,+ created_by_kind=room.created_by_kind,+ )++ await self._report_first_room_active(active)++ async def _report_first_room_active(self, active: list) -> None:+ """The activation milestone: the first room a person actually used.++ Fires once, so all three of these are permanent if wrong. Measured from+ the interaction, not from this pass, which is always late in the same+ direction. The *earliest* room, not the quickest. And user-created+ only, matching `first_room_created`.+ """+ by_a_person = [room for room in active if room.created_by_kind == "user"]+ if not by_a_person or self._installed_at is None:+ return+ # Not `emit_milestone`, because the elapsed time comes from the room+ # rather than from now — so its enabled gate is applied here instead.+ if not self._telemetry.enabled:+ return++ earliest = min(by_a_person, key=lambda room: room.first_active_at)+ elapsed = (+ earliest.first_active_at - as_utc(self._installed_at)+ ).total_seconds()+ if not await claim_milestone(self._session_factory, "first_room_active"):+ return+ self._telemetry.emit(+ "first_room_active",+ seconds_since_install=max(elapsed, 0.0),+ bridge_platform=earliest.bridge_platform,+ seconds_since_room_created=earliest.seconds_since_room_created,+ )++ async def _read_watermark(self) -> datetime | None:+ async with self._session_factory() as session:+ row = (+ await session.execute(select(TelemetrySnapshotWatermark).limit(1))+ ).scalar_one_or_none()+ if row is None:+ return None+ stamp = row.last_sent_at+ return stamp.replace(tzinfo=UTC) if stamp.tzinfo is None else stamp++ async def _write_watermark(self, when: datetime) -> None:+ async with self._session_factory() as session:+ await session.execute(+ pg_insert(TelemetrySnapshotWatermark)+ .values(id=1, last_sent_at=when)+ .on_conflict_do_update(+ index_elements=["id"], set_={"last_sent_at": when}+ )+ )+ await session.commit()diff --git a/core/switch_core/telemetry/service.py b/core/switch_core/telemetry/service.pynew file mode 100644index 000000000..1391177b9--- /dev/null+++ b/core/switch_core/telemetry/service.py@@ -0,0 +1,185 @@+"""The one call every site uses to report an event.++`emit` is fire-and-forget and synchronous to call: creating a room must not+wait on a relay. It validates against the catalogue first, then hands the send+to a background task.++The asymmetry is deliberate. **A bad event raises** — it is a programming error+and silence would defeat the catalogue. **A failed send does not** — it is+logged and dropped.+"""++from __future__ import annotations++import asyncio+import logging+import time+from collections.abc import Mapping+from datetime import datetime++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.telemetry.catalogue import PropertyValue, validate, wire_name+from switch_core.telemetry.deployment import claim_milestone, seconds_since_install+from switch_core.telemetry.sink import TelemetryRecord, TelemetrySink++logger = logging.getLogger(__name__)+++class TelemetryService:+ """Validates, tags and dispatches events.++ Holds a sink unconditionally — :class:`~switch_core.telemetry.sink.NullSink`+ when telemetry is off — so that no call site ever tests whether reporting+ is enabled. One place decides; everywhere else just reports.+ """++ def __init__(+ self,+ *,+ sink: TelemetrySink,+ enabled: bool,+ client_id: str,+ service_name: str,+ version: str | None,+ environment: str | None,+ session_factory: async_sessionmaker[AsyncSession] | None = None,+ installed_at: datetime | None = None,+ ) -> None:+ self._sink = sink+ self._enabled = enabled+ # Only the milestone path needs these. Optional so the ordinary+ # `emit` is usable from a test that has no database at all.+ self._session_factory = session_factory+ self._installed_at = installed_at+ self._resource = {+ "service.name": service_name,+ "flint.client_id": client_id,+ }+ # Omitted rather than sent empty: an absent attribute reads as "not+ # configured", where `""` reads as a real environment named nothing.+ if version:+ self._resource["service.version"] = version+ if environment:+ self._resource["deployment.environment"] = environment+ self._tasks: set[asyncio.Task[None]] = set()++ @property+ def enabled(self) -> bool:+ return self._enabled++ @property+ def installed_at(self) -> datetime | None:+ """When this deployment was installed, or None if that is unknown."""+ return self._installed_at++ def emit(self, event: str, **properties: PropertyValue) -> None:+ """Report one event. Never blocks; raises only on a malformed event."""+ # Validated even when disabled, so a mistake in a rarely-taken branch+ # is caught by whichever test exercises it rather than lying dormant+ # until the day a deployment switches telemetry on.+ validate(event, properties)+ if not self._enabled:+ return+ self._dispatch(+ TelemetryRecord(+ name=wire_name(event),+ properties=dict(properties),+ resource=dict(self._resource),+ timestamp_ns=time.time_ns(),+ )+ )++ async def emit_milestone(self, event: str, **properties: PropertyValue) -> None:+ """Report a once-ever activation milestone, if it has not been reported.++ Adds `seconds_since_install` and takes the claim that makes it+ once-ever, so a call site only has to say which milestone it is and+ what else it carries.++ Silently does nothing in three cases, each of them correct:++ - **telemetry is off**, so there is nothing to report and no claim+ should be taken — switching it on later must not find every+ milestone already used up;+ - **the deployment predates this telemetry** and has no install date,+ so elapsed time is unknowable and a guess would be worse than+ silence (see `telemetry/deployment.py`);+ - **the milestone is already claimed**, which is the whole point.+ """+ if not self._enabled or self._session_factory is None:+ return+ elapsed = seconds_since_install(self._installed_at)+ if elapsed is None:+ return+ if not await claim_milestone(self._session_factory, event):+ return+ self.emit(event, seconds_since_install=elapsed, **properties)++ def _dispatch(self, record: TelemetryRecord) -> None:+ try:+ loop = asyncio.get_running_loop()+ except RuntimeError:+ # A management command or a sync helper; not its job to have one.+ logger.debug(+ "Telemetry event %s not sent: no running event loop.", record.name+ )+ return++ task = loop.create_task(self._send(record))+ # Held for the lifetime of the send. An un-referenced task can be+ # garbage-collected mid-flight, which drops the event silently and is+ # exactly the kind of bug telemetry code is bad at revealing.+ self._tasks.add(task)+ task.add_done_callback(self._tasks.discard)++ async def _send(self, record: TelemetryRecord) -> None:+ try:+ await self._sink.send(record)+ except asyncio.CancelledError:+ raise+ except Exception:+ # A bug in the sink, not a bad relay — but this is a bare task, so+ # letting it out only surfaces at some later collection.+ logger.exception("Telemetry sink failed on event %s", record.name)++ async def aclose(self) -> None:+ """Let in-flight sends finish, then close the sink.++ Shutdown is the one time waiting is right: the events worth losing+ least are the ones emitted just before the process goes away, and the+ sink's own timeout already bounds how long this can take.+ """+ if self._tasks:+ await asyncio.gather(*tuple(self._tasks), return_exceptions=True)+ await self._sink.aclose()+++def emit_safely(+ telemetry: TelemetryService | None,+ event: str,+ properties: Mapping[str, PropertyValue],+) -> None:+ """Report an event from a path that must not fail because of telemetry.++ For call sites in the middle of real work — creating a room, opening a+ session — where a catalogue bug must not take the operation down with it.+ The mistake is still loud, because it is logged with a stack trace at+ error level, but it costs the user nothing.++ Paths that can afford to fail (the snapshot task, tests) should call+ :meth:`TelemetryService.emit` directly and let the error out.++ `telemetry` is optional because several services are constructed in tests+ and in tooling without one.+ """+ if telemetry is None:+ return+ try:+ telemetry.emit(event, **dict(properties))+ except Exception:+ logger.exception(+ "Telemetry event %s could not be reported; continuing. This is a "+ "bug in the event, not a relay problem.",+ event,+ )diff --git a/core/switch_core/telemetry/setup.py b/core/switch_core/telemetry/setup.pynew file mode 100644index 000000000..0ca9b6bff--- /dev/null+++ b/core/switch_core/telemetry/setup.py@@ -0,0 +1,139 @@+"""Building the telemetry service at boot.++One function, so `main.py` does not have to know the difference between an+enabled deployment and a disabled one — it asks for a service and gets one+either way. Off is a service holding a sink that discards, not a `None` that+every call site would have to remember to check.+"""++from __future__ import annotations++import logging+from datetime import datetime++import httpx+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.config import SwitchConfig+from switch_core.observability.otlp import OtlpClient+from switch_core.telemetry.deployment import load_deployment_identity+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.sink import NullSink, OtlpRelaySink, TelemetrySink++logger = logging.getLogger(__name__)+++async def build_telemetry(+ config: SwitchConfig,+ session_factory: async_sessionmaker[AsyncSession],+ version: str | None,+) -> tuple[TelemetryService, datetime | None, httpx.AsyncClient | None]:+ """The telemetry service, the deployment's install date, and its HTTP client.++ The install date rides along because it is read from the same row. The+ client comes back so `main` can close it.++ Resolved even when telemetry is off, so a deployment that opts in later+ already has the id it was assigned at install.+ """+ try:+ generated_id, installed_at = await load_deployment_identity(session_factory)+ except Exception:+ # Never fatal: refusing to serve over analytics is the one thing this+ # must not do. Disabled rather than given an invented id, which would+ # make one deployment look like a population of installs.+ logger.error(+ "Could not read the deployment identity, so product telemetry is "+ "disabled for this run. Its row is seeded by the telemetry "+ "bookkeeping migration — check that migrations have been applied.",+ exc_info=True,+ )+ return (+ _service(+ config,+ NullSink(),+ client_id="",+ version=version,+ session_factory=session_factory,+ installed_at=None,+ enabled=False,+ ),+ None,+ None,+ )++ # Both streams send `flint.client_id`, so a deployment reporting both must+ # be one subject downstream. The operator's value wins; the generated one+ # cannot be copied between deployments and carries the install date.+ client_id = config.deployment_id or generated_id++ if not config.telemetry_enabled:+ logger.info(+ "Product telemetry is off; nothing is collected or sent. Set "+ "TELEMETRY_ENABLED=true to report anonymous usage counts."+ )+ return (+ _service(+ config,+ NullSink(),+ client_id=client_id,+ version=version,+ session_factory=session_factory,+ installed_at=installed_at,+ ),+ installed_at,+ None,+ )++ http_client = httpx.AsyncClient()+ sink: TelemetrySink = OtlpRelaySink(+ client=OtlpClient(+ base_endpoint=config.telemetry_endpoint,+ timeout_seconds=config.telemetry_timeout_seconds,+ headers={},+ client=http_client,+ )+ )+ logger.info(+ "Product telemetry is ON: usage counts and timings are reported to "+ "%s. No room, tenant, agent, user or message is identified in them — "+ "see docs/old/telemetry-events.md for exactly what is sent. Set "+ "TELEMETRY_ENABLED=false to switch it off.",+ config.telemetry_endpoint,+ )+ return (+ _service(+ config,+ sink,+ client_id=client_id,+ version=version,+ session_factory=session_factory,+ installed_at=installed_at,+ ),+ installed_at,+ http_client,+ )+++def _service(+ config: SwitchConfig,+ sink: TelemetrySink,+ *,+ client_id: str,+ version: str | None,+ session_factory: async_sessionmaker[AsyncSession],+ installed_at: datetime | None,+ enabled: bool | None = None,+) -> TelemetryService:+ """`enabled` overrides the setting for the one case that has to: with no+ identity, every event would carry no deployment and be dropped."""+ return TelemetryService(+ sink=sink,+ enabled=config.telemetry_enabled if enabled is None else enabled,+ client_id=client_id,+ service_name=config.service_name,+ version=version,+ environment=config.environment,+ session_factory=session_factory,+ installed_at=installed_at,+ )diff --git a/core/switch_core/telemetry/sink.py b/core/switch_core/telemetry/sink.pynew file mode 100644index 000000000..562cc4d60--- /dev/null+++ b/core/switch_core/telemetry/sink.py@@ -0,0 +1,139 @@+"""Where a validated event actually goes: the only thing that knows there is an+HTTP request involved.++The wire format belongs to `switch_core.observability.otlp`, shared with the+operational export. What is here is what a product event needs on top: the+`eventName` field the relay's exporter reads, and a failure policy that never+lets a reporting problem reach the caller.+"""++from __future__ import annotations++import logging+from dataclasses import dataclass+from typing import Any, Protocol++from switch_core.observability.otlp import (+ LogRecord,+ OtlpClient,+ OtlpResource,+ OtlpSendError,+ build_logs_payload,+)+from switch_core.telemetry.catalogue import PropertyValue++logger = logging.getLogger(__name__)++# OTLP's severity number for INFO. A product event is not a log line, but the+# relay carries it as one, and a record with no severity is rendered by some+# receivers as an error.+_SEVERITY_INFO = 9+++@dataclass(frozen=True)+class TelemetryRecord:+ """One validated event, ready to send.++ `name` is already prefixed. `properties` has already been checked against+ the catalogue: a sink must not have to trust or re-check its caller, and+ must never be the thing that decides what is allowed to leave.+ """++ name: str+ properties: dict[str, PropertyValue]+ resource: dict[str, str]+ timestamp_ns: int+++class TelemetrySink(Protocol):+ """The seam. One method, and it never raises."""++ async def send(self, record: TelemetryRecord) -> None: ...++ async def aclose(self) -> None: ...+++class NullSink:+ """Drops everything. Off is a sink that discards, so no call site has to+ ask whether telemetry is on."""++ async def send(self, record: TelemetryRecord) -> None:+ return None++ async def aclose(self) -> None:+ return None+++class OtlpRelaySink:+ """Posts one OTLP log record per event to the relay.++ Log records, not metrics: the relay routes on them and the analytics+ exporter reads them as events. A metric would be dropped without complaint.++ **The event name goes in two places** — the record's `eventName` field and+ an `event.name` attribute. The relay filters on the attribute, the exporter+ reads the field, and sending only one is accepted with a 200 at every hop+ and then discarded. That is the easiest way to believe this works when it+ does not.++ No batching and no retry, matching the operational exporter.+ """++ def __init__(self, *, client: OtlpClient) -> None:+ self._client = client++ async def send(self, record: TelemetryRecord) -> None:+ payload = build_logs_payload(+ [+ LogRecord(+ # Datadog renders this as the log message, and a blank one+ # makes the event unreadable there.+ body=record.name,+ severity_text="INFO",+ severity_number=_SEVERITY_INFO,+ time_nanos=record.timestamp_ns,+ attributes={"event.name": record.name, **record.properties},+ )+ ],+ _resource_from(record),+ )+ _add_event_name(payload, record.name)++ try:+ await self._client.post("logs", payload)+ except OtlpSendError as exc:+ # Switch has to keep working while analytics is down.+ logger.warning(+ "Telemetry event %s was not sent: %s. The event is dropped; "+ "there is no retry.",+ record.name,+ exc,+ )++ async def aclose(self) -> None:+ # `telemetry/setup.py` opens the client and `main._drain_telemetry`+ # closes it, under a timeout shutdown depends on.+ return None+++def _resource_from(record: TelemetryRecord) -> OtlpResource:+ """The record's resource attributes, as the shared encoder wants them.++ Rebuilt here rather than in the service, so only this file depends on the+ observability package.+ """+ return OtlpResource(+ service_name=record.resource["service.name"],+ service_version=record.resource.get("service.version"),+ environment=record.resource.get("deployment.environment"),+ deployment_id=record.resource["flint.client_id"],+ )+++def _add_event_name(payload: dict[str, Any], name: str) -> None:+ """Set the record's own `eventName` field, which `build_logs_payload` does+ not: an operational log line has no event name."""+ for resource_log in payload["resourceLogs"]:+ for scope_log in resource_log["scopeLogs"]:+ for record in scope_log["logRecords"]:+ record["eventName"] = namediff --git a/core/switch_core/telemetry/snapshot.py b/core/switch_core/telemetry/snapshot.pynew file mode 100644index 000000000..54973f93a--- /dev/null+++ b/core/switch_core/telemetry/snapshot.py@@ -0,0 +1,727 @@+"""The daily usage snapshot, and the room-activation events derived with it.++Counting here rather than emitting per occurrence is what lets these questions+be answered with no room, tenant or person identified: the ids stay in the+database and only totals leave.++**Counted per tenant and summed**, because row-level security requires it — a+session with nothing bound reads nothing from a scoped table, so an unscoped+`COUNT` answers zero on a correctly configured deployment.++Room activation is derived here rather than detected at write time, which+would need a per-room flag and three extra queries on the hottest path to learn+something nobody needs within a day.+"""++from __future__ import annotations++import logging+from collections.abc import Sequence+from dataclasses import dataclass, field+from datetime import UTC, datetime, timedelta+from typing import Any++from sqlalchemy import Select, and_, case, distinct, exists, func, select+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import (+ Agent,+ ApiKey,+ Client,+ ClientRoom,+ CollaborationBridge,+ Document,+ Message,+ MessageAttachment,+ Package,+ Reference,+ Room,+ RoomGroup,+ User,+ room_documents,+ room_references,+)+from switch_core.db.session_scope import tenant_session+from switch_core.db.tenant_lookup import all_tenant_ids++logger = logging.getLogger(__name__)++# `clients.type` for a human: one puppet per external user per bridge, and the+# only row in the schema that stands for "a person did something".+HUMAN_CLIENT_TYPE = "user"+AGENT_CLIENT_TYPE = "agent"++# The platforms reported individually. Fixed rather than derived from what is+# configured, so a deployment with no Discord bridge reports zero rather than+# omitting the property — the catalogue requires every key every time.+PLATFORMS = ("slack", "mattermost", "discord", "teams", "telegram")++_DAY = timedelta(days=1)+# How far back the turn pairing looks for a message's predecessor. See+# `_collect_turns`.+_TURN_LOOKBACK = timedelta(days=2)+_WEEK = timedelta(days=7)+++@dataclass+class UsageCounts:+ """The snapshot's numbers, accumulated across tenants."""++ tenant_count: int = 0+ user_count: int = 0+ user_active_1d: int = 0+ user_active_7d: int = 0+ room_count: int = 0+ room_agent_created_count: int = 0+ room_system_created_count: int = 0+ room_active_1d: int = 0+ room_active_7d: int = 0+ room_archived_count: int = 0+ room_internal_only_count: int = 0+ room_membership_total: int = 0+ room_users_max: int = 0+ agent_count: int = 0+ agent_active_7d: int = 0+ agent_claude_code_count: int = 0+ agent_codex_count: int = 0+ agent_opencode_count: int = 0+ agent_other_count: int = 0+ connector_configured_count: int = 0+ connector_counts: dict[str, int] = field(+ default_factory=lambda: dict.fromkeys(PLATFORMS, 0)+ )+ message_count_1d: int = 0+ message_from_human_1d: int = 0+ message_from_agent_1d: int = 0+ turn_human_to_agent_1d: int = 0+ turn_agent_to_human_1d: int = 0+ turn_agent_to_agent_1d: int = 0+ attachment_count_1d: int = 0+ reference_count: int = 0+ reference_attached_count: int = 0+ document_count: int = 0+ document_attached_count: int = 0+ package_count: int = 0+ room_group_count: int = 0+ api_key_count: int = 0++ def as_event_properties(self, *, session_live_count: int) -> dict[str, float]:+ """Flatten to exactly the properties `usage_snapshot` declares."""+ properties: dict[str, float] = {+ "tenant_count": self.tenant_count,+ "user_count": self.user_count,+ "user_active_1d": self.user_active_1d,+ "user_active_7d": self.user_active_7d,+ "room_count": self.room_count,+ "room_agent_created_count": self.room_agent_created_count,+ "room_system_created_count": self.room_system_created_count,+ "room_active_1d": self.room_active_1d,+ "room_active_7d": self.room_active_7d,+ "room_archived_count": self.room_archived_count,+ "room_internal_only_count": self.room_internal_only_count,+ "room_membership_total": self.room_membership_total,+ "room_users_mean": (+ round(self.room_membership_total / self.room_count, 2)+ if self.room_count+ else 0.0+ ),+ "room_users_max": self.room_users_max,+ "agent_count": self.agent_count,+ "agent_active_7d": self.agent_active_7d,+ "agent_claude_code_count": self.agent_claude_code_count,+ "agent_codex_count": self.agent_codex_count,+ "agent_opencode_count": self.agent_opencode_count,+ "agent_other_count": self.agent_other_count,+ "session_live_count": session_live_count,+ "connector_configured_count": self.connector_configured_count,+ "message_count_1d": self.message_count_1d,+ "message_from_human_1d": self.message_from_human_1d,+ "message_from_agent_1d": self.message_from_agent_1d,+ "turn_human_to_agent_1d": self.turn_human_to_agent_1d,+ "turn_agent_to_human_1d": self.turn_agent_to_human_1d,+ "turn_agent_to_agent_1d": self.turn_agent_to_agent_1d,+ "attachment_count_1d": self.attachment_count_1d,+ "reference_count": self.reference_count,+ "reference_attached_count": self.reference_attached_count,+ "document_count": self.document_count,+ "document_attached_count": self.document_attached_count,+ "package_count": self.package_count,+ "room_group_count": self.room_group_count,+ "api_key_count": self.api_key_count,+ }+ for platform in PLATFORMS:+ properties[f"connector_{platform}_count"] = self.connector_counts[platform]+ return properties+++@dataclass(frozen=True)+class NewlyActiveRoom:+ """A room whose first human interaction happened in the window just read."""++ # The milestone is measured from this, not from when the pass ran: a pass+ # is up to a whole interval late, always in the same direction.+ first_active_at: datetime+ seconds_since_room_created: float+ bridge_platform: str+ channel_type: str+ agent_count: int+ created_by_kind: str+++def _room_has_an_agent(tenant_id: str) -> Select[tuple[str]]:+ """Correlated subquery: the message's room has an agent in it."""+ return (+ select(ClientRoom.room_id)+ .join(Client, Client.id == ClientRoom.client_id)+ .where(+ ClientRoom.room_id == Message.room_id,+ ClientRoom.tenant_id == tenant_id,+ Client.type == AGENT_CLIENT_TYPE,+ Client.tenant_id == tenant_id,+ )+ )+++def _human_interaction(tenant_id: str, since: datetime) -> Select[tuple[str]]:+ """Room ids a human spoke in since `since`.++ "Interaction" is a human posting in a room that has an agent in it. Both+ halves matter: a message from a bridge relay or the admin client is not a+ person, and a person talking in a room with no agent is not using the+ product this telemetry is about. Two agents talking to each other is+ likewise not activity, which is why this keys on the human side only.+ """+ return (+ select(distinct(Message.room_id))+ .join(Client, Client.id == Message.sender_client_id)+ .where(+ Message.tenant_id == tenant_id,+ Message.sent_at >= since,+ Client.type == HUMAN_CLIENT_TYPE,+ Client.tenant_id == tenant_id,+ exists(_room_has_an_agent(tenant_id)),+ )+ )+++def _active_humans(tenant_id: str, since: datetime) -> Select[tuple[str | None]]:+ """Distinct human clients who interacted since `since`."""+ return (+ select(distinct(Message.sender_client_id))+ .join(Client, Client.id == Message.sender_client_id)+ .where(+ Message.tenant_id == tenant_id,+ Message.sent_at >= since,+ Client.type == HUMAN_CLIENT_TYPE,+ Client.tenant_id == tenant_id,+ exists(_room_has_an_agent(tenant_id)),+ )+ )+++async def _count(session: AsyncSession, query: Select[Any]) -> int:+ result = await session.execute(select(func.count()).select_from(query.subquery()))+ return int(result.scalar_one())+++async def _scalar(session: AsyncSession, query: Select[Any]) -> int:+ result = await session.execute(query)+ return int(result.scalar_one() or 0)+++async def collect_tenant_counts(+ session: AsyncSession, tenant_id: str, counts: UsageCounts, now: datetime+) -> None:+ """Add one tenant's numbers to `counts`.++ The session must already be bound to `tenant_id`, **and** every query names+ the tenant explicitly as well. That looks redundant and is not: the policy+ is what does not apply on an owner connection, so a read that leans on it+ alone returns every tenant's rows on every pass and a fan-out over N+ tenants counts each row N times. `db/tenant_lookup.py` states the rule and+ every other fan-out in the tree follows it — this is a count, so the+ duplication would be silent rather than visible.+ """+ day_ago = now - _DAY+ week_ago = now - _WEEK++ counts.user_active_1d += await _count(session, _active_humans(tenant_id, day_ago))+ counts.user_active_7d += await _count(session, _active_humans(tenant_id, week_ago))+ counts.room_active_1d += await _count(+ session, _human_interaction(tenant_id, day_ago)+ )+ counts.room_active_7d += await _count(+ session, _human_interaction(tenant_id, week_ago)+ )++ # A room predating the stamp reads as user-created, the conservative+ # answer. `system` is a channel Switch was invited to; folding those in+ # would make the headline mean "channels this workspace happens to have".+ kind = Room.metadata_["created_by_kind"].astext+ live = (Room.tenant_id == tenant_id, Room.archived_at.is_(None))+ counts.room_count += await _scalar(+ session,+ select(func.count())+ .select_from(Room)+ .where(*live, (kind == "user") | kind.is_(None)),+ )+ counts.room_agent_created_count += await _scalar(+ session, select(func.count()).select_from(Room).where(*live, kind == "agent")+ )+ counts.room_system_created_count += await _scalar(+ session, select(func.count()).select_from(Room).where(*live, kind == "system")+ )+ counts.room_archived_count += await _scalar(+ session,+ select(func.count())+ .select_from(Room)+ .where(Room.tenant_id == tenant_id, Room.archived_at.is_not(None)),+ )+ counts.room_internal_only_count += await _scalar(+ session,+ select(func.count()).select_from(Room).where(*live, Room.bridge_id.is_(None)),+ )++ # Human membership per room, as a total and a maximum. The mean is derived+ # from the total rather than averaged per tenant, so a deployment with one+ # busy tenant and one idle one reports the real figure instead of the mean+ # of two means.+ # Same population as `room_count`, since the mean divides one by the+ # other — different populations can report a mean above the maximum.+ per_room = (+ select(func.count(ClientRoom.client_id).label("members"))+ .join(Client, Client.id == ClientRoom.client_id)+ .join(Room, Room.id == ClientRoom.room_id)+ .where(+ ClientRoom.tenant_id == tenant_id,+ Client.tenant_id == tenant_id,+ Client.type == HUMAN_CLIENT_TYPE,+ *live,+ (kind == "user") | kind.is_(None),+ )+ .group_by(ClientRoom.room_id)+ .subquery()+ )+ membership = await session.execute(+ select(+ func.coalesce(func.sum(per_room.c.members), 0),+ func.coalesce(func.max(per_room.c.members), 0),+ )+ )+ total, largest = membership.one()+ counts.room_membership_total += int(total)+ counts.room_users_max = max(counts.room_users_max, int(largest))++ # Agents, split by the runtime behind them.+ runtime = Agent.metadata_["known_agent_type"].astext+ by_runtime = await session.execute(+ select(runtime, func.count())+ .select_from(Agent)+ .where(Agent.tenant_id == tenant_id)+ .group_by(runtime)+ )+ for name, count in by_runtime.all():+ if name == "claude-code":+ counts.agent_claude_code_count += count+ elif name == "codex":+ counts.agent_codex_count += count+ elif name == "opencode":+ counts.agent_opencode_count += count+ else:+ counts.agent_other_count += count+ counts.agent_count += count++ counts.agent_active_7d += await _count(+ session,+ select(distinct(Message.sender_client_id))+ .join(Client, Client.id == Message.sender_client_id)+ .where(+ Message.tenant_id == tenant_id,+ Message.sent_at >= week_ago,+ Client.type == AGENT_CLIENT_TYPE,+ Client.tenant_id == tenant_id,+ ),+ )++ # Connectors, by platform. Configured, not connected — whether each is+ # currently up is process state, added by the caller.+ by_platform = await session.execute(+ select(CollaborationBridge.type, func.count())+ .select_from(CollaborationBridge)+ .where(CollaborationBridge.tenant_id == tenant_id)+ .group_by(CollaborationBridge.type)+ )+ for platform, count in by_platform.all():+ counts.connector_configured_count += count+ if platform in counts.connector_counts:+ counts.connector_counts[platform] += count++ # Messages in the last day, and who sent them. Only live messages: `seq`+ # is negative for reconstructed history, and a backfill is not traffic.+ counts.message_count_1d += await _scalar(+ session,+ select(func.count())+ .select_from(Message)+ .where(+ Message.tenant_id == tenant_id, Message.sent_at >= day_ago, Message.seq > 0+ ),+ )+ by_sender = await session.execute(+ select(Client.type, func.count())+ .select_from(Message)+ .join(Client, Client.id == Message.sender_client_id)+ .where(+ Message.tenant_id == tenant_id,+ Message.sent_at >= day_ago,+ Message.seq > 0,+ Client.tenant_id == tenant_id,+ )+ .group_by(Client.type)+ )+ for client_type, count in by_sender.all():+ if client_type == HUMAN_CLIENT_TYPE:+ counts.message_from_human_1d += count+ elif client_type == AGENT_CLIENT_TYPE:+ counts.message_from_agent_1d += count++ await _collect_resource_counts(session, tenant_id, counts)++ await _collect_turns(session, tenant_id, counts, day_ago)++ counts.attachment_count_1d += await _scalar(+ session,+ select(func.count())+ .select_from(MessageAttachment)+ .join(Message, Message.id == MessageAttachment.message_id)+ .where(+ MessageAttachment.tenant_id == tenant_id,+ Message.tenant_id == tenant_id,+ Message.sent_at >= day_ago,+ ),+ )+++async def _collect_resource_counts(+ session: AsyncSession, tenant_id: str, counts: UsageCounts+) -> None:+ """What the tenant has built up, and how much of it is actually in a room.++ The attached figures are the point. A library of references nobody ever+ attached and one attached to every room are the same number under+ `reference_count`, and they mean opposite things about whether the feature+ is working.+ """+ for table, name in (+ (Reference, "reference_count"),+ (Document, "document_count"),+ (Package, "package_count"),+ (RoomGroup, "room_group_count"),+ (ApiKey, "api_key_count"),+ ):+ setattr(+ counts,+ name,+ getattr(counts, name)+ + await _scalar(+ session,+ select(func.count())+ .select_from(table)+ .where(table.tenant_id == tenant_id),+ ),+ )++ for junction, column, name in (+ (room_references, "reference_id", "reference_attached_count"),+ (room_documents, "document_id", "document_attached_count"),+ ):+ setattr(+ counts,+ name,+ getattr(counts, name)+ + await _scalar(+ session,+ select(func.count(distinct(junction.c[column]))).where(+ junction.c.tenant_id == tenant_id+ ),+ ),+ )+++async def _collect_turns(+ session: AsyncSession, tenant_id: str, counts: UsageCounts, since: datetime+) -> None:+ """Who replied to whom, in the window.++ A turn is a message paired with the one before it in the same room, so the+ pairing is read off `seq` — which is a total order within a room with no+ ties, assigned in commit order, and therefore the only ordering where+ "the previous message" means what it says. A timestamp would tie.++ Only three pairings are counted, and the ones left out are deliberate:+ human→human is two people talking with no agent involved, and a turn whose+ predecessor is a bridge relay or the admin client is machinery rather than+ conversation. The first message in a room has no predecessor and is not a+ turn at all.++ The window is applied to the *current* message, not the pair, so a reply+ this morning to a question asked last night still counts — which is the+ right reading of "turns today", and avoids a turn falling through the gap+ between two windows.+ """+ kind = case(+ (Client.type == HUMAN_CLIENT_TYPE, "human"),+ (Client.type == AGENT_CLIENT_TYPE, "agent"),+ else_="other",+ )+ paired = (+ select(+ kind.label("sender"),+ Message.sender_client_id.label("sender_id"),+ func.lag(kind)+ .over(partition_by=Message.room_id, order_by=Message.seq)+ .label("previous"),+ func.lag(Message.sender_client_id)+ .over(partition_by=Message.room_id, order_by=Message.seq)+ .label("previous_id"),+ Message.sent_at.label("sent_at"),+ )+ .select_from(Message)+ .join(Client, Client.id == Message.sender_client_id)+ .where(+ Message.tenant_id == tenant_id,+ Client.tenant_id == tenant_id,+ Message.seq > 0,+ # Bounded, or the window covers the tenant's whole history every+ # pass. The outer `sent_at` filter cannot be pushed in: the window+ # partitions by room, so narrowing the input would change which+ # message counts as the predecessor. The lookback is wider than the+ # window so a reply to yesterday still finds what it answered.+ Message.sent_at >= since - _TURN_LOOKBACK,+ )+ .subquery()+ )+ rows = await session.execute(+ select(paired.c.sender, paired.c.previous, func.count())+ .where(+ paired.c.sent_at >= since,+ paired.c.previous.is_not(None),+ # A reply needs two participants: without this an agent answering+ # across three messages scores as two agent-to-agent turns.+ paired.c.sender_id != paired.c.previous_id,+ )+ .group_by(paired.c.sender, paired.c.previous)+ )+ for sender, previous, count in rows.all():+ if sender == "agent" and previous == "human":+ counts.turn_human_to_agent_1d += count+ elif sender == "human" and previous == "agent":+ counts.turn_agent_to_human_1d += count+ elif sender == "agent" and previous == "agent":+ counts.turn_agent_to_agent_1d += count+++async def room_had_human_activity(+ session: AsyncSession, tenant_id: str, room_id: str+) -> bool:+ """Whether a human has ever posted in this room.++ The session must already be bound to `tenant_id`; the predicate is named+ anyway, for the reason `collect_tenant_counts` gives.+ """+ found = await session.execute(+ select(Message.id)+ .join(Client, Client.id == Message.sender_client_id)+ .where(+ Message.tenant_id == tenant_id,+ Message.room_id == room_id,+ Message.seq > 0,+ Client.type == HUMAN_CLIENT_TYPE,+ Client.tenant_id == tenant_id,+ )+ .limit(1)+ )+ return found.scalar_one_or_none() is not None+++async def collect_usage(+ session_factory: async_sessionmaker[AsyncSession], *, now: datetime | None = None+) -> UsageCounts:+ """Every tenant's numbers, summed into one set of deployment totals."""+ moment = now or datetime.now(UTC)+ counts = UsageCounts()+ tenant_ids = await all_tenant_ids(session_factory)+ counts.tenant_count = len(tenant_ids)+ for tenant_id in tenant_ids:+ async with tenant_session(session_factory, tenant_id) as session:+ await collect_tenant_counts(session, tenant_id, counts, moment)+ # `users` carries no tenant, so it is counted once for the deployment+ # rather than per tenant — summing a global table over tenants would+ # multiply it by however many there are.+ async with session_factory() as session:+ counts.user_count = await _scalar(+ session, select(func.count()).select_from(User)+ )+ return counts+++async def newly_active_rooms(+ session_factory: async_sessionmaker[AsyncSession],+ *,+ since: datetime,+ now: datetime | None = None,+) -> list[NewlyActiveRoom]:+ """Rooms whose *first* human interaction happened after `since`.++ The window is what makes this once-per-room without storing anything: a+ room qualifies only if its earliest human message falls inside it, and each+ window starts where the last one ended. A room that was already active+ before `since` has an earlier first message and is skipped for good.++ The cost of that is a room can be reported late — up to one window — and+ cannot be reported at all if the deployment was down when the window that+ covered it would have run. Both are acceptable for a figure nobody reads+ inside a day, and neither can produce a duplicate.+ """+ moment = now or datetime.now(UTC)+ found: list[NewlyActiveRoom] = []++ for tenant_id in await all_tenant_ids(session_factory):+ async with tenant_session(session_factory, tenant_id) as session:+ first_interaction = (+ select(+ Message.room_id.label("room_id"),+ func.min(Message.sent_at).label("first_at"),+ )+ .join(Client, Client.id == Message.sender_client_id)+ .where(+ Message.tenant_id == tenant_id,+ Client.tenant_id == tenant_id,+ Client.type == HUMAN_CLIENT_TYPE,+ Message.seq > 0,+ )+ .group_by(Message.room_id)+ .subquery()+ )+ agent_count = (+ select(func.count())+ .select_from(ClientRoom)+ .join(Client, Client.id == ClientRoom.client_id)+ .where(+ ClientRoom.room_id == Room.id,+ ClientRoom.tenant_id == tenant_id,+ Client.type == AGENT_CLIENT_TYPE,+ Client.tenant_id == tenant_id,+ )+ .scalar_subquery()+ )+ rows = await session.execute(+ select(+ Room.created_at,+ first_interaction.c.first_at,+ Room.channel_type,+ Room.bridge_id,+ Room.metadata_["created_by_kind"].astext,+ agent_count,+ )+ .join(first_interaction, first_interaction.c.room_id == Room.id)+ .where(+ and_(+ Room.tenant_id == tenant_id,+ first_interaction.c.first_at > since,+ first_interaction.c.first_at <= moment,+ )+ )+ )++ platforms = await _bridge_platforms(session)+ for created_at, first_at, channel_type, bridge_id, kind, agents in rows:+ found.append(+ NewlyActiveRoom(+ first_active_at=as_utc(first_at),+ seconds_since_room_created=max(+ (first_at - created_at).total_seconds(), 0.0+ ),+ bridge_platform=normalise_platform(platforms.get(bridge_id)),+ channel_type=normalise_channel_type(channel_type),+ agent_count=int(agents or 0),+ created_by_kind=normalise_actor_kind(kind),+ )+ )+ return found+++async def _bridge_platforms(session: AsyncSession) -> dict[str | None, str]:+ """Bridge id → platform, for the tenant this session is bound to."""+ rows = await session.execute(+ select(CollaborationBridge.id, CollaborationBridge.type)+ )+ return {bridge_id: platform for bridge_id, platform in rows.all()}+++def as_utc(moment: datetime) -> datetime:+ """A timestamp column as an aware UTC datetime."""+ return moment if moment.tzinfo else moment.replace(tzinfo=UTC)+++def normalise_actor_kind(kind: str | None) -> str:+ """A stamped `created_by_kind` as the catalogue spells it.++ Rooms predating the stamp carry nothing and read as `user`, the same+ conservative default the room counts use. Anything unrecognised reads as+ `system` rather than raising: an unknown origin is machinery, and a room+ creation must not fail because a later kind was added without touching+ this file.+ """+ if kind in ("user", "agent", "system"):+ return str(kind)+ return "user" if kind is None else "system"+++def normalise_channel_type(channel_type: str | None) -> str:+ """A `rooms.channel_type` as the catalogue spells it.++ The column predates the catalogue and carries a value the closed set does+ not: `group`, the pre-rename name for a private channel (see the+ `rename channel types` migration). Mapped rather than passed through,+ because an unmapped value would raise at the point of emission and take a+ room creation down with it.+ """+ if channel_type in ("channel_public", "channel_private", "direct"):+ return str(channel_type)+ if channel_type == "group":+ return "channel_private"+ if channel_type == "channel":+ return "channel_public"+ return "none"+++def normalise_platform(platform: str | None) -> str:+ """A bridge type as the catalogue spells it."""+ return platform if platform in PLATFORMS else "none"+++def normalise_known_agent_type(metadata: dict | None) -> str:+ """The runtime behind an agent, as the catalogue spells it."""+ if not metadata:+ return "none"+ declared = metadata.get("known_agent_type")+ if declared is None:+ return "none"+ if declared in ("claude-code", "codex", "opencode"):+ return str(declared)+ return "other"+++def summarise(counts: UsageCounts, active: Sequence[NewlyActiveRoom]) -> str:+ """A one-line log of what a snapshot pass found, for the server's own log.++ Worth logging even when telemetry is switched off: an operator asking "what+ would this send?" should be able to answer it from the log rather than by+ reading the code or by turning reporting on to find out.+ """+ return (+ f"rooms={counts.room_count} active_7d={counts.room_active_7d} "+ f"users={counts.user_count} active_users_7d={counts.user_active_7d} "+ f"agents={counts.agent_count} messages_1d={counts.message_count_1d} "+ f"newly_active_rooms={len(active)}"+ )diff --git a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.pyindex 6e5563d2a..cdcaf0fe9 100644--- a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py+++ b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py@@ -15,6 +15,7 @@ from fastapi import HTTPExceptionfrom starlette.responses import StreamingResponsefrom switch_core.bridges.agent.api.handlers import _resolve_start_cursor, poll_events+from switch_core.bridges.agent.api.session_reporter import SessionReporterfrom switch_core.bridges.agent.protocol.connections import (PROTOCOL_ACCEPTS,PROTOCOL_VERSION,@@ -30,6 +31,10 @@ class _Protocol:def __init__(self) -> None:self.event_buffer = EventBuffer()self.connections = ConnectionRegistry()+ # Opening and closing a stream reports a session; a reporter with no+ # telemetry service reports nothing, which is what these tests want.+ self.telemetry = None+ self.sessions = SessionReporter(None)self.polled = Falseself.recorded: list[tuple[str, str, ClientDeclaration]] = []@@ -47,7 +52,8 @@ class _Protocol:def _agent() -> Any:- return SimpleNamespace(id=AGENT_ID)+ # `metadata_` carries the agent's runtime, which opening a stream reports.+ return SimpleNamespace(id=AGENT_ID, metadata_={"known_agent_type": "claude-code"})async def _call(protocol: _Protocol, **kw: Any) -> Any:diff --git a/core/tests/switch_core/bridges/agent/protocol/test_room_detail.py b/core/tests/switch_core/bridges/agent/protocol/test_room_detail.pyindex ef476aff5..9f26e4d24 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_room_detail.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_room_detail.py@@ -174,6 +174,16 @@ def _build_service(return resolved_rolessvc.list_room_roles = _fake_roles # type: ignore[assignment]++ # Archiving goes through RoomService rather than straight at the store, so+ # that an agent's archive is reported like any other. This stand-in keeps+ # the fake store as the thing under test.+ class _RoomServiceStub:+ async def set_room_archived(self, room_id: str, archived: bool) -> None:+ async with _session_factory() as session:+ await svc.room_store.set_archived(session, room_id, archived)++ svc.room_service = _RoomServiceStub() # type: ignore[assignment]return svcdiff --git a/core/tests/switch_core/db/test_tenant_exemption_allowlist.py b/core/tests/switch_core/db/test_tenant_exemption_allowlist.pyindex ec76835fa..bc2cd9099 100644--- a/core/tests/switch_core/db/test_tenant_exemption_allowlist.py+++ b/core/tests/switch_core/db/test_tenant_exemption_allowlist.py@@ -88,6 +88,15 @@ _ALLOWED_MODULES = {# came off this list with `tenant_of_client`: both were built from a# `clients` row that already named the tenant, so they carry it instead of# asking for it.+ #+ # The usage snapshot counts every tenant's rooms, messages and agents and+ # reports one deployment-wide total. That is the same boot-style fan-out+ # `main` does: enumerate the tenants, then bind each one in turn and read+ # its rows under its own policy. It has to ask, because a session with+ # nothing bound reads nothing — a snapshot written without this would+ # report a page of zeroes on a correctly configured deployment and look+ # perfectly healthy doing it.+ "switch_core.telemetry.snapshot",}# Every module allowed to open a session straight from the factory. Not short,@@ -149,6 +158,18 @@ _RAW_SESSION_FACTORY_MODULES = {# from the exemption, so neither has a session left that says nothing.# `switch_core.main` came off it earlier, when the tenant-zero fallback# went.+ #+ # ── Telemetry bookkeeping: three tables that carry no tenant and no+ # policy, named in `rls_ddl.GLOBAL_TABLES`. Each records a fact about the+ # *installation* — which deployment this is, when it was installed, which+ # once-ever milestones it has reported, when the last snapshot went out —+ # so there is no tenant for a policy to narrow on and binding one would be+ # theatre. Same shape, and same reasoning, as reading `users`.+ "switch_core.telemetry.deployment",+ "switch_core.telemetry.reporter",+ # Its own reads are the per-tenant fan-out above; this is the one global+ # read beside them, the deployment's user count.+ "switch_core.telemetry.snapshot",}# Calls that end in `session_factory` but hand one back rather than open adiff --git a/core/tests/switch_core/db/test_tenant_schema_catalogue.py b/core/tests/switch_core/db/test_tenant_schema_catalogue.pyindex c2b32c10d..d06f2a7dc 100644--- a/core/tests/switch_core/db/test_tenant_schema_catalogue.py+++ b/core/tests/switch_core/db/test_tenant_schema_catalogue.py@@ -96,7 +96,19 @@ class TestEveryTableIsScopedUnlessItIsNamedGlobal:scoped table, not a nullable column there. `alembic_version` isglobal too but is not in this metadata: Alembic owns it."""- assert set(GLOBAL_TABLES) == {"users", "oidc_identities", "feature_flags"}+ assert set(GLOBAL_TABLES) == {+ "users",+ "oidc_identities",+ "feature_flags",+ # Facts about the installation, not about anything in it: which+ # deployment this is to the analytics relay and when it was+ # installed, which once-ever milestones it has reported, and when+ # its last usage snapshot went out. A deployment running three+ # tenants has one identity, not three.+ "deployment_identity",+ "telemetry_milestones",+ "telemetry_snapshot_watermark",+ }async def test_scoped_is_everything_else(self) -> None:scoped = _scoped_tables()diff --git a/core/tests/switch_core/telemetry/test_catalogue.py b/core/tests/switch_core/telemetry/test_catalogue.pynew file mode 100644index 000000000..f55a65f66--- /dev/null+++ b/core/tests/switch_core/telemetry/test_catalogue.py@@ -0,0 +1,176 @@+"""The catalogue is the privacy boundary, so these are the tests that matter.++Everything here is about what *cannot* reach the relay. The counterpart to the+Console's own catalogue test, which tries to smuggle a room name into every+event and asserts it never arrives — the same trick is played below, because+the rule ("no identifier for anything inside a deployment") is only a rule if+something enforces it.+"""++from __future__ import annotations++import pytest++from switch_core.telemetry.catalogue import (+ CATALOGUE,+ EVENT_NAME_PREFIX,+ TelemetryCatalogueError,+ validate,+ wire_name,+)++# Anything that would identify something inside a deployment. None of these is+# a declared property of any event, and none may become one without this test+# being changed deliberately.+FORBIDDEN_PROPERTIES = (+ "room_id",+ "room_name",+ "tenant_id",+ "tenant_name",+ "agent_id",+ "agent_name",+ "user_id",+ "user_email",+ "message_id",+ "message_body",+ "channel_id",+ "channel_name",+ "external_channel_id",+ "display_name",+ "hostname",+ "repo_dir",+ "file_path",+ "error_message",+ "stack_trace",+)+++def _one_valid_value(spec: object) -> object:+ """A value the property will accept, whatever kind it is."""+ kind = type(spec).__name__+ if kind == "_Number":+ return 1+ if kind == "_Boolean":+ return True+ return sorted(spec.values)[0] # type: ignore[attr-defined]+++def _valid_payload(event: str) -> dict[str, object]:+ return {name: _one_valid_value(spec) for name, spec in CATALOGUE[event].items()}+++class TestNothingIdentifyingCanBeSent:+ def test_no_event_declares_an_identifying_property(self) -> None:+ """The rule, stated against the catalogue rather than against a payload.++ A property added under one of these names would pass every other test+ in this file, because the machinery would happily carry it. This is+ the one that says it may not exist at all.+ """+ offenders = {+ f"{event}.{name}"+ for event, spec in CATALOGUE.items()+ for name in spec+ if name in FORBIDDEN_PROPERTIES+ }+ assert not offenders, (+ f"{sorted(offenders)} name something inside a deployment. Telemetry "+ "reports counts and durations only — see docs/old/telemetry-events.md. "+ "If a new property genuinely needs to identify something, that is a "+ "decision for the InfoSec review, not for this file."+ )++ @pytest.mark.parametrize("event", sorted(CATALOGUE))+ def test_an_identifier_smuggled_alongside_valid_properties_is_refused(+ self, event: str+ ) -> None:+ """The Console's trick: a real payload with one extra field."""+ payload = _valid_payload(event)+ payload["room_name"] = "incident-response"+ with pytest.raises(TelemetryCatalogueError, match="does not declare"):+ validate(event, payload) # type: ignore[arg-type]++ def test_an_undeclared_event_is_refused(self) -> None:+ with pytest.raises(TelemetryCatalogueError, match="not a telemetry event"):+ validate("room_secretly_inspected", {})+++class TestThePropertySetIsExact:+ @pytest.mark.parametrize("event", sorted(CATALOGUE))+ def test_a_declared_payload_is_accepted(self, event: str) -> None:+ validate(event, _valid_payload(event)) # type: ignore[arg-type]++ @pytest.mark.parametrize(+ "event", sorted(event for event in CATALOGUE if CATALOGUE[event])+ )+ def test_a_missing_property_is_refused(self, event: str) -> None:+ """Every event of a name carries the same keys every time.++ Not a privacy rule but a charting one: a property that is sometimes+ absent cannot be grouped on, and the absence is invisible in the tool.+ """+ payload = _valid_payload(event)+ payload.pop(sorted(payload)[0])+ with pytest.raises(TelemetryCatalogueError, match="is missing"):+ validate(event, payload) # type: ignore[arg-type]+++class TestValuesAreClosed:+ def test_a_value_outside_its_set_is_refused(self) -> None:+ payload = _valid_payload("bridge_connected")+ payload["bridge_platform"] = "irc"+ with pytest.raises(TelemetryCatalogueError, match="expected one of"):+ validate("bridge_connected", payload) # type: ignore[arg-type]++ def test_free_text_where_a_set_belongs_is_refused(self) -> None:+ """The case that matters: an exception message reaching `failure_reason`."""+ payload = _valid_payload("bridge_connected")+ payload["failure_reason"] = "SlackApiError: invalid_auth for team acme-corp"+ with pytest.raises(TelemetryCatalogueError, match="expected one of"):+ validate("bridge_connected", payload) # type: ignore[arg-type]++ def test_a_boolean_is_not_a_number(self) -> None:+ """`bool` subclasses `int`, so a count set to True would otherwise pass+ and be reported as 1."""+ payload = _valid_payload("usage_snapshot")+ payload["room_count"] = True+ with pytest.raises(TelemetryCatalogueError, match="expected a number"):+ validate("usage_snapshot", payload) # type: ignore[arg-type]++ def test_a_number_is_not_a_string(self) -> None:+ payload = _valid_payload("usage_snapshot")+ payload["room_count"] = "lots"+ with pytest.raises(TelemetryCatalogueError, match="expected a number"):+ validate("usage_snapshot", payload) # type: ignore[arg-type]++ def test_a_non_finite_count_is_refused(self) -> None:+ """A mean over zero rooms must not arrive as NaN."""+ payload = _valid_payload("usage_snapshot")+ payload["room_users_mean"] = float("nan")+ with pytest.raises(TelemetryCatalogueError, match="finite"):+ validate("usage_snapshot", payload) # type: ignore[arg-type]+++class TestNaming:+ def test_every_event_is_snake_case(self) -> None:+ offenders = [+ event+ for event in CATALOGUE+ if not event.replace("_", "").isalnum() or event != event.lower()+ ]+ assert not offenders++ def test_every_property_is_snake_case(self) -> None:+ offenders = [+ f"{event}.{name}"+ for event, spec in CATALOGUE.items()+ for name in spec+ if not name.replace("_", "").isalnum() or name != name.lower()+ ]+ assert not offenders++ def test_the_wire_name_is_prefixed_by_product(self) -> None:+ """One Amplitude project holds several products, so the prefix is what+ keeps `room_created` here apart from the Console's."""+ assert wire_name("room_created") == f"{EVENT_NAME_PREFIX}.room_created"+ assert EVENT_NAME_PREFIX == "switch_core"diff --git a/core/tests/switch_core/telemetry/test_deployment_and_reporter.py b/core/tests/switch_core/telemetry/test_deployment_and_reporter.pynew file mode 100644index 000000000..050c796c8--- /dev/null+++ b/core/tests/switch_core/telemetry/test_deployment_and_reporter.py@@ -0,0 +1,322 @@+"""Deployment identity, once-ever milestones, and the snapshot schedule.++Against real Postgres, because all three are claims about durability: an+identity that survives a restart, a milestone that cannot fire twice, and a+schedule anchored to what was sent rather than to how long the process has+been up. None of those can be tested against a mock — the second in particular+relies on a primary-key collision being the guard.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta++import pytest+from sqlalchemy import delete+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import DeploymentIdentity, TelemetrySnapshotWatermark+from switch_core.telemetry.deployment import (+ DeploymentIdentityMissingError,+ claim_milestone,+ load_deployment_identity,+ seconds_since_install,+)+from switch_core.telemetry.reporter import SnapshotReporter+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.sink import TelemetryRecord++NOW = datetime(2026, 9, 16, 12, 0, tzinfo=UTC)+++class _RecordingSink:+ def __init__(self) -> None:+ self.sent: list[TelemetryRecord] = []++ async def send(self, record: TelemetryRecord) -> None:+ self.sent.append(record)++ async def aclose(self) -> None:+ return None+++async def _seed_identity(+ session_factory: async_sessionmaker[AsyncSession],+ *,+ installed_at: datetime | None,+) -> None:+ async with session_factory() as session:+ await session.execute(delete(DeploymentIdentity))+ session.add(+ DeploymentIdentity(+ id=1, client_id=str(uuid.uuid4()), installed_at=installed_at+ )+ )+ await session.commit()+++class TestDeploymentIdentity:+ async def test_the_identity_is_read_back(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await _seed_identity(session_factory, installed_at=NOW)++ client_id, installed_at = await load_deployment_identity(session_factory)++ assert uuid.UUID(client_id)+ assert installed_at is not None++ async def test_a_missing_identity_raises_rather_than_minting_one(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Only the migration ran early enough to tell a new deployment from an+ existing one. Re-creating the row here would give a year-old+ installation an install date of today and a brand-new analytics+ identity."""+ async with session_factory() as session:+ await session.execute(delete(DeploymentIdentity))+ await session.commit()++ with pytest.raises(DeploymentIdentityMissingError):+ await load_deployment_identity(session_factory)++ async def test_only_one_identity_can_exist(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Two would mean one installation reporting as two subjects, silently+ doubling every count derived from it."""+ await _seed_identity(session_factory, installed_at=NOW)++ with pytest.raises(Exception):+ async with session_factory() as session:+ session.add(DeploymentIdentity(id=2, client_id=str(uuid.uuid4())))+ await session.commit()+++class TestTheInstallClock:+ def test_a_deployment_with_no_install_date_is_unmeasurable(self) -> None:+ """Not zero — `None`, which every milestone call site treats as "do not+ report". A pre-existing deployment stays out of the funnel rather than+ appearing to have activated instantly."""+ assert seconds_since_install(None) is None++ def test_elapsed_time_is_measured_from_the_install(self) -> None:+ elapsed = seconds_since_install(datetime.now(UTC) - timedelta(hours=2))+ assert elapsed is not None+ assert 7100 < elapsed < 7300++ def test_a_naive_timestamp_is_read_as_utc(self) -> None:+ """A `timestamptz` read back without a zone must not raise on+ comparison."""+ naive = (datetime.now(UTC) - timedelta(minutes=5)).replace(tzinfo=None)+ elapsed = seconds_since_install(naive)+ assert elapsed is not None and elapsed > 0+++class TestMilestonesFireOnce:+ async def test_the_first_claim_wins_and_the_second_does_not(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ assert await claim_milestone(session_factory, "first_room_created") is True+ assert await claim_milestone(session_factory, "first_room_created") is False++ async def test_different_milestones_do_not_collide(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ assert await claim_milestone(session_factory, "first_room_created") is True+ assert await claim_milestone(session_factory, "first_connector_added") is True++ async def test_a_milestone_survives_a_restart(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The claim is a row, not process state — otherwise every restart+ would re-report "first room created" on finding a room."""+ await claim_milestone(session_factory, "deployment_installed")+ assert await claim_milestone(session_factory, "deployment_installed") is False+++class TestEmitMilestone:+ def _service(+ self,+ sink: _RecordingSink,+ session_factory: async_sessionmaker[AsyncSession],+ *,+ enabled: bool = True,+ installed_at: datetime | None = None,+ ) -> TelemetryService:+ return TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=enabled,+ client_id="deployment-uuid",+ service_name="switch-core",+ version="1.0.0",+ environment=None,+ session_factory=session_factory,+ installed_at=installed_at,+ )++ async def test_a_milestone_is_reported_once_with_its_elapsed_time(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ sink = _RecordingSink()+ service = self._service(+ sink, session_factory, installed_at=datetime.now(UTC) - timedelta(hours=1)+ )++ await service.emit_milestone("first_connector_added", bridge_platform="slack")+ await service.emit_milestone("first_connector_added", bridge_platform="slack")+ await service.aclose()++ assert len(sink.sent) == 1+ assert sink.sent[0].name == "switch_core.first_connector_added"+ assert 3500 < float(sink.sent[0].properties["seconds_since_install"]) < 3700++ async def test_a_deployment_with_no_install_date_reports_no_milestone(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ sink = _RecordingSink()+ service = self._service(sink, session_factory, installed_at=None)++ await service.emit_milestone("first_connector_added", bridge_platform="slack")+ await service.aclose()++ assert sink.sent == []++ async def test_a_disabled_deployment_does_not_use_up_its_claims(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Switching telemetry on later must not find every milestone already+ spent."""+ sink = _RecordingSink()+ off = self._service(+ sink, session_factory, enabled=False, installed_at=datetime.now(UTC)+ )++ await off.emit_milestone("first_connector_added", bridge_platform="slack")++ assert await claim_milestone(session_factory, "first_connector_added") is True+++class TestTheSnapshotSchedule:+ def _reporter(+ self,+ sink: _RecordingSink,+ session_factory: async_sessionmaker[AsyncSession],+ *,+ interval_hours: float = 24.0,+ ) -> SnapshotReporter:+ service = TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=True,+ client_id="deployment-uuid",+ service_name="switch-core",+ version="1.0.0",+ environment=None,+ session_factory=session_factory,+ installed_at=datetime.now(UTC) - timedelta(days=1),+ )+ return SnapshotReporter(+ telemetry=service,+ session_factory=session_factory,+ interval_hours=interval_hours,+ installed_at=service.installed_at,+ live_session_count=lambda: 2,+ )++ async def _clear_watermark(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await session.execute(delete(TelemetrySnapshotWatermark))+ await session.commit()++ async def test_the_first_pass_sends_a_snapshot_and_sets_the_watermark(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await self._clear_watermark(session_factory)+ sink = _RecordingSink()+ reporter = self._reporter(sink, session_factory)++ assert await reporter.run_once_if_due() is True++ names = [record.name for record in sink.sent]+ assert "switch_core.usage_snapshot" in names++ async def test_a_second_pass_inside_the_interval_does_nothing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await self._clear_watermark(session_factory)+ sink = _RecordingSink()+ reporter = self._reporter(sink, session_factory)++ await reporter.run_once_if_due()+ sent_after_first = len(sink.sent)++ assert await reporter.run_once_if_due() is False+ assert len(sink.sent) == sent_after_first++ async def test_the_schedule_follows_the_watermark_not_the_process(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A restart must not send a second snapshot the same day, and a+ deployment that was down over its due time must send promptly rather+ than waiting a further full period."""+ await self._clear_watermark(session_factory)+ sink = _RecordingSink()+ first = self._reporter(sink, session_factory)+ await first.run_once_if_due()++ # A brand-new reporter, as a restart would build.+ restarted = self._reporter(_RecordingSink(), session_factory)+ assert await restarted.run_once_if_due() is False++ async def test_a_lapsed_watermark_sends_again(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await session.execute(delete(TelemetrySnapshotWatermark))+ session.add(+ TelemetrySnapshotWatermark(+ id=1, last_sent_at=datetime.now(UTC) - timedelta(days=3)+ )+ )+ await session.commit()++ sink = _RecordingSink()+ reporter = self._reporter(sink, session_factory)++ assert await reporter.run_once_if_due() is True++ async def test_the_first_pass_reports_no_room_activations(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """With no watermark, "first interaction since then" means every room+ that ever went active, arriving at once and all dated today."""+ await self._clear_watermark(session_factory)+ sink = _RecordingSink()+ reporter = self._reporter(sink, session_factory)++ await reporter.run_once_if_due()++ assert not [+ record+ for record in sink.sent+ if record.name == "switch_core.room_became_active"+ ]++ async def test_the_snapshot_carries_the_live_session_count(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await self._clear_watermark(session_factory)+ sink = _RecordingSink()+ reporter = self._reporter(sink, session_factory)++ await reporter.run_once_if_due()++ snapshot = next(+ record+ for record in sink.sent+ if record.name == "switch_core.usage_snapshot"+ )+ assert snapshot.properties["session_live_count"] == 2diff --git a/core/tests/switch_core/telemetry/test_emitters_are_live.py b/core/tests/switch_core/telemetry/test_emitters_are_live.pynew file mode 100644index 000000000..5037c4699--- /dev/null+++ b/core/tests/switch_core/telemetry/test_emitters_are_live.py@@ -0,0 +1,105 @@+"""The services that report telemetry actually hold a telemetry service.++`test_every_event_is_emitted.py` proves a call site exists for every catalogue+entry. It cannot prove the call does anything: `emit_safely` returns+immediately when the service is `None`, which is deliberate — several services+are built without one in tests and tooling — and it means a call site can be+present, correct, covered by its own unit test, and dead in production.++That is exactly what happened. The agent bridge built *two* `ProtocolService`+instances: one in `create_agent_bridge_app` that got the telemetry service, and+one in `init_dependencies` that the HTTP handlers actually resolve through+`Depends(get_protocol)` and that got nothing. Every session event and every+agent registration arriving at the agent bridge was validated, handed to+`emit_safely`, and dropped — silently, at a relay nobody watches, to be+discovered later as "usage is zero".++So these tests assert on the wiring rather than on the code: build the app the+way the server does, then ask the objects a request would actually reach+whether they can report.+"""++from __future__ import annotations++from typing import Any++from switch_core.bridges.agent.app import create_agent_bridge_app+from switch_core.bridges.agent.dependencies import get_protocol+from switch_core.bridges.agent.protocol.event_buffer import EventBuffer+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.sink import NullSink+++def _telemetry() -> TelemetryService:+ return TelemetryService(+ sink=NullSink(),+ enabled=True,+ client_id="deployment-uuid",+ service_name="switch-core",+ version="1.0.0",+ environment=None,+ )+++def _build(telemetry: TelemetryService) -> Any:+ """The agent bridge app, wired the way `main.run` wires it."""+ _, protocol = create_agent_bridge_app(+ agent_store=object(), # type: ignore[arg-type]+ agent_session_store=object(), # type: ignore[arg-type]+ room_store=object(), # type: ignore[arg-type]+ room_service=object(), # type: ignore[arg-type]+ client_lifecycle=object(), # type: ignore[arg-type]+ collab_lifecycle=object(), # type: ignore[arg-type]+ event_buffer=EventBuffer(),+ task_store=object(), # type: ignore[arg-type]+ resource_service=object(), # type: ignore[arg-type]+ api_key_store=object(), # type: ignore[arg-type]+ external_user_store=object(), # type: ignore[arg-type]+ bridge_store=object(), # type: ignore[arg-type]+ session_factory=object(),+ config=_config(),+ telemetry=telemetry,+ )+ return protocol+++def _config() -> Any:+ class _Config:+ agent_auth_cache_ttl_seconds = 1+ agent_auth_cache_max_entries = 16+ jwt_secret_key = "x"+ oauth_issuer_url = None+ oauth_audience = None+ oauth_verify_issuer = True+ matrix_server_name = "test"++ return _Config()+++def test_the_protocol_service_a_request_reaches_can_report() -> None:+ """`get_protocol()` is what every handler resolves. If its service has no+ telemetry, every session event and agent registration at the agent bridge+ is silently dropped."""+ telemetry = _telemetry()+ _build(telemetry)++ assert get_protocol().telemetry is telemetry, (+ "The ProtocolService the HTTP handlers resolve has no telemetry "+ "service, so every event it emits is dropped by emit_safely. The app "+ "and init_dependencies must be given the same one."+ )+++def test_the_protocol_service_the_app_returns_is_the_one_handlers_use() -> None:+ """Two instances is the shape that caused the drop. They must be one, or+ a future change will wire telemetry to whichever is convenient and leave+ the other dead again."""+ telemetry = _telemetry()+ returned = _build(telemetry)++ assert get_protocol() is returned, (+ "create_agent_bridge_app returns a different ProtocolService from the "+ "one its handlers use. Anything wired onto one is absent from the "+ "other — which is how the session events came to be emitted into "+ "nothing."+ )diff --git a/core/tests/switch_core/telemetry/test_every_event_is_emitted.py b/core/tests/switch_core/telemetry/test_every_event_is_emitted.pynew file mode 100644index 000000000..34baa97ed--- /dev/null+++ b/core/tests/switch_core/telemetry/test_every_event_is_emitted.py@@ -0,0 +1,95 @@+"""Every declared event is actually emitted somewhere.++A catalogue entry with no call site is a metric the product believes it has and+does not. That is worse than an absent entry, because the absence is visible in+the code and the silence is only visible in an empty chart six weeks later —+and the reader's first assumption will be that usage is zero, not that nothing+is reporting.++Five entries were in exactly that state when a coverage review looked:+`agent_registered`, `agent_session_started`, `agent_session_ended`,+`first_agent_registered` and `first_session_started` — between them the whole+agent half of the funnel, and two of the metrics the business asked for.+"""++from __future__ import annotations++import ast+from pathlib import Path++import switch_core+from switch_core.telemetry.catalogue import CATALOGUE++_PACKAGE_ROOT = Path(switch_core.__file__).resolve().parent+_CATALOGUE = _PACKAGE_ROOT / "telemetry" / "catalogue.py"+++def _emitted_names() -> set[str]:+ """Every string literal passed as the first argument to an emit call.++ Matched on the call rather than on the bare string, so a name that appears+ only in a comment, a docstring or a reason map does not count as an+ emitter. The three shapes in the tree are `telemetry.emit("x", ...)`,+ `await telemetry.emit_milestone("x", ...)` and+ `emit_safely(target, "x", {...})`.+ """+ emitters = {"emit", "emit_milestone", "emit_safely"}+ found: set[str] = set()+ for path in _PACKAGE_ROOT.rglob("*.py"):+ if path == _CATALOGUE:+ continue+ tree = ast.parse(path.read_text(), filename=str(path))+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call) or not node.args:+ continue+ func = node.func+ name = (+ func.attr+ if isinstance(func, ast.Attribute)+ else func.id+ if isinstance(func, ast.Name)+ else None+ )+ if name not in emitters:+ continue+ # `emit_safely` takes the service first, so scan the leading+ # arguments rather than assuming a position.+ for arg in node.args[:2]:+ if isinstance(arg, ast.Constant) and isinstance(arg.value, str):+ found.add(arg.value)+ return found+++def test_no_declared_event_is_left_unemitted() -> None:+ declared = set(CATALOGUE)+ unemitted = sorted(declared - _emitted_names())+ assert not unemitted, (+ f"{unemitted} are declared in the telemetry catalogue and emitted "+ "nowhere. An event nobody sends is a metric the product believes it "+ "has: the chart is empty and reads as 'no usage' rather than 'not "+ "instrumented'. Either wire it up, or delete the entry and the row it "+ "claims in docs/old/telemetry-events.md."+ )+++def test_no_event_is_emitted_without_being_declared() -> None:+ """The other direction. `validate()` already raises at runtime on an+ undeclared name, but that only fires if the branch is taken — this catches+ a typo in a rarely-reached call site at import time instead."""+ declared = set(CATALOGUE)+ # Names passed to an emit call that are not events: `emit_safely`'s first+ # argument is a service, never a literal, so anything found here should be+ # an event name.+ undeclared = sorted(name for name in _emitted_names() if name not in declared)+ assert not undeclared, (+ f"{undeclared} are emitted but not declared in the catalogue. "+ "`validate()` would reject them at runtime; declare them, or fix the "+ "name."+ )+++def test_the_detector_would_notice_a_new_unemitted_entry() -> None:+ """The test above only proves today's tree is clean; this proves it can+ fail. Without it, a broken detector reads as a clean catalogue."""+ pretend = set(CATALOGUE) | {"room_abandoned"}+ assert sorted(pretend - _emitted_names()) == ["room_abandoned"]diff --git a/core/tests/switch_core/telemetry/test_first_room_active.py b/core/tests/switch_core/telemetry/test_first_room_active.pynew file mode 100644index 000000000..44bf95810--- /dev/null+++ b/core/tests/switch_core/telemetry/test_first_room_active.py@@ -0,0 +1,250 @@+"""The activation milestone, which fires once and is permanent if wrong.++A review found four independent defects in seven lines of this method, none of+which any test would have caught because nothing exercised it. Each case below+pins one of them.++The value matters more than most: `first_room_active` is the end of the+activation funnel, it is claimed once per deployment ever, and a wrong number+cannot be corrected by a later pass.+"""++from __future__ import annotations++from datetime import UTC, datetime, timedelta++from sqlalchemy import delete+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import TelemetryMilestone+from switch_core.telemetry.deployment import claim_milestone+from switch_core.telemetry.reporter import SnapshotReporter+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.sink import TelemetryRecord+from switch_core.telemetry.snapshot import NewlyActiveRoom++INSTALLED = datetime(2026, 9, 1, 0, 0, tzinfo=UTC)+++class _RecordingSink:+ def __init__(self) -> None:+ self.sent: list[TelemetryRecord] = []++ async def send(self, record: TelemetryRecord) -> None:+ self.sent.append(record)++ async def aclose(self) -> None:+ return None+++def _room(+ *,+ first_active_at: datetime,+ since_created: float = 60.0,+ kind: str = "user",+ platform: str = "slack",+) -> NewlyActiveRoom:+ return NewlyActiveRoom(+ first_active_at=first_active_at,+ seconds_since_room_created=since_created,+ bridge_platform=platform,+ channel_type="channel_public",+ agent_count=1,+ created_by_kind=kind,+ )+++def _reporter(+ sink: _RecordingSink,+ session_factory: async_sessionmaker[AsyncSession],+ *,+ enabled: bool = True,+) -> SnapshotReporter:+ service = TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=enabled,+ client_id="deployment-uuid",+ service_name="switch-core",+ version="1.0.0",+ environment=None,+ session_factory=session_factory,+ installed_at=INSTALLED,+ )+ return SnapshotReporter(+ telemetry=service,+ session_factory=session_factory,+ interval_hours=24.0,+ installed_at=INSTALLED,+ live_session_count=lambda: 0,+ )+++async def _clear(session_factory: async_sessionmaker[AsyncSession]) -> None:+ async with session_factory() as session:+ await session.execute(delete(TelemetryMilestone))+ await session.commit()+++async def _report(reporter: SnapshotReporter, rooms: list) -> None:+ """Report, then let the fire-and-forget send actually run.++ `emit` hands the send to a background task by design, so a test that+ inspects the sink immediately races it.+ """+ await reporter._report_first_room_active(rooms)+ await reporter._telemetry.aclose()+++def _milestone(sink: _RecordingSink) -> TelemetryRecord | None:+ return next(+ (r for r in sink.sent if r.name == "switch_core.first_room_active"), None+ )+++class TestItIsMeasuredFromTheInteraction:+ async def test_the_elapsed_time_is_install_to_activation_not_install_to_now(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The snapshot runs on an interval, so it always learns about an+ activation late — and always in the same direction. Measuring to `now`+ would add a day to every deployment's headline activation figure."""+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory)++ activated = INSTALLED + timedelta(hours=3)+ await _report(reporter, [_room(first_active_at=activated)])++ record = _milestone(sink)+ assert record is not None+ assert record.properties["seconds_since_install"] == 3 * 3600+++class TestItPicksTheEarliestRoom:+ async def test_the_first_room_to_activate_wins_not_the_quickest(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """A batch can hold several. The deployment activated when the first of+ them did; the one that went from creation to use fastest is a different+ and much smaller number."""+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory)++ earliest = _room(+ first_active_at=INSTALLED + timedelta(hours=2),+ since_created=9999.0,+ platform="teams",+ )+ quickest = _room(+ first_active_at=INSTALLED + timedelta(days=5),+ since_created=1.0,+ platform="slack",+ )++ await _report(reporter, [quickest, earliest])++ record = _milestone(sink)+ assert record is not None+ assert record.properties["seconds_since_install"] == 2 * 3600+ assert record.properties["bridge_platform"] == "teams"+++class TestOnlyARoomAPersonMade:+ async def test_an_agent_created_room_does_not_activate_the_deployment(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """An orchestration spinning up a scratch room is not a customer+ getting started, and must not consume the once-ever claim."""+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory)++ await _report(+ reporter,+ [_room(first_active_at=INSTALLED + timedelta(hours=1), kind="agent")],+ )++ assert _milestone(sink) is None+ # And the claim is still available for the real activation.+ assert await claim_milestone(session_factory, "first_room_active") is True++ async def test_a_system_adopted_room_does_not_either(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory)++ await _report(+ reporter,+ [_room(first_active_at=INSTALLED + timedelta(hours=1), kind="system")],+ )++ assert _milestone(sink) is None++ async def test_the_user_room_is_chosen_from_a_mixed_batch(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory)++ await _report(+ reporter,+ [+ _room(first_active_at=INSTALLED + timedelta(hours=1), kind="agent"),+ _room(+ first_active_at=INSTALLED + timedelta(hours=4),+ kind="user",+ platform="discord",+ ),+ ],+ )++ record = _milestone(sink)+ assert record is not None+ assert record.properties["seconds_since_install"] == 4 * 3600+ assert record.properties["bridge_platform"] == "discord"+++class TestTheClaimIsNotSpentWhenNobodyIsListening:+ async def test_a_disabled_deployment_keeps_its_claim(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Otherwise a deployment that opts in later has already used up the+ milestone and can never report its activation."""+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory, enabled=False)++ await _report(reporter, [_room(first_active_at=INSTALLED + timedelta(hours=1))])++ assert sink.sent == []+ assert await claim_milestone(session_factory, "first_room_active") is True+++class TestItFiresOnce:+ async def test_a_second_batch_reports_nothing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory)++ await _report(reporter, [_room(first_active_at=INSTALLED + timedelta(hours=1))])+ await _report(reporter, [_room(first_active_at=INSTALLED + timedelta(hours=2))])++ assert len([r for r in sink.sent if r.name.endswith("first_room_active")]) == 1++ async def test_a_deployment_with_no_install_date_reports_nothing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await _clear(session_factory)+ sink = _RecordingSink()+ reporter = _reporter(sink, session_factory)+ reporter._installed_at = None++ await _report(reporter, [_room(first_active_at=INSTALLED + timedelta(hours=1))])++ assert _milestone(sink) is Nonediff --git a/core/tests/switch_core/telemetry/test_merge_fixes.py b/core/tests/switch_core/telemetry/test_merge_fixes.pynew file mode 100644index 000000000..7dfc0c2bc--- /dev/null+++ b/core/tests/switch_core/telemetry/test_merge_fixes.py@@ -0,0 +1,380 @@+"""The defects a third review found after 487 was merged with 491.++Each is the same shape: something that fails silently. A misdirected endpoint+that 404s once per event into a log nobody reads, an identity the relay drops+with a 200, a once-ever claim spent while nothing is listening, and a session+that ends with no event because the path that closed it was not one of the+three that reported.+"""++from __future__ import annotations++import asyncio+import time+import uuid+from types import SimpleNamespace++import pytest+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.bridges.agent.api import session_reporter+from switch_core.bridges.agent.api.session_reporter import SessionReporter+from switch_core.bridges.agent.protocol.connections import (+ ClientDeclaration,+ ConnectionRegistry,+)+from switch_core.telemetry.service import TelemetryService+from switch_core.telemetry.sink import TelemetryRecord++VALID_UUID = "11111111-1111-1111-1111-111111111111"+++class _RecordingSink:+ def __init__(self) -> None:+ self.sent: list[TelemetryRecord] = []++ async def send(self, record: TelemetryRecord) -> None:+ self.sent.append(record)++ async def aclose(self) -> None:+ return None+++def _config(**overrides: object) -> object:+ """A SwitchConfig with only what the validators need, plus overrides."""+ from switch_core.config import SwitchConfig++ base = {+ "db_host": "h",+ "db_port": "5432",+ "db_user": "u",+ "db_password": "p",+ "db_name": "d",+ "matrix_server_name": "test",+ "agent_registration_token": "t",+ "jwt_secret_key": "k",+ "gateway_admin_email": "[email protected]",+ "gateway_admin_password": "pw",+ }+ base.update(overrides) # type: ignore[arg-type]+ return SwitchConfig(**base) # type: ignore[arg-type]+++class TestTheEndpointIsABaseUrl:+ """It changed meaning in the merge — the signal path is appended now — and+ the full logs URL is the form most people have seen written down."""++ def test_a_full_signal_url_is_refused(self) -> None:+ with pytest.raises(ValueError, match="no path of its own"):+ _config(+ telemetry_enabled=True,+ telemetry_endpoint="https://telemetry.flintai.dev/v1/logs",+ )++ def test_whitespace_is_refused(self) -> None:+ """`urlsplit` puts a trailing space inside the host, so every other+ check passes and the failure names a connection problem instead."""+ with pytest.raises(ValueError, match="whitespace"):+ _config(+ telemetry_enabled=True,+ telemetry_endpoint="https://telemetry.flintai.dev ",+ )++ def test_a_query_string_is_refused(self) -> None:+ with pytest.raises(ValueError, match="query or"):+ _config(+ telemetry_enabled=True,+ telemetry_endpoint="https://relay.example?token=x",+ )++ def test_a_bare_base_url_is_accepted(self) -> None:+ _config(telemetry_enabled=True, telemetry_endpoint="https://relay.example")++ def test_the_shipped_default_is_valid(self) -> None:+ """The check is worth nothing if the value everyone gets fails it."""+ _config(telemetry_enabled=True)+++class TestTheDeploymentIdIsCheckedWhereverItIsSet:+ """Both streams use it now, so the shape check cannot live only on the+ collector's validator — the relay drops a non-UUID with a 200."""++ def test_a_malformed_id_is_refused_with_no_collector(self) -> None:+ with pytest.raises(ValueError, match="must be a UUID"):+ _config(telemetry_enabled=True, deployment_id="acme-prod")++ def test_a_malformed_id_is_refused_even_with_telemetry_off(self) -> None:+ """It is wrong whenever it is set; nothing is gained by waiting until+ it is used."""+ with pytest.raises(ValueError, match="must be a UUID"):+ _config(deployment_id="acme-prod")++ def test_a_uuid_is_accepted(self) -> None:+ _config(telemetry_enabled=True, deployment_id=VALID_UUID)++ def test_an_unset_id_is_fine(self) -> None:+ """The database supplies one; the env var is an override."""+ _config(telemetry_enabled=True)+++class TestASessionIsTheAgentNotTheConnection:+ """What filled the first real dashboard, and why.++ Two ordinary things make an agent hold a succession of short connections+ while being, to anyone watching the product, continuously present: a stream+ rejected at the room claim and retried, and a stream whose heartbeat lapsed+ (the TTL is six seconds) closing itself so the client reopens. Reported per+ connection, both are a storm of session pairs seconds apart. Reported per+ agent, neither is a session at all.+ """++ def _reporter(+ self, sink: _RecordingSink, registry: ConnectionRegistry+ ) -> SessionReporter:+ service = TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=True,+ client_id=VALID_UUID,+ service_name="switch-core",+ version="1.0.0",+ environment=None,+ )+ reporter = SessionReporter(service, registry)+ registry.set_close_listener(reporter.on_close)+ return reporter++ def _open(self, registry: ConnectionRegistry, agent: str = "agent-1") -> str:+ connection_id = uuid.uuid4().hex+ registry.open(+ agent_id=agent,+ connection_id=connection_id,+ scope="all",+ delivery_filter="all",+ spawn_capable=False,+ cursor=0,+ declaration=ClientDeclaration(),+ )+ return connection_id++ async def _stream(+ self, reporter: SessionReporter, registry: ConnectionRegistry, cid: str+ ) -> None:+ conn = registry.get(cid)+ assert conn is not None+ await reporter.started(+ SimpleNamespace(metadata_={"known_agent_type": "codex"}), # type: ignore[arg-type]+ conn,+ )++ def _names(self, sink: _RecordingSink) -> list[str]:+ return [r.name.removeprefix("switch_core.") for r in sink.sent]++ async def test_a_rejected_stream_reports_nothing(self) -> None:+ """No stream was handed back, so no session began."""+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ self._reporter(sink, registry)++ cid = self._open(registry)+ registry.close(cid, "room already claimed")+ await _settle()++ assert sink.sent == []++ async def test_twenty_rejected_attempts_report_nothing(self) -> None:+ """The retry loop, as the dashboard actually saw it."""+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ self._reporter(sink, registry)++ for _ in range(20):+ cid = self._open(registry)+ registry.close(cid, "room already claimed")+ await _settle()++ assert sink.sent == []++ async def test_a_reconnect_within_the_grace_continues_the_session(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """The heartbeat-lapse loop: one session, not one per six seconds."""+ monkeypatch.setattr(session_reporter, "_RECONNECT_GRACE_SECONDS", 0.05)+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ reporter = self._reporter(sink, registry)++ for _ in range(5):+ cid = self._open(registry)+ await self._stream(reporter, registry, cid)+ registry.close(cid, "heartbeat lapsed")+ await asyncio.sleep(0.01) # well inside the grace period+ await _settle()++ assert self._names(sink) == ["agent_session_started"]++ async def test_the_session_ends_once_the_agent_stays_away(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ monkeypatch.setattr(session_reporter, "_RECONNECT_GRACE_SECONDS", 0.05)+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ reporter = self._reporter(sink, registry)++ cid = self._open(registry)+ await self._stream(reporter, registry, cid)+ registry.close(cid, "heartbeat lapsed")+ await asyncio.sleep(0.15)+ await _settle()++ assert self._names(sink) == ["agent_session_started", "agent_session_ended"]+ assert sink.sent[1].properties["reason"] == "heartbeat_lapsed"++ async def test_the_duration_spans_the_whole_session(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """Not the last connection's lifetime — the span the agent was present,+ across however many reconnects it took."""+ monkeypatch.setattr(session_reporter, "_RECONNECT_GRACE_SECONDS", 0.05)+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ reporter = self._reporter(sink, registry)++ cid = self._open(registry)+ await self._stream(reporter, registry, cid)+ reporter._sessions["agent-1"].started_at = time.monotonic() - 300.0+ registry.close(cid, "heartbeat lapsed")+ await asyncio.sleep(0.15)+ await _settle()++ ended = next(r for r in sink.sent if r.name.endswith("session_ended"))+ assert float(ended.properties["duration_seconds"]) > 299.0++ async def test_a_second_connection_does_not_start_a_second_session(+ self,+ ) -> None:+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ reporter = self._reporter(sink, registry)++ for _ in range(3):+ cid = self._open(registry)+ await self._stream(reporter, registry, cid)+ await _settle()++ assert self._names(sink) == ["agent_session_started"]++ async def test_closing_one_of_several_connections_ends_nothing(+ self, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ monkeypatch.setattr(session_reporter, "_RECONNECT_GRACE_SECONDS", 0.05)+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ reporter = self._reporter(sink, registry)++ first = self._open(registry)+ second = self._open(registry)+ await self._stream(reporter, registry, first)+ await self._stream(reporter, registry, second)+ registry.close(first, "heartbeat lapsed")+ await asyncio.sleep(0.15)+ await _settle()++ assert self._names(sink) == ["agent_session_started"]++ async def test_two_agents_are_two_sessions(self) -> None:+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ reporter = self._reporter(sink, registry)++ for agent in ("agent-1", "agent-2"):+ cid = self._open(registry, agent)+ await self._stream(reporter, registry, cid)+ await _settle()++ assert self._names(sink) == [+ "agent_session_started",+ "agent_session_started",+ ]++ async def test_shutdown_reports_no_ends(self) -> None:+ """Every agent disconnects at once when the process stops; a burst of+ ends saying "the server stopped" is noise, not signal."""+ registry = ConnectionRegistry()+ sink = _RecordingSink()+ reporter = self._reporter(sink, registry)++ cid = self._open(registry)+ await self._stream(reporter, registry, cid)+ await reporter.aclose()+ await _settle()++ assert self._names(sink) == ["agent_session_started"]++ def test_a_listener_that_raises_does_not_break_the_close(self) -> None:+ """The registry's contract — the connection is closed and handed back —+ must not depend on whoever is watching."""+ registry = ConnectionRegistry()+ registry.set_close_listener(lambda conn: (_ for _ in ()).throw(RuntimeError()))+ cid = self._open(registry)++ assert registry.close(cid, "heartbeat lapsed") is not None+ assert registry.get(cid) is None+++class TestTelemetryNeverPreventsBoot:+ """A missing identity row disabled reporting; it must not stop the server.++ The row is seeded by a migration boot runs first, so its absence means a+ schema older than the code or a row deleted by hand. Either way, refusing+ to serve over analytics is the one thing this subsystem must never do.+ """++ async def test_an_unreadable_identity_disables_rather_than_raises(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ from sqlalchemy import delete++ from switch_core.db.models import DeploymentIdentity+ from switch_core.telemetry.setup import build_telemetry++ async with session_factory() as session:+ await session.execute(delete(DeploymentIdentity))+ await session.commit()++ service, installed_at, http = await build_telemetry(+ _config(telemetry_enabled=True), # type: ignore[arg-type]+ session_factory,+ "1.0.0",+ )++ assert service.enabled is False+ assert installed_at is None+ assert http is None++ async def test_it_reports_nothing_rather_than_an_empty_deployment(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Off, not "on with a blank id" — the relay drops a payload it cannot+ attribute, silently and with a 200, so sending would look like working."""+ from sqlalchemy import delete++ from switch_core.db.models import DeploymentIdentity+ from switch_core.telemetry.setup import build_telemetry++ async with session_factory() as session:+ await session.execute(delete(DeploymentIdentity))+ await session.commit()++ service, _, _ = await build_telemetry(+ _config(telemetry_enabled=True), # type: ignore[arg-type]+ session_factory,+ "1.0.0",+ )+ service.emit("deployment_started", tenant_count=1)+ await service.aclose()+++async def _settle() -> None:+ """Let a fire-and-forget send run."""+ for _ in range(3):+ await asyncio.sleep(0)diff --git a/core/tests/switch_core/telemetry/test_removals.py b/core/tests/switch_core/telemetry/test_removals.pynew file mode 100644index 000000000..566c43e41--- /dev/null+++ b/core/tests/switch_core/telemetry/test_removals.py@@ -0,0 +1,169 @@+"""Removals are reported, and carry what they were.++Without these, every count in the snapshot can fall with nothing to explain it:+a drop in `room_count` reads the same whether a customer tidied up, a bridge+was disconnected, or the deployment was abandoned. The lifespan is the part+that separates them — "deleted after an hour" and "deleted after a year" are+opposite signals.++The tests that matter here are the ones about *when* the data is gathered. Two+of these properties describe something that no longer exists by the time the+event is built, so they have to be read before the delete rather than after,+and a test that only checks the event fires would not notice.+"""++from __future__ import annotations++from datetime import UTC, datetime, timedelta++import pytest++from switch_core.telemetry.catalogue import CATALOGUE, TelemetryCatalogueError, validate+++class TestTheRemovalEventsExist:+ @pytest.mark.parametrize(+ "event",+ ["room_deleted", "agent_deleted", "connector_removed", "room_agents_removed"],+ )+ def test_each_removal_is_in_the_catalogue(self, event: str) -> None:+ assert event in CATALOGUE++ def test_room_deletion_carries_what_it_was(self) -> None:+ validate(+ "room_deleted",+ {+ "bridge_platform": "slack",+ "channel_type": "channel_public",+ "created_by_kind": "user",+ "age_days": 12.5,+ "was_ever_active": True,+ "agent_count": 3,+ },+ )++ def test_agent_deletion_carries_what_it_was(self) -> None:+ validate(+ "agent_deleted",+ {+ "known_agent_type": "codex",+ "age_days": 0.5,+ "room_count": 2,+ "had_parent": False,+ },+ )++ def test_connector_removal_says_whether_it_ever_worked(self) -> None:+ """A connector removed having never connected is a failed setup; one+ removed after months is a decision. Both are "removed"."""+ validate(+ "connector_removed",+ {+ "bridge_platform": "teams",+ "age_days": 90.0,+ "was_ever_connected": False,+ "room_count": 0,+ },+ )++ def test_a_removal_still_cannot_carry_a_name(self) -> None:+ with pytest.raises(TelemetryCatalogueError):+ validate(+ "room_deleted",+ {+ "bridge_platform": "slack",+ "channel_type": "channel_public",+ "created_by_kind": "user",+ "age_days": 1.0,+ "was_ever_active": True,+ "agent_count": 1,+ "room_name": "incident-response",+ },+ )+++class TestRegistrationPathProducesEveryValue:+ """All four values are produced by real code paths, which is the point of+ having four. `gateway` rather than `console` because the desktop app and+ the browser dashboard authenticate identically against the same endpoint —+ a value that looked precise and was a guess is worse than a coarser one+ that is true."""++ def test_the_declared_set_is_what_the_code_produces(self) -> None:+ spec = CATALOGUE["agent_registered"]["registration_path"]+ assert spec.values == frozenset( # type: ignore[attr-defined]+ {"bootstrap", "personal_key", "gateway", "other"}+ )++ @pytest.mark.parametrize("path", ["bootstrap", "personal_key", "gateway", "other"])+ def test_each_value_is_accepted(self, path: str) -> None:+ validate(+ "agent_registered",+ {+ "agent_type": "auto_session",+ "known_agent_type": "claude-code",+ "registration_path": path,+ "has_parent": False,+ },+ )++ def test_console_is_not_a_value(self) -> None:+ """It was, and it could never have been produced."""+ with pytest.raises(TelemetryCatalogueError, match="expected one of"):+ validate(+ "agent_registered",+ {+ "agent_type": "always_on",+ "known_agent_type": "none",+ "registration_path": "console",+ "has_parent": False,+ },+ )+++class TestAutoSessionIsAnAgentType:+ """It is one of the four connection models, and the one Switch Console sets+ whenever a user ticks auto-session — so leaving it out dropped the+ registration event for exactly the population the Console serves."""++ @pytest.mark.parametrize(+ "agent_type",+ ["always_on", "session_addressable", "session_passive", "auto_session"],+ )+ def test_every_connection_model_is_accepted(self, agent_type: str) -> None:+ validate(+ "agent_registered",+ {+ "agent_type": agent_type,+ "known_agent_type": "claude-code",+ "registration_path": "gateway",+ "has_parent": False,+ },+ )++ def test_the_set_matches_the_protocol_types(self) -> None:+ """Pinned against the source of truth, so a fifth connection model+ added there fails here rather than being silently dropped at emission."""+ from switch_core.bridges.agent.protocol.types import IntegrationProfile++ declared = CATALOGUE["agent_registered"]["agent_type"].values # type: ignore[attr-defined]+ annotation = IntegrationProfile.model_fields["connection_model"].annotation+ assert set(annotation.__args__) == set(declared) # type: ignore[union-attr]+++class TestAgeIsReportedInDays:+ def test_a_fresh_row_is_near_zero(self) -> None:+ from switch_core.room_service import _age_days++ assert _age_days(datetime.now(UTC)) < 0.01++ def test_an_old_row_reports_its_age(self) -> None:+ from switch_core.room_service import _age_days++ assert 9.9 < _age_days(datetime.now(UTC) - timedelta(days=10)) < 10.1++ def test_an_unreadable_timestamp_is_zero_rather_than_a_crash(self) -> None:+ from switch_core.room_service import _age_days++ assert _age_days(None) == 0.0+ assert _age_days("yesterday") == 0.0diff --git a/core/tests/switch_core/telemetry/test_service_and_sink.py b/core/tests/switch_core/telemetry/test_service_and_sink.pynew file mode 100644index 000000000..0ab2e90b5--- /dev/null+++ b/core/tests/switch_core/telemetry/test_service_and_sink.py@@ -0,0 +1,329 @@+"""Consent, the wire format, and what happens when the relay misbehaves."""++from __future__ import annotations++import asyncio+import json++import httpx+import pytest++from switch_core.observability.otlp import OtlpClient+from switch_core.telemetry.catalogue import TelemetryCatalogueError+from switch_core.telemetry.service import TelemetryService, emit_safely+from switch_core.telemetry.sink import NullSink, OtlpRelaySink, TelemetryRecord+++class _RecordingSink:+ def __init__(self) -> None:+ self.sent: list[TelemetryRecord] = []+ self.closed = False++ async def send(self, record: TelemetryRecord) -> None:+ self.sent.append(record)++ async def aclose(self) -> None:+ self.closed = True+++def _service(sink: object, *, enabled: bool = True) -> TelemetryService:+ return TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=enabled,+ client_id="deployment-uuid",+ service_name="switch-core",+ version="1.2.3",+ environment="pilot",+ )+++class TestConsent:+ async def test_nothing_is_sent_when_telemetry_is_off(self) -> None:+ sink = _RecordingSink()+ service = _service(sink, enabled=False)++ service.emit("deployment_started", tenant_count=1)+ await service.aclose()++ assert sink.sent == []++ async def test_a_bad_event_is_still_caught_when_telemetry_is_off(self) -> None:+ """Validation runs regardless, so a mistake in a rarely-taken branch is+ found by whichever test exercises it rather than lying dormant until+ the day a deployment switches reporting on."""+ service = _service(_RecordingSink(), enabled=False)+ with pytest.raises(TelemetryCatalogueError):+ service.emit("deployment_started", tenant_count="one") # type: ignore[arg-type]++ async def test_events_are_sent_when_telemetry_is_on(self) -> None:+ sink = _RecordingSink()+ service = _service(sink)++ service.emit("deployment_started", tenant_count=2)+ await service.aclose()++ assert [record.name for record in sink.sent] == [+ "switch_core.deployment_started"+ ]+++class TestTagging:+ async def test_every_event_carries_the_deployment_and_service(self) -> None:+ sink = _RecordingSink()+ service = _service(sink)++ service.emit("deployment_started", tenant_count=1)+ await service.aclose()++ assert sink.sent[0].resource == {+ "service.name": "switch-core",+ "flint.client_id": "deployment-uuid",+ "service.version": "1.2.3",+ "deployment.environment": "pilot",+ }++ async def test_an_unset_environment_is_omitted_rather_than_empty(self) -> None:+ """An absent attribute reads as "not configured"; an empty string reads+ as a real environment named nothing."""+ sink = _RecordingSink()+ service = TelemetryService(+ sink=sink, # type: ignore[arg-type]+ enabled=True,+ client_id="deployment-uuid",+ service_name="switch-core",+ version=None,+ environment=None,+ )++ service.emit("deployment_started", tenant_count=1)+ await service.aclose()++ assert "deployment.environment" not in sink.sent[0].resource+ assert "service.version" not in sink.sent[0].resource+++class TestFailuresDoNotReachTheCaller:+ async def test_a_sink_that_raises_does_not_surface(self) -> None:+ class _Broken:+ async def send(self, record: TelemetryRecord) -> None:+ raise RuntimeError("relay on fire")++ async def aclose(self) -> None:+ return None++ service = _service(_Broken())+ service.emit("deployment_started", tenant_count=1)+ await service.aclose() # must not raise++ def test_emit_safely_swallows_a_catalogue_mistake(self) -> None:+ """A bad event must not take down the room creation that reported it."""+ service = _service(_RecordingSink())+ emit_safely(service, "deployment_started", {"tenant_count": "one"})++ def test_emit_safely_tolerates_no_service_at_all(self) -> None:+ emit_safely(None, "deployment_started", {"tenant_count": 1})++ def test_emit_outside_an_event_loop_does_not_raise(self) -> None:+ """Reported from a management command or a sync helper."""+ service = _service(_RecordingSink())+ service.emit("deployment_started", tenant_count=1)+++class TestTheWireFormat:+ """The relay's expectations, which fail silently rather than loudly.++ The encoding itself belongs to `observability/otlp.py` and is tested+ there; what is pinned here is the part specific to a product event — that+ the name reaches both places the relay needs it, and that the shared+ encoder is being handed what it expects.+ """++ async def _capture(self, handler: object) -> dict:+ captured: dict = {}++ def _handle(request: httpx.Request) -> httpx.Response:+ captured.update(json.loads(request.content))+ return handler(request) # type: ignore[operator]++ http = httpx.AsyncClient(transport=httpx.MockTransport(_handle))+ sink = OtlpRelaySink(client=OtlpClient("https://relay.example", 5, {}, http))+ await sink.send(+ TelemetryRecord(+ name="switch_core.usage_snapshot",+ properties={"room_count": 7, "from_template": True, "kind": "user"},+ resource={+ "service.name": "switch-core",+ "flint.client_id": "deployment-uuid",+ },+ timestamp_ns=1_700_000_000_000_000_000,+ )+ )+ await http.aclose()+ return captured++ def _record(self, body: dict) -> dict:+ return body["resourceLogs"][0]["scopeLogs"][0]["logRecords"][0]++ async def test_the_event_name_is_sent_in_both_required_places(self) -> None:+ """The relay filters on the attribute and the exporter reads the field.+ Sending only one is accepted with a 200 and silently discarded."""+ record = self._record(await self._capture(lambda r: httpx.Response(200)))++ assert record["eventName"] == "switch_core.usage_snapshot"+ attributes = {a["key"]: a["value"] for a in record["attributes"]}+ assert attributes["event.name"] == {"stringValue": "switch_core.usage_snapshot"}++ async def test_a_count_is_a_number_not_a_string(self) -> None:+ """OTLP renders `intValue` as a JSON string, which arrives in analytics+ as text and cannot be summed."""+ record = self._record(await self._capture(lambda r: httpx.Response(200)))+ attributes = {a["key"]: a["value"] for a in record["attributes"]}++ assert attributes["room_count"] == {"doubleValue": 7.0}++ async def test_a_boolean_stays_a_boolean(self) -> None:+ record = self._record(await self._capture(lambda r: httpx.Response(200)))+ attributes = {a["key"]: a["value"] for a in record["attributes"]}++ assert attributes["from_template"] == {"boolValue": True}++ async def test_the_body_carries_the_name_so_the_log_line_is_not_blank(+ self,+ ) -> None:+ record = self._record(await self._capture(lambda r: httpx.Response(200)))++ assert record["body"] == {"stringValue": "switch_core.usage_snapshot"}++ async def test_the_deployment_is_identified_on_the_resource(self) -> None:+ body = await self._capture(lambda r: httpx.Response(200))+ resource = {+ a["key"]: a["value"]+ for a in body["resourceLogs"][0]["resource"]["attributes"]+ }++ assert resource["flint.client_id"] == {"stringValue": "deployment-uuid"}+ assert resource["service.name"] == {"stringValue": "switch-core"}++ async def test_it_posts_to_the_logs_signal(self) -> None:+ """Not `/v1/metrics`: the relay routes on log records, and a metric+ would be dropped without complaint."""+ seen: list[str] = []++ def _handle(request: httpx.Request) -> httpx.Response:+ seen.append(str(request.url))+ return httpx.Response(200)++ http = httpx.AsyncClient(transport=httpx.MockTransport(_handle))+ sink = OtlpRelaySink(client=OtlpClient("https://relay.example", 5, {}, http))+ await sink.send(_a_record())+ await http.aclose()++ assert seen == ["https://relay.example/v1/logs"]++ async def test_no_credential_is_sent(self) -> None:+ """The relay takes none, and holds the vendor keys itself."""+ seen: dict[str, str] = {}++ def _handle(request: httpx.Request) -> httpx.Response:+ seen.update(request.headers)+ return httpx.Response(200)++ http = httpx.AsyncClient(transport=httpx.MockTransport(_handle))+ sink = OtlpRelaySink(client=OtlpClient("https://relay.example", 5, {}, http))+ await sink.send(_a_record())+ await http.aclose()++ assert "authorization" not in seen+ assert "x-api-key" not in seen+++class TestTheRelayMisbehaving:+ """Every failure is logged and dropped. None reaches the caller."""++ async def _send_against(self, handler: object) -> None:+ http = httpx.AsyncClient(+ transport=httpx.MockTransport(handler) # type: ignore[arg-type]+ )+ sink = OtlpRelaySink(client=OtlpClient("https://relay.example", 5, {}, http))+ await sink.send(_a_record())+ await http.aclose()++ async def test_a_refusal_is_swallowed(self) -> None:+ await self._send_against(lambda r: httpx.Response(503))++ async def test_a_network_error_is_swallowed(self) -> None:+ def _boom(request: httpx.Request) -> httpx.Response:+ raise httpx.ConnectError("no route")++ await self._send_against(_boom)++ async def test_a_timeout_is_swallowed(self) -> None:+ def _slow(request: httpx.Request) -> httpx.Response:+ raise httpx.ReadTimeout("too slow")++ await self._send_against(_slow)++ async def test_a_partial_success_inside_a_200_is_noticed(+ self, caplog: pytest.LogCaptureFixture+ ) -> None:+ """A 200 does not mean the record was kept. Without this a+ misconfigured deployment reports nothing and looks healthy doing it."""+ with caplog.at_level("WARNING"):+ await self._send_against(+ lambda r: httpx.Response(+ 200, json={"partialSuccess": {"rejectedLogRecords": "3"}}+ )+ )++ assert "was not sent" in caplog.text++ async def test_an_empty_200_is_not_treated_as_a_rejection(+ self, caplog: pytest.LogCaptureFixture+ ) -> None:+ with caplog.at_level("WARNING"):+ await self._send_against(lambda r: httpx.Response(200))++ assert "was not sent" not in caplog.text+++def _a_record() -> TelemetryRecord:+ return TelemetryRecord(+ name="switch_core.deployment_started",+ properties={"tenant_count": 1},+ resource={"service.name": "switch-core", "flint.client_id": "deployment-uuid"},+ timestamp_ns=1,+ )+++class TestNullSink:+ async def test_it_discards_and_closes(self) -> None:+ sink = NullSink()+ await sink.send(TelemetryRecord("switch_core.x", {}, {}, 1))+ await sink.aclose()+++class TestShutdown:+ async def test_in_flight_sends_are_awaited(self) -> None:+ """The events worth losing least are the ones emitted just before the+ process goes away."""+ started = asyncio.Event()++ class _Slow:+ def __init__(self) -> None:+ self.finished = False++ async def send(self, record: TelemetryRecord) -> None:+ started.set()+ await asyncio.sleep(0.05)+ self.finished = True++ async def aclose(self) -> None:+ return None++ sink = _Slow()+ service = _service(sink)+ service.emit("deployment_started", tenant_count=1)+ await started.wait()+ await service.aclose()++ assert sink.finisheddiff --git a/core/tests/switch_core/telemetry/test_snapshot.py b/core/tests/switch_core/telemetry/test_snapshot.pynew file mode 100644index 000000000..3cd0fee4f--- /dev/null+++ b/core/tests/switch_core/telemetry/test_snapshot.py@@ -0,0 +1,679 @@+"""The usage snapshot against real Postgres.++These are the numbers that go in front of the business, so the tests are about+the definitions rather than about the plumbing: what counts as active, who+counts as a human, which room counts as one somebody made, and what a "turn"+between two participants actually is. A mock cannot check any of that — the+window function behind the turn counts, the JSONB read behind the+created-by split and the row-level-security fan-out all only exist in the+database.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import (+ Agent,+ ApiKey,+ Client,+ ClientRoom,+ CollaborationBridge,+ Message,+ Room,+ User,+)+from switch_core.telemetry.snapshot import (+ UsageCounts,+ collect_tenant_counts,+ collect_usage,+ newly_active_rooms,+ normalise_actor_kind,+ normalise_channel_type,+ normalise_known_agent_type,+ normalise_platform,+ room_had_human_activity,+)++NOW = datetime(2026, 9, 16, 12, 0, tzinfo=UTC)+++async def _room(+ session: AsyncSession,+ *,+ created_by_kind: str | None = "user",+ created_at: datetime | None = None,+ archived: bool = False,+ bridge_id: str | None = None,+ channel_type: str = "channel_public",+) -> Room:+ room = Room(+ matrix_room_id=f"!{uuid.uuid4().hex[:10]}:test",+ name=f"room-{uuid.uuid4().hex[:6]}",+ description="a room",+ channel_type=channel_type,+ bridge_id=bridge_id,+ created_at=created_at or (NOW - timedelta(days=30)),+ archived_at=NOW if archived else None,+ metadata_=({"created_by_kind": created_by_kind} if created_by_kind else None),+ )+ session.add(room)+ await session.flush()+ return room+++async def _client(session: AsyncSession, client_type: str) -> Client:+ client = Client(+ matrix_user_id=f"@{client_type}-{uuid.uuid4().hex[:8]}:test",+ display_name=f"{client_type} client",+ type=client_type,+ )+ session.add(client)+ await session.flush()+ return client+++async def _agent(session: AsyncSession, runtime: str | None) -> Agent:+ """An agent with the client and api-key rows its foreign keys require."""+ slug = uuid.uuid4().hex[:10]+ owner = User(+ name="owner", email=f"owner-{slug}@test", role="user", password_hash="x"+ )+ session.add(owner)+ await session.flush()+ key = ApiKey(+ user_id=owner.id,+ key_hash=f"hash-{slug}",+ encrypted_key="enc",+ label="test",+ type="agent",+ )+ backing = Client(+ matrix_user_id=f"@agent-{slug}:test", display_name="agent", type="agent"+ )+ session.add_all([key, backing])+ await session.flush()+ agent = Agent(+ name=f"agent-{uuid.uuid4().hex[:6]}",+ description="d",+ agent_type="session_addressable",+ connector_type="http",+ integration_profile={},+ client_id=backing.id,+ api_key_id=key.id,+ metadata_=({"known_agent_type": runtime} if runtime else None),+ )+ session.add(agent)+ await session.flush()+ return agent+++async def _join(session: AsyncSession, client: Client, room: Room) -> None:+ session.add(ClientRoom(client_id=client.id, room_id=room.id))+ await session.flush()+++async def _say(+ session: AsyncSession,+ room: Room,+ sender: Client,+ *,+ seq: int,+ when: datetime | None = None,+) -> Message:+ message = Message(+ room_id=room.id,+ seq=seq,+ transport_event_id=f"$evt-{uuid.uuid4().hex}",+ sender_id=sender.matrix_user_id,+ sender_client_id=sender.id,+ event_type="m.room.message",+ msgtype="m.text",+ body="hello",+ content={"body": "hello"},+ sent_at=when or (NOW - timedelta(hours=1)),+ )+ session.add(message)+ await session.flush()+ return message+++TENANT_ZERO = "00000000-0000-0000-0000-000000000000"+++async def _counts(session: AsyncSession, tenant_id: str = TENANT_ZERO) -> UsageCounts:+ counts = UsageCounts()+ await collect_tenant_counts(session, tenant_id, counts, NOW)+ return counts+++class TestWhatCountsAsActive:+ async def test_a_human_talking_to_an_agent_makes_the_room_active(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ agent = await _client(session, "agent")+ await _join(session, human, room)+ await _join(session, agent, room)+ await _say(session, room, human, seq=1)++ counts = await _counts(session)++ assert counts.room_active_1d == 1+ assert counts.user_active_1d == 1++ async def test_two_agents_talking_is_not_activity(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The product question is whether people are using it. An orchestration+ chatting to itself all night must not read as adoption."""+ async with session_factory() as session:+ room = await _room(session)+ one = await _client(session, "agent")+ two = await _client(session, "agent")+ await _join(session, one, room)+ await _join(session, two, room)+ await _say(session, room, one, seq=1)+ await _say(session, room, two, seq=2)++ counts = await _counts(session)++ assert counts.room_active_1d == 0+ assert counts.user_active_1d == 0++ async def test_a_human_in_a_room_with_no_agent_is_not_activity(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ await _join(session, human, room)+ await _say(session, room, human, seq=1)++ counts = await _counts(session)++ assert counts.room_active_1d == 0++ async def test_a_bridge_relay_is_not_a_person(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """`bridge`, `admin` and `observe` are machinery. Counting them as+ users would make every bridged deployment look busier than it is."""+ async with session_factory() as session:+ room = await _room(session)+ agent = await _client(session, "agent")+ await _join(session, agent, room)+ for machinery in ("bridge", "admin", "observe"):+ relay = await _client(session, machinery)+ await _join(session, relay, room)+ await _say(session, room, relay, seq=100 + len(machinery))++ counts = await _counts(session)++ assert counts.user_active_1d == 0+ assert counts.room_active_1d == 0++ async def test_the_day_and_week_windows_differ(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ agent = await _client(session, "agent")+ await _join(session, human, room)+ await _join(session, agent, room)+ await _say(session, room, human, seq=1, when=NOW - timedelta(days=3))++ counts = await _counts(session)++ assert counts.room_active_1d == 0+ assert counts.room_active_7d == 1+++class TestRoomsAreCountedByWhoMadeThem:+ async def test_a_user_created_room_is_the_headline_figure(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await _room(session, created_by_kind="user")+ await _room(session, created_by_kind="agent")++ counts = await _counts(session)++ assert counts.room_count == 1+ assert counts.room_agent_created_count == 1++ async def test_a_room_predating_the_stamp_counts_as_user_created(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The conservative reading: agent-created is the newer path, so an+ unstamped room is far more likely to be one a person made."""+ async with session_factory() as session:+ await _room(session, created_by_kind=None)++ counts = await _counts(session)++ assert counts.room_count == 1+ assert counts.room_agent_created_count == 0++ async def test_archived_rooms_leave_the_live_count(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await _room(session)+ await _room(session, archived=True)++ counts = await _counts(session)++ assert counts.room_count == 1+ assert counts.room_archived_count == 1+++class TestTurns:+ """Who is actually talking to whom."""++ async def test_an_agent_answering_a_person_is_a_human_to_agent_turn(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ agent = await _client(session, "agent")+ await _say(session, room, human, seq=1)+ await _say(session, room, agent, seq=2)+ await _say(session, room, human, seq=3)++ counts = await _counts(session)++ assert counts.turn_human_to_agent_1d == 1+ assert counts.turn_agent_to_human_1d == 1+ assert counts.turn_agent_to_agent_1d == 0++ async def test_two_agents_are_agent_to_agent_turns(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The distinction a sender-only count cannot make: both of these are+ "a message from an agent", and only one is a conversation with a+ person."""+ async with session_factory() as session:+ room = await _room(session)+ one = await _client(session, "agent")+ two = await _client(session, "agent")+ await _say(session, room, one, seq=1)+ await _say(session, room, two, seq=2)+ await _say(session, room, one, seq=3)++ counts = await _counts(session)++ assert counts.turn_agent_to_agent_1d == 2+ assert counts.turn_human_to_agent_1d == 0++ async def test_the_first_message_in_a_room_is_not_a_turn(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ await _say(session, room, human, seq=1)++ counts = await _counts(session)++ assert counts.turn_human_to_agent_1d == 0+ assert counts.turn_agent_to_human_1d == 0+ assert counts.turn_agent_to_agent_1d == 0++ async def test_turns_do_not_pair_across_rooms(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Two rooms interleaved in time must not make each other's messages+ look like replies."""+ async with session_factory() as session:+ first = await _room(session)+ second = await _room(session)+ human = await _client(session, "user")+ agent = await _client(session, "agent")+ await _say(session, first, human, seq=1)+ await _say(session, second, agent, seq=1)++ counts = await _counts(session)++ assert counts.turn_human_to_agent_1d == 0+++class TestMessageCounts:+ async def test_messages_are_split_by_sender_kind(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ agent = await _client(session, "agent")+ await _say(session, room, human, seq=1)+ await _say(session, room, agent, seq=2)+ await _say(session, room, agent, seq=3)++ counts = await _counts(session)++ assert counts.message_count_1d == 3+ assert counts.message_from_human_1d == 1+ assert counts.message_from_agent_1d == 2++ async def test_backfilled_history_is_not_traffic(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Reconstructed history is numbered below zero. Importing a year of+ Slack must not read as a year's usage arriving today."""+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ await _say(session, room, human, seq=-1)+ await _say(session, room, human, seq=-2)++ counts = await _counts(session)++ assert counts.message_count_1d == 0+++class TestAgentsAndConnectors:+ async def test_agents_are_split_by_runtime(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ for runtime in ("claude-code", "codex", "opencode", "something-new", None):+ await _agent(session, runtime)++ counts = await _counts(session)++ assert counts.agent_count == 5+ assert counts.agent_claude_code_count == 1+ assert counts.agent_codex_count == 1+ assert counts.agent_opencode_count == 1+ assert counts.agent_other_count == 2++ async def test_connectors_are_counted_per_platform(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ for platform in ("slack", "slack", "teams"):+ client = await _client(session, "bridge")+ session.add(+ CollaborationBridge(+ type=platform,+ display_name=f"{platform} workspace",+ client_id=client.id,+ status="active",+ )+ )+ await session.flush()++ counts = await _counts(session)++ assert counts.connector_counts["slack"] == 2+ assert counts.connector_counts["teams"] == 1+ assert counts.connector_counts["discord"] == 0+ assert counts.connector_configured_count == 3+++class TestMembership:+ async def test_only_humans_count_towards_users_in_rooms(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ for _ in range(3):+ await _join(session, await _client(session, "user"), room)+ await _join(session, await _client(session, "agent"), room)+ await _join(session, await _client(session, "bridge"), room)++ counts = await _counts(session)++ assert counts.room_membership_total == 3+ assert counts.room_users_max == 3+++class TestNewlyActiveRooms:+ async def test_a_room_reports_when_a_person_first_speaks_in_it(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ created = NOW - timedelta(hours=5)+ async with session_factory() as session:+ room = await _room(session, created_at=created)+ human = await _client(session, "user")+ await _say(session, room, human, seq=1, when=NOW - timedelta(hours=2))+ await session.commit()++ found = await newly_active_rooms(+ session_factory, since=NOW - timedelta(hours=4), now=NOW+ )++ assert len(found) == 1+ assert found[0].seconds_since_room_created == 3 * 3600+ assert found[0].created_by_kind == "user"++ async def test_a_room_already_active_before_the_window_is_not_reported_again(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """What makes this once-per-room without storing anything: the room+ qualifies only if its *earliest* human message is inside the window."""+ async with session_factory() as session:+ room = await _room(session, created_at=NOW - timedelta(days=10))+ human = await _client(session, "user")+ await _say(session, room, human, seq=1, when=NOW - timedelta(days=9))+ await _say(session, room, human, seq=2, when=NOW - timedelta(hours=1))+ await session.commit()++ found = await newly_active_rooms(+ session_factory, since=NOW - timedelta(hours=4), now=NOW+ )++ assert found == []++ async def test_an_agent_only_room_never_becomes_active(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ agent = await _client(session, "agent")+ await _say(session, room, agent, seq=1, when=NOW - timedelta(hours=1))+ await session.commit()++ found = await newly_active_rooms(+ session_factory, since=NOW - timedelta(hours=4), now=NOW+ )++ assert found == []+++class TestRoomHadHumanActivity:+ async def test_it_reports_whether_a_person_ever_posted(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ quiet = await _room(session)+ busy = await _room(session)+ human = await _client(session, "user")+ await _say(session, busy, human, seq=1)++ assert await room_had_human_activity(session, TENANT_ZERO, busy.id) is True+ assert (+ await room_had_human_activity(session, TENANT_ZERO, quiet.id) is False+ )+++class TestTheDeploymentTotal:+ async def test_users_are_counted_once_for_the_deployment(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """`users` carries no tenant, so summing it per tenant would multiply+ it by however many tenants there are."""+ async with session_factory() as session:+ await _room(session)+ await session.commit()++ counts = await collect_usage(session_factory, now=NOW)++ assert counts.tenant_count >= 1+ assert counts.room_count == 1+++class TestTheDerivedProperties:+ def test_the_mean_is_zero_rather_than_a_division_by_zero(self) -> None:+ counts = UsageCounts()+ properties = counts.as_event_properties(session_live_count=0)+ assert properties["room_users_mean"] == 0.0++ def test_every_platform_reports_even_with_none_configured(self) -> None:+ """The catalogue requires every key every time, so a deployment with no+ Discord bridge reports zero rather than omitting the property."""+ properties = UsageCounts().as_event_properties(session_live_count=0)+ for platform in ("slack", "mattermost", "discord", "teams", "telegram"):+ assert properties[f"connector_{platform}_count"] == 0++ def test_the_properties_match_the_catalogue_exactly(self) -> None:+ from switch_core.telemetry.catalogue import CATALOGUE++ properties = UsageCounts().as_event_properties(session_live_count=3)+ assert set(properties) == set(CATALOGUE["usage_snapshot"])+++class TestNormalising:+ def test_the_pre_rename_channel_type_is_mapped(self) -> None:+ """`group` predates the catalogue's vocabulary; passing it through+ would raise at emission and take a room creation down with it."""+ assert normalise_channel_type("group") == "channel_private"+ assert normalise_channel_type("channel") == "channel_public"+ assert normalise_channel_type("channel_public") == "channel_public"+ assert normalise_channel_type(None) == "none"+ assert normalise_channel_type("something-new") == "none"++ def test_an_unknown_platform_becomes_none(self) -> None:+ assert normalise_platform("slack") == "slack"+ assert normalise_platform(None) == "none"+ assert normalise_platform("irc") == "none"++ def test_a_runtime_switch_does_not_know_becomes_other(self) -> None:+ assert normalise_known_agent_type({"known_agent_type": "codex"}) == "codex"+ assert normalise_known_agent_type({"known_agent_type": "zed"}) == "other"+ assert normalise_known_agent_type({}) == "none"+ assert normalise_known_agent_type(None) == "none"+++class TestTheThreeRoomOrigins:+ """A bridge-adopted channel is not a room a person made.++ The headline figure was written as "not agent-created", which quietly+ folded in the third kind this change introduces — every channel Switch was+ invited to on a platform. On a busy Slack that is most of them.+ """++ async def test_each_origin_is_counted_separately(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await _room(session, created_by_kind="user")+ await _room(session, created_by_kind="agent")+ await _room(session, created_by_kind="system")+ await _room(session, created_by_kind="system")++ counts = await _counts(session)++ assert counts.room_count == 1+ assert counts.room_agent_created_count == 1+ assert counts.room_system_created_count == 2++ async def test_the_mean_cannot_exceed_the_maximum(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """Numerator and denominator must count the same rooms. Over different+ populations the pair can report a mean above the maximum, which is+ impossible for any one set and reads as a broken metric."""+ async with session_factory() as session:+ mine = await _room(session, created_by_kind="user")+ theirs = await _room(session, created_by_kind="agent")+ await _join(session, await _client(session, "user"), mine)+ # An agent-created room legitimately holds people.+ for _ in range(5):+ await _join(session, await _client(session, "user"), theirs)++ counts = await _counts(session)++ properties = counts.as_event_properties(session_live_count=0)+ assert properties["room_users_mean"] <= properties["room_users_max"]+ assert counts.room_membership_total == 1+++class TestNormaliseActorKind:+ def test_an_unstamped_room_reads_as_user(self) -> None:+ assert normalise_actor_kind(None) == "user"++ def test_the_three_kinds_pass_through(self) -> None:+ assert normalise_actor_kind("user") == "user"+ assert normalise_actor_kind("agent") == "agent"+ assert normalise_actor_kind("system") == "system"++ def test_an_unknown_kind_reads_as_system_rather_than_raising(self) -> None:+ """A later kind added without touching this file must not be able to+ fail a room creation at the point of emission."""+ assert normalise_actor_kind("imported") == "system"+++class TestATurnNeedsTwoParticipants:+ """A turn is a reply, so the two sides must be different participants.++ Agents normally answer in several messages. Pairing on the sender's *kind*+ alone scored each of those as an agent-to-agent turn, so the figure meant+ to show "two agents talking among themselves" was dominated by one agent+ talking to a person.+ """++ async def test_one_agent_posting_twice_is_not_an_agent_to_agent_turn(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ agent = await _client(session, "agent")+ await _say(session, room, human, seq=1)+ # One agent answering across three messages, as agents do.+ await _say(session, room, agent, seq=2)+ await _say(session, room, agent, seq=3)+ await _say(session, room, agent, seq=4)++ counts = await _counts(session)++ assert counts.turn_human_to_agent_1d == 1+ assert counts.turn_agent_to_agent_1d == 0++ async def test_two_different_agents_still_count(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ one = await _client(session, "agent")+ two = await _client(session, "agent")+ await _say(session, room, one, seq=1)+ await _say(session, room, two, seq=2)++ counts = await _counts(session)++ assert counts.turn_agent_to_agent_1d == 1++ async def test_a_person_repeating_themselves_is_not_a_turn_either(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ room = await _room(session)+ human = await _client(session, "user")+ agent = await _client(session, "agent")+ await _say(session, room, agent, seq=1)+ await _say(session, room, human, seq=2)+ await _say(session, room, human, seq=3)++ counts = await _counts(session)++ assert counts.turn_agent_to_human_1d == 1diff --git a/core/tests/switch_core/telemetry/test_snapshot_multi_tenant.py b/core/tests/switch_core/telemetry/test_snapshot_multi_tenant.pynew file mode 100644index 000000000..58fe16a26--- /dev/null+++ b/core/tests/switch_core/telemetry/test_snapshot_multi_tenant.py@@ -0,0 +1,156 @@+"""The snapshot's counts must not multiply by the number of tenants.++This is the regression test for the defect a review found: every query in+`collect_tenant_counts` leaned on row-level security to narrow it, and the+policy is exactly what does *not* apply on an owner connection. A fan-out that+binds each tenant in turn then reads every tenant's rows on every pass, so a+deployment with N tenants reported N times its real size — silently, because a+count has no shape that looks wrong.++`db/tenant_lookup.py` states the rule and every other fan-out in the tree+follows it. These tests exist because the single-tenant tests next door cannot+fail on it: with one tenant, N == 1.++The default `session_factory` fixture connects as the owner, which is the+connection where the bug was reachable — so this file needs no special+harness to reproduce it. That is the point: CI runs the vulnerable shape.+"""++from __future__ import annotations++import uuid+from datetime import UTC, datetime, timedelta++from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.db.models import (+ TENANT_ZERO_ID,+ Client,+ ClientRoom,+ Message,+ Room,+ Tenant,+)+from switch_core.db.session_scope import tenant_session+from switch_core.telemetry.snapshot import collect_usage, newly_active_rooms++NOW = datetime(2026, 9, 16, 12, 0, tzinfo=UTC)+OTHER_TENANT = "11111111-1111-1111-1111-111111111111"+++async def _make_tenant(session_factory: async_sessionmaker[AsyncSession]) -> None:+ async with session_factory() as session:+ session.add(+ Tenant(id=OTHER_TENANT, name="second", slug=f"s-{uuid.uuid4().hex[:8]}")+ )+ await session.commit()+++async def _room_with_a_conversation(+ session_factory: async_sessionmaker[AsyncSession],+ tenant_id: str,+ *,+ first_at: datetime,+) -> None:+ """One room, one human, one agent, one human message."""+ async with tenant_session(session_factory, tenant_id) as session:+ room = Room(+ matrix_room_id=f"!{uuid.uuid4().hex[:10]}:test",+ name=f"room-{uuid.uuid4().hex[:6]}",+ description="a room",+ channel_type="channel_public",+ created_at=NOW - timedelta(days=2),+ metadata_={"created_by_kind": "user"},+ )+ human = Client(+ matrix_user_id=f"@human-{uuid.uuid4().hex[:8]}:test",+ display_name="a person",+ type="user",+ )+ agent = Client(+ matrix_user_id=f"@agent-{uuid.uuid4().hex[:8]}:test",+ display_name="an agent",+ type="agent",+ )+ session.add_all([room, human, agent])+ await session.flush()+ session.add_all(+ [+ ClientRoom(client_id=human.id, room_id=room.id),+ ClientRoom(client_id=agent.id, room_id=room.id),+ ]+ )+ session.add(+ Message(+ room_id=room.id,+ seq=1,+ transport_event_id=f"$evt-{uuid.uuid4().hex}",+ sender_id=human.matrix_user_id,+ sender_client_id=human.id,+ event_type="m.room.message",+ msgtype="m.text",+ body="hello",+ content={"body": "hello"},+ sent_at=first_at,+ )+ )+ await session.commit()+++class TestCountsDoNotMultiplyByTenant:+ async def test_two_tenants_with_one_room_each_report_two_rooms(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await _make_tenant(session_factory)+ await _room_with_a_conversation(+ session_factory, TENANT_ZERO_ID, first_at=NOW - timedelta(hours=1)+ )+ await _room_with_a_conversation(+ session_factory, OTHER_TENANT, first_at=NOW - timedelta(hours=1)+ )++ counts = await collect_usage(session_factory, now=NOW)++ assert counts.tenant_count == 2+ # Two, not four. Without the tenant predicate each pass saw both rooms.+ assert counts.room_count == 2+ assert counts.room_active_1d == 2+ assert counts.user_active_1d == 2+ assert counts.message_count_1d == 2+ assert counts.room_membership_total == 2++ async def test_one_tenants_room_is_not_counted_by_the_other(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """The sharper version: the second tenant owns nothing at all, so every+ count must be exactly what the first tenant has."""+ await _make_tenant(session_factory)+ await _room_with_a_conversation(+ session_factory, TENANT_ZERO_ID, first_at=NOW - timedelta(hours=1)+ )++ counts = await collect_usage(session_factory, now=NOW)++ assert counts.tenant_count == 2+ assert counts.room_count == 1+ assert counts.room_active_7d == 1+ assert counts.user_active_7d == 1+ assert counts.message_count_1d == 1+++class TestRoomActivationIsNotReportedPerTenant:+ async def test_a_room_is_reported_once_not_once_per_tenant(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ """`room_became_active` is emitted per returned row, so a duplicate here+ is a duplicated analytics event, not just a wrong count."""+ await _make_tenant(session_factory)+ await _room_with_a_conversation(+ session_factory, TENANT_ZERO_ID, first_at=NOW - timedelta(hours=1)+ )++ found = await newly_active_rooms(+ session_factory, since=NOW - timedelta(hours=4), now=NOW+ )++ assert len(found) == 1diff --git a/deploy/remote/helm/switch/templates/_helpers.tpl b/deploy/remote/helm/switch/templates/_helpers.tplindex a7fd805f2..1c12f980e 100644--- a/deploy/remote/helm/switch/templates/_helpers.tpl+++ b/deploy/remote/helm/switch/templates/_helpers.tpl@@ -649,6 +649,14 @@ Include with `nindent 12`.{{- end }}{{- end }}{{- end }}+- name: TELEMETRY_ENABLED+ value: {{ .Values.switchCore.telemetry.enabled | quote }}+{{- if .Values.switchCore.telemetry.enabled }}+- name: TELEMETRY_ENDPOINT+ value: {{ .Values.switchCore.telemetry.endpoint | quote }}+- name: TELEMETRY_SNAPSHOT_INTERVAL_HOURS+ value: {{ .Values.switchCore.telemetry.snapshotIntervalHours | quote }}+{{- end }}# switch-core sits behind the cluster/ALB and enforces its own# BearerAuthMiddleware, so fastmcp's browser-oriented DNS-rebinding# Host/Origin guard (default-on since mcp 1.28) only rejects thediff --git a/deploy/remote/helm/switch/values.yaml b/deploy/remote/helm/switch/values.yamlindex 4ecf47967..d6fde02fa 100644--- a/deploy/remote/helm/switch/values.yaml+++ b/deploy/remote/helm/switch/values.yaml@@ -166,6 +166,28 @@ switchCore:# collector that is slow or far away.timeoutSeconds: 10+ # Anonymous product telemetry: usage counts and timings reported to the+ # Flint relay, which is the same pipeline Switch Console reports to.+ #+ # Off by default, and that is deliberate — this deployment's usage may be+ # yours rather than ours, so reporting it is a choice you make rather than+ # one you discover. When it is off nothing is collected and no request is+ # made.+ #+ # Nothing that identifies anything inside the deployment is ever sent: no+ # room, tenant, agent, user or message id, no names, no message content, and+ # no free text of any kind. What is sent is counts (how many rooms, how many+ # active users, how much traffic) and durations (how long from install to a+ # working connector). The full list is in docs/old/telemetry-events.md and+ # is enforced in code, not just documented.+ telemetry:+ enabled: false+ # Base URL, no path — `/v1/logs` is appended, the same+ # convention otlpEndpoint follows.+ endpoint: https://telemetry.flintai.dev+ # How often the usage snapshot is collected and sent.+ snapshotIntervalHours: 24+# Public base URL the gateway is served on (used for links / OIDC redirects).frontendBaseUrl: ""# Public origin (scheme + host, no path) of the gateway HTTP API itself, useddiff --git a/docs/old/telemetry-events.md b/docs/old/telemetry-events.mdnew file mode 100644index 000000000..358261678--- /dev/null+++ b/docs/old/telemetry-events.md@@ -0,0 +1,734 @@+# 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](#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.name` attribute.+- **The event name is sent twice** — as the log record's own `eventName` field+ and as an `event.name` attribute. 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 sends+ `switch_core.<event>`.++## 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 the catalogue. 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` |+| `service.version` | the running version, as `/version` reports it |+| `flint.client_id` | the per-deployment id |+| `deployment.environment` | from the existing `ENVIRONMENT` setting |++`deployment.environment` is the OpenTelemetry-conventional name and is already a+server setting. The Console instead sends a bespoke `build` attribute+(`dev`/`canary`/`stable`), which is a desktop release-channel notion with no+server equivalent. The two are deliberately different fields rather than one+field meaning different things on each side.++## Three kinds of event++**A daily snapshot**, one per deployment, carrying the counts that describe the+installation. This answers "how much".++**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.++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.++### Why there is no `message_sent` event++Message volume is reported as a count in the daily snapshot, not as an event per+message. Three reasons, in order of weight:++1. **Volume.** The relay path has no batching, no retry and no queue — one HTTP+ request per event, fire-and-forget, because a desktop app emits a handful an+ hour. A busy server emits thousands of messages an hour. Per-message events+ would be a different class of load on a component not built for it.+2. **It answers nothing extra.** Without a room id, a per-message event supports+ the same charts the snapshot count does.+3. **Content risk.** An event shaped around a message is the one most likely to+ grow a property that reveals something about the message. Not having it+ removes the temptation.++If per-message granularity is ever genuinely needed, it should arrive with+batching on the export path first.++## 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 on the deployment |+| `user_count` | number | user accounts that exist |+| `user_active_1d` | number | distinct humans who interacted in 24h |+| `user_active_7d` | number | same over 7 days |+| `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_slack_count` | number | **configured** bridges by platform |+| `connector_mattermost_count` | number | |+| `connector_discord_count` | number | |+| `connector_teams_count` | number | |+| `connector_telegram_count` | number | |+| `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.++**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.++### 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](#deployment-identity-and-the-install-clock).++| Event | Emitted when | Extra properties |+|---|---|---|+| `deployment_installed` | the deployment id is generated on an empty database | — |+| `first_connector_added` | any bridge first 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 session opens | `known_agent_type` |++The two room milestones track user-created rooms only, for the reason given+under [Definitions](#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_first_connector` | boolean |+| `failed_attempts_before_success` | number |++`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 |+| `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`+(boolean).++**`room_agents_added`** — `agent_count` (number), `added_by_kind`.++**`room_agents_removed`** — `agent_count` (number), `removed_by_kind`.++### 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`, `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`,+`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.++**`agent_registered`**++| Property | Type |+|---|---|+| `agent_type` | `always_on` \| `session_addressable` \| `session_passive` |+| `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_session_started`** — `known_agent_type`. Deliberately nothing about+*how* the session was started: the server sees an authenticated connection+whether a person launched it or Switch Console spawned it, and a property that+takes the same value on every emission is a dimension that cannot segment+anything.++**`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_platform`, `outcome`, `failure_reason`.++**`bridge_disconnected`** — `bridge_platform`, `reason`+(`shutdown` \| `restart` \| `auth_failed` \| `network` \| `platform_error` \|+`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.++### Closed value sets++`bridge_platform`: `slack` | `mattermost` | `discord` | `teams` | `telegram` |+`none`.++`outcome`: `success` | `failure`. `failure_reason` is an enumerated code per+event, `none` on success — never an exception message.++`bridge_connected.failure_reason` and `bridge_disconnected.reason` share one+set, 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.++Where a duration cannot be known — a deployment with no install clock, a bridge+whose configuration timestamp is unreadable — the property carries `-1` rather+than `0`, so "we could not tell" is distinguishable from "it happened+instantly".++Any property whose value is not in its set is a bug. It should raise where the+event is built rather than be coerced, dropped, or sent as `unknown` — a+silently-widening value set is how an analytics catalogue stops being+trustworthy.++## 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.++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:++1. **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.+2. **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.+3. **The consent gate inside the send**, so that no call site can bypass it and+ no new event can forget it.+4. **The deployment id and `installed_at`**, generated and persisted once.+5. **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.++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++Twenty-two events. 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_at` is null and the six `first_*` 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`. Check `created_by_kind` is `user`+ here, `agent` when an agent creates one through its MCP tool, and `system`+ when 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's+ `archive_room` tool. Unarchiving emits nothing.+- `room_deleted` — `DELETE /gateway/rooms/{id}`. Check `was_ever_active` is+ 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_path` should be+ `gateway` from the dashboard or Console, `personal_key` from a user's own+ registration key, `bootstrap` from 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_started` — an agent opening its event stream. A supervisor+ reattaching to a connection it already had correctly emits nothing.+- `first_session_started` — the same, once ever.+- `agent_session_ended` — 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.++**Connectors** — `bridges/collaboration/lifecycle_service.py`++- `bridge_connected` — a bridge reaching its platform. Also fires with+ `outcome: failure` when 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 on the deployment.+- `bridge_disconnected` — stopping a bridge (`reason: shutdown`), restarting+ one (`restart`), or a live bridge crashing.+- `connector_removed` — `DELETE /gateway/collaborations/{id}`. Check+ `was_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 as `other`, because its slug is+ free text somebody chose.+- `document_created` / `document_attached_to_room` / `document_deleted` —+ `scope` is `library` for one in the shared library and `room` for 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_kind` names the three the+ product uses and reports anything an operator invents as `other`.+- `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. Many of these and few `bridge_connected` is a deployment+ whose setup is failing, and only the pair shows it.+- `server_connector_registered` / `server_connector_removed`.++**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 fifteen queries per tenant,+ including two seven-day `DISTINCT` scans over `messages` and 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.diff --git a/scripts/otlp_sink.py b/scripts/otlp_sink.pyindex 78219ca34..1cf08a56d 100644--- a/scripts/otlp_sink.py+++ b/scripts/otlp_sink.py@@ -78,11 +78,40 @@ def _render(attributes: list[dict[str, Any]]) -> str:return " {" + ", ".join(f"{k}={v}" for k, v in sorted(flat.items())) + "}"+def _summarise_events(records: list[dict[str, Any]]) -> list[str]:+ """Product events: the name, then every property.++ Nothing is truncated. The point of watching these is to check exactly what+ a deployment would report, and a property elided as "… and 6 more" is+ precisely the one that might not belong on the wire.+ """+ lines = []+ for record in records:+ attributes = _attributes(record.get("attributes", []))+ name = attributes.pop("event.name", record.get("eventName", "?"))+ if record.get("eventName") != name:+ # Both places must carry it: the relay filters on the attribute and+ # the exporter reads the field. One without the other is accepted+ # with a 200 and then silently dropped.+ lines.append(f" !! {name}: eventName field is {record.get('eventName')!r}")+ lines.append(f" ▸ {name}")+ for key in sorted(attributes):+ lines.append(f" {key:<34} {attributes[key]!r}")+ return lines++def _summarise_logs(payload: dict[str, Any]) -> list[str]:lines = []for resource in payload.get("resourceLogs", []):for scope in resource.get("scopeLogs", []):records = scope.get("logRecords", [])+ # A product event is a log record carrying an event name, and it+ # wants the opposite treatment from a log line: every property+ # matters and there is one record per request, where a log batch+ # is many records of which the first few are representative.+ if records and "eventName" in records[0]:+ lines.extend(_summarise_events(records))+ continuelevels = Counter(record.get("severityText", "?") for record in records)lines.append(f" {len(records)} record(s): "@@ -107,6 +136,8 @@ def _summarise_logs(payload: dict[str, Any]) -> list[str]:class Handler(BaseHTTPRequestHandler):raw = False+ reject = 0+ fail_with = 0# Keep-alive, like a real collector. The default is HTTP/1.0, where closing# the connection delimits the response — which curl accepts and a pooling# client reports as "server disconnected without sending a response".@@ -116,7 +147,25 @@ class Handler(BaseHTTPRequestHandler):length = int(self.headers.get("Content-Length", 0))body = self.rfile.read(length)# Answer first: a slow collector is indistinguishable from a broken one.- reply = b'{"partialSuccess":{}}'+ if self.fail_with:+ self.send_response(self.fail_with)+ self.send_header("Content-Length", "0")+ self.end_headers()+ print(+ f"[{datetime.now(UTC):%H:%M:%S}] refused with {self.fail_with}",+ flush=True,+ )+ return++ # A 200 does not mean a collector kept anything: OTLP reports partial+ # success in the body. `--reject` is how to check the sender notices.+ reply = (+ json.dumps(+ {"partialSuccess": {"rejectedLogRecords": str(self.reject)}}+ ).encode()+ if self.reject+ else b'{"partialSuccess":{}}'+ )self.send_response(200)self.send_header("Content-Type", "application/json")self.send_header("Content-Length", str(len(reply)))@@ -156,9 +205,25 @@ def main() -> None:parser.add_argument("--raw", action="store_true", help="print the full JSON payload")+ parser.add_argument(+ "--reject",+ type=int,+ default=0,+ metavar="N",+ help="claim N records were rejected inside a 200, to check the sender notices",+ )+ parser.add_argument(+ "--fail",+ type=int,+ default=0,+ metavar="CODE",+ help="answer every request with this HTTP status instead of accepting it",+ )args = parser.parse_args()Handler.raw = args.raw+ Handler.reject = args.reject+ Handler.fail_with = args.failtry:server = ThreadingHTTPServer(("127.0.0.1", args.port), Handler)except OSError as error: