Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

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.py
index 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 annotations
import hashlib
import logging
+from contextvars import ContextVar
from datetime import UTC, datetime
from 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, ProtocolService
from switch_core.bridges.agent.protocol.stream import event_stream
from 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.py
new file mode 100644
index 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.py
index 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_route
from switch_core.bridges.agent.api_key_cache import ApiKeyCache
from switch_core.bridges.agent.auth import BearerAuthMiddleware
from 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_dependencies
from switch_core.bridges.agent.mcp import create_mcp_app
from switch_core.bridges.agent.protocol.connections import ConnectionRegistry
from switch_core.bridges.agent.protocol.event_buffer import EventBuffer
@@ -36,6 +36,7 @@ from switch_core.request_context import RequestContextMiddleware
from switch_core.room_service import RoomService
from switch_core.sessions.http import session_error_response
from switch_core.sessions.service import SessionError
+from switch_core.telemetry import TelemetryService
logger = 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.py
index 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 ExternalUserStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.task_store import TaskStore
from 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.py
index 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 annotations
import asyncio
import logging
import time
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
from dataclasses import dataclass, field
from 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: None
self._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 conn
def 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.py
index 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_url
from switch_core.aliases import check_alias_collisions, validate_alias_format
from switch_core.attachments import parse_attachment_group
from switch_core.authz import Action, Principal, require, require_manage
+from switch_core.bridges.agent.api.session_reporter import SessionReporter
from switch_core.bridges.agent.api_key_cache import ApiKeyCache
from switch_core.bridges.agent.mediation import MediationService
from 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_TYPE
from 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_type
from switch_core.tenant_context import current_tenant_id, tenant_scope
from 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_store
self.agent_session_store = agent_session_store
self.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_id
resolved_id = agent.id
resolved_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.py
index 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_session
from switch_core.db.stores.api_key_store import ApiKeyStore
from switch_core.db.stores.server_connector_store import ServerConnectorStore
from switch_core.db.tenant_lookup import all_tenant_ids, tenant_of_server_connector
+from switch_core.telemetry import TelemetryService, emit_safely
logger = 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_store
self._api_key_store = api_key_store
self._protocol = protocol
self._session_factory = session_factory
+ self._telemetry = telemetry
self._encryption_secret = encryption_secret
self._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.py
index 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
+
@contextmanager
def _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, _ = existing
await 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.py
index 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 annotations
import asyncio
import logging
import re
+from datetime import UTC, datetime
from typing import TYPE_CHECKING
from uuid import uuid4
@@ -27,6 +28,13 @@ from switch_core.db.stores.session_request_post_store import SessionRequestPostS
from switch_core.db.tenant_lookup import all_tenant_ids, tenant_of_collaboration_bridge
from switch_core.deeplinks import gateway_url_warning
from 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_platform
from switch_core.tenant_context import current_tenant_id, no_tenant
if 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_store
self._external_user_store = external_user_store
@@ -81,6 +131,7 @@ class CollaborationBridgeLifecycleService:
self._agent_store = agent_store
self._client_store = client_store
self._client_lifecycle = client_lifecycle
+ self._telemetry = telemetry
self._room_service = room_service
self._matrix_admin = matrix_admin
self._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 each
delivery 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 = False
try:
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 edit
is 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 keys
refuse.
"""
+ # 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.py
index 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 annotations
import logging
import re
from dataclasses import dataclass
+from datetime import UTC, datetime
from typing import Any, Literal
from sqlalchemy import select
@@ -35,9 +36,33 @@ from switch_core.db.stores.package_store import PackageStore
from switch_core.db.stores.reference_store import ReferenceStore
from switch_core.db.stores.reference_type_store import ReferenceTypeStore
from switch_core.db.stores.room_link_store import RoomLinkStore
+from switch_core.telemetry import TelemetryService, emit_safely
logger = 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_576
REFERENCE_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 = telemetry
self._references = reference_store
self._reference_types = reference_type_store
self._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 created
async 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 created
async 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 detached
async 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 created
async 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 detached
async 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 created
async 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 created
async 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 created
async 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 detached
async 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: str
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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 annotations
import hashlib
import logging
import secrets
+from datetime import UTC, datetime
from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException
@@ -14,6 +15,7 @@ from switch_core.db.models import ApiKey, User
from switch_core.db.stores.api_key_store import ApiKeyStore
from switch_core.gateway.auth import get_current_user
from 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_safely
logger = 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.py
index 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 TemplateStore
from switch_core.db.stores.user_store import UserStore
from switch_core.room_service import RoomService
from 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.py
index 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, datetime
from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException, Response
@@ -11,6 +12,7 @@ from switch_core.db.stores.room_group_store import RoomGroupStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.gateway.auth import get_current_user, get_tenant_is_admin
from 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 e
await 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.py
index 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 RoomStore
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.auth import get_current_user, get_tenant_is_admin
from 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, RoomService
from switch_core.rooms_yaml import ProvisionResult, RoomYamlService, TemplateDocument
+from switch_core.telemetry import emit_safely
logger = 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.py
index 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 annotations
import re
+from datetime import UTC, datetime
from typing import Annotated
from urllib.parse import quote
@@ -31,6 +32,7 @@ from switch_core.db.stores.template_store import (
from switch_core.db.stores.user_store import UserStore
from switch_core.gateway.auth import get_current_user, get_tenant_is_admin
from 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_safely
from 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 e
await 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 e
await 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.py
index 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_response
from 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_safely
from switch_core.tenant_context import current_tenant_id
logger = 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_role
diff --git a/core/switch_core/main.py b/core/switch_core/main.py
index abc7fac56..8a24ae5ee 100644
--- a/core/switch_core/main.py
+++ b/core/switch_core/main.py
@@ -10,6 +10,7 @@ from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from pathlib import Path
+import httpx
import uvicorn
from alembic import command as alembic_command
from alembic.config import Config as AlembicConfig
@@ -136,6 +137,9 @@ from switch_core.observability.runtime import EventLoopLag
from switch_core.provisioning import Provisioning
from switch_core.provisioning.postgres import PostgresProvisioning
from 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_telemetry
from switch_core.tenant_context import no_tenant
from switch_core.transport.ephemeral import EphemeralBus
from 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,
+ )
+
@asynccontextmanager
async 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:
yield
finally:
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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 annotations
import logging
-from typing import TYPE_CHECKING, Any
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, Literal
from pydantic import BaseModel
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -36,6 +37,13 @@ from switch_core.db.stores.collaboration_bridge_store import CollaborationBridge
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.tenant_lookup import all_tenant_ids
from 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_scope
if 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: str
label: str
@@ -111,6 +132,11 @@ class RoomCreateConfig(BaseModel):
aliases: dict[str, str] | None = None
acting_user_id: str | None = None
acting_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 = False
class 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_admin
self._room_store = room_store
@@ -147,6 +180,9 @@ class RoomService:
self._collab_bridge_store = collab_bridge_store
self._resource_service = resource_service
self._session_factory = session_factory
+ # Optional because several tests and tooling build a RoomService
+ # without one; `emit_safely` treats None as "report nothing".
+ self._telemetry = telemetry
async 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_id
client_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 None
if 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 unresolved
async def link_bridge_to_room(
diff --git a/core/switch_core/rooms_yaml.py b/core/switch_core/rooms_yaml.py
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 False
diff --git a/core/switch_core/telemetry/reporter.py b/core/switch_core/telemetry/reporter.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"] = name
diff --git a/core/switch_core/telemetry/snapshot.py b/core/switch_core/telemetry/snapshot.py
new file mode 100644
index 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.py
index 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 HTTPException
from starlette.responses import StreamingResponse
from switch_core.bridges.agent.api.handlers import _resolve_start_cursor, poll_events
+from switch_core.bridges.agent.api.session_reporter import SessionReporter
from 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 = False
self.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.py
index 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_roles
svc.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 svc
diff --git a/core/tests/switch_core/db/test_tenant_exemption_allowlist.py b/core/tests/switch_core/db/test_tenant_exemption_allowlist.py
index 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 a
diff --git a/core/tests/switch_core/db/test_tenant_schema_catalogue.py b/core/tests/switch_core/db/test_tenant_schema_catalogue.py
index 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` is
global 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"] == 2
diff --git a/core/tests/switch_core/telemetry/test_emitters_are_live.py b/core/tests/switch_core/telemetry/test_emitters_are_live.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/core/tests/switch_core/telemetry/test_merge_fixes.py b/core/tests/switch_core/telemetry/test_merge_fixes.py
new file mode 100644
index 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.py
new file mode 100644
index 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.0
diff --git a/core/tests/switch_core/telemetry/test_service_and_sink.py b/core/tests/switch_core/telemetry/test_service_and_sink.py
new file mode 100644
index 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.finished
diff --git a/core/tests/switch_core/telemetry/test_snapshot.py b/core/tests/switch_core/telemetry/test_snapshot.py
new file mode 100644
index 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 == 1
diff --git a/core/tests/switch_core/telemetry/test_snapshot_multi_tenant.py b/core/tests/switch_core/telemetry/test_snapshot_multi_tenant.py
new file mode 100644
index 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) == 1
diff --git a/deploy/remote/helm/switch/templates/_helpers.tpl b/deploy/remote/helm/switch/templates/_helpers.tpl
index 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 the
diff --git a/deploy/remote/helm/switch/values.yaml b/deploy/remote/helm/switch/values.yaml
index 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, used
diff --git a/docs/old/telemetry-events.md b/docs/old/telemetry-events.md
new file mode 100644
index 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.py
index 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))
+ continue
levels = 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.fail
try:
server = ThreadingHTTPServer(("127.0.0.1", args.port), Handler)
except OSError as error: