Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
Keep operator-set names out of usage telemetry (#735)
Christian McDermottc56333b91319
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 696e2d82d..d6723c1d3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -75,6 +75,17 @@ version of their own to them without also giving them a release of their own.and chat clients read such a host differently from Switch, so its checkscould not tell where the image would be loaded from.+#### Fixed+- **Usage telemetry no longer carries the `ENVIRONMENT` or `SERVICE_NAME`+ settings.** From 0.28.0 through 0.30.0, with `TELEMETRY_ENABLED=true`, every+ event sent to the Flint relay carried both, as `deployment.environment`,+ `service.name` and the OTLP scope name. They are free text an operator sets+ for their own logs (Helm `switchCore.logging.environment` and `serviceName`),+ so a value such as a company name left the deployment despite the promise of+ no free text. Usage events now always say `switch-core` and omit the+ environment; `flint_env` still says which Amplitude project they belong in.+ The operational OTLP export to your own collector is unchanged.+### [0.30.0] - 2026-10-12#### Added@@ -1666,6 +1677,12 @@ version of their own to them without also giving them a release of their own.returns it; Console only accepted the gateway's host and refused the sign-inas an invalid URL. It now accepts either of the server's own origins, overHTTPS. Google Workspace connects this way.+- **The usage-data note says what a "yes" does on a shared server.** The+ consent dialog and Settings said the answer applies to a server Console runs+ for you. On a server other people also run from their own Console, a "no"+ turns sharing off for everyone at your next start, while a "yes" leaves it as+ it is — on stays on, off stays off — unless none of them has used the server+ in the last 14 days. The note now says so.### [0.39.0] - 2026-10-12diff --git a/console/AGENTS.md b/console/AGENTS.mdindex dd2b873f9..47517ca13 100644--- a/console/AGENTS.md+++ b/console/AGENTS.md@@ -420,7 +420,11 @@ pnpm run lintreads it and writes `TELEMETRY_ENABLED` into the stack's `.env` on every start —`false` as explicitly as `true`, because the compose file forwards the key only whenthe `.env` names it, and a stack started under a yes would otherwise keep reporting.- Adding a variable to that contract needs both edits: `deploy/local/standalone-docker-compose.yml`+ On a shared SSH host a "yes" is written only when the stack already shares or no+ other Console has been seen on it lately (`shareUsageData` in `pipeline.ts`), so one+ user's yes never turns sharing on over the others; a "no" is always written. The+ scope note in `telemetry-copy.ts` and `docs/TELEMETRY.md` §4.1 state this to the+ user, and change with it. Adding a variable to that contract needs both edits: `deploy/local/standalone-docker-compose.yml`plus `pnpm run sync:compose`, and `env-file.ts`. The server reads the gate once atboot, so a running stack can be out of step; that is surfaced on the server's page witha restart offered, never applied by restarting the user's server for them. Whether itdiff --git a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/console-register.ts b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/console-register.tsindex d06bf8c6c..fadb01589 100644--- a/console/apps/switch-console-desktop/src/main/core/managed-switch-server/console-register.ts+++ b/console/apps/switch-console-desktop/src/main/core/managed-switch-server/console-register.ts@@ -19,9 +19,12 @@ import { CONSOLE_ID_PATTERN, UNDER_STATE_MUTEX } from './state-mutex';* Who uses a shared remote stack and what they last did to it, kept in its* state volume (CHOO-2893). Everyone signs in to the server as its one admin,* so the server cannot say who stopped it; each Console records itself in- * `consoles/<id>.json` and an appended `activity.jsonl` instead. It is a- * record, not a control: nothing is allowed or refused on its strength, and a- * Console that fails to write it still does what it was asked.+ * `consoles/<id>.json` and an appended `activity.jsonl` instead. It records+ * rather than controls: no action is allowed or refused on its strength, and a+ * Console that fails to write it still does what it was asked. The one decision+ * it feeds is a cautious one: a start keeps usage sharing off rather than apply+ * this Console's "yes" while others are seen on the server (`shareUsageData` in+ * `pipeline.ts`).*//** Only the latest entries are read back; the file keeps a few hundred. */diff --git a/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts b/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.tsindex b92d2b6e2..f295c6e11 100644--- a/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts+++ b/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts@@ -1,3 +1,5 @@+import { RECENTLY_SEEN_DAYS } from '@shared/core/managed-switch-server/managed-switch-server';+/*** The disclosure shown to the user, in one place so the first-run notice and* the Settings row cannot drift into promising different things.@@ -21,11 +23,14 @@ export const TELEMETRY_SUMMARY =** It governs a Switch server this app runs — the setting is written into that* server's configuration at every start — and it does not govern a server- * reached by URL, which is somebody else's deployment with its own answer. Both- * halves matter: the first is the promise, the second is the limit of it.+ * reached by URL, which is somebody else's deployment with its own answer. On a+ * server other Consoles use too, a "no" applies to everyone at the next start+ * from here, while a "yes" leaves the server as it is — sharing already on stays+ * on — unless nobody else has been seen on it lately (`shareUsageData` in the+ * managed-server pipeline). The first is the promise; the other two are its+ * limits.*/-export const TELEMETRY_SCOPE_NOTE =- 'The same answer applies to a Switch server this app runs for you. A server you connect to by URL is not covered — whoever operates it decides.';+export const TELEMETRY_SCOPE_NOTE = `The same answer applies to a Switch server this app runs for you. If other people use that server from their own Switch Console too, a no turns sharing off for everyone when you next start it, and a yes leaves it as it is unless none of them has used the server in the last ${RECENTLY_SEEN_DAYS} days. A server you connect to by URL is not covered — whoever operates it decides.`;export const TELEMETRY_DETAILS_LABEL = 'Read what is collected';diff --git a/core/switch_core/config.py b/core/switch_core/config.pyindex 4ab4f8c9a..af7e3a708 100644--- a/core/switch_core/config.py+++ b/core/switch_core/config.py@@ -398,9 +398,10 @@ class SwitchConfig(BaseSettings):# 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.+ # `docs/old/telemetry-events.md`: counts, durations and values from closed+ # sets, 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 samediff --git a/core/switch_core/telemetry/__init__.py b/core/switch_core/telemetry/__init__.pyindex 166831924..489fb6be1 100644--- a/core/switch_core/telemetry/__init__.py+++ b/core/switch_core/telemetry/__init__.py@@ -1,8 +1,9 @@"""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+Counts, durations and values from closed sets, 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`,diff --git a/core/switch_core/telemetry/service.py b/core/switch_core/telemetry/service.pyindex b0d440d6a..24d59e1c2 100644--- a/core/switch_core/telemetry/service.py+++ b/core/switch_core/telemetry/service.py@@ -40,9 +40,7 @@ class TelemetryService:sink: TelemetrySink,enabled: bool,client_id: str,- service_name: str,version: str | None,- environment: str | None,telemetry_environment: str,telemetry_internal: bool,session_factory: async_sessionmaker[AsyncSession] | None = None,@@ -55,7 +53,6 @@ class TelemetryService:self._session_factory = session_factoryself._installed_at = installed_atself._resource = {- "service.name": service_name,"flint.client_id": client_id,# The relay picks the Amplitude project from this. Sent even as# `prod`, so an event says where it belongs rather than relying on@@ -66,11 +63,9 @@ class TelemetryService:"flint_internal": "true" if telemetry_internal else "false",}# Omitted rather than sent empty: an absent attribute reads as "not- # configured", where `""` reads as a real environment named nothing.+ # known", where `""` reads as a real version named nothing.if version:self._resource["service.version"] = version- if environment:- self._resource["deployment.environment"] = environment@propertydef enabled(self) -> bool:diff --git a/core/switch_core/telemetry/setup.py b/core/switch_core/telemetry/setup.pyindex 5c348dfba..18f855b2c 100644--- a/core/switch_core/telemetry/setup.py+++ b/core/switch_core/telemetry/setup.py@@ -142,9 +142,7 @@ def _service(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,telemetry_environment=config.telemetry_environment,telemetry_internal=config.telemetry_internal,session_factory=session_factory,diff --git a/core/switch_core/telemetry/sink.py b/core/switch_core/telemetry/sink.pyindex b063e0a72..0e5f7e38d 100644--- a/core/switch_core/telemetry/sink.py+++ b/core/switch_core/telemetry/sink.py@@ -31,6 +31,9 @@ from switch_core.telemetry.catalogue import PropertyValuelogger = logging.getLogger(__name__)+# Fixed, so no operator-set text (service or environment name) reaches the relay.+_RELAY_SERVICE_NAME = "switch-core"+# 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.@@ -316,12 +319,13 @@ 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.+ observability package. The service name is fixed and the environment left+ out here, whatever the record carries."""return OtlpResource(- service_name=record.resource["service.name"],+ service_name=_RELAY_SERVICE_NAME,service_version=record.resource.get("service.version"),- environment=record.resource.get("deployment.environment"),+ environment=None,deployment_id=record.resource["flint.client_id"],commit_sha=None,repository_url=None,diff --git a/core/tests/benchmarks/server.py b/core/tests/benchmarks/server.pyindex 09b0d76d2..085e84caf 100644--- a/core/tests/benchmarks/server.py+++ b/core/tests/benchmarks/server.py@@ -496,9 +496,7 @@ async def _serve(sink=NullSink(),enabled=False,client_id="",- service_name="switch-core",version=None,- environment=None,telemetry_environment="dev",telemetry_internal=True,),diff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.pyindex 7f12f13c8..2f0eaf534 100644--- a/core/tests/integration/conftest.py+++ b/core/tests/integration/conftest.py@@ -601,9 +601,7 @@ async def harness(sink=NullSink(),enabled=False,client_id="",- service_name="switch-core",version=None,- environment=None,telemetry_environment="dev",telemetry_internal=True,),diff --git a/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.py b/core/tests/switch_core/bridges/agent/api/test_events_endpoint_dispatch.pyindex d979bc3e3..5ba393216 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@@ -462,9 +462,7 @@ class TestOpeningAStreamReportsASession:sink=sink, # type: ignore[arg-type]enabled=True,client_id="11111111-1111-1111-1111-111111111111",- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,)diff --git a/core/tests/switch_core/session_activity/test_session_started_route.py b/core/tests/switch_core/session_activity/test_session_started_route.pyindex b097ba00f..cbe78c73a 100644--- a/core/tests/switch_core/session_activity/test_session_started_route.py+++ b/core/tests/switch_core/session_activity/test_session_started_route.py@@ -52,9 +52,7 @@ def _telemetry(sink: _RecordingSink, *, enabled: bool) -> TelemetryService:sink=sink, # type: ignore[arg-type]enabled=enabled,client_id="11111111-1111-1111-1111-111111111111",- service_name="switch-core",version=None,- environment=None,telemetry_environment="prod",telemetry_internal=False,)diff --git a/core/tests/switch_core/telemetry/test_bridge_connect_reporting.py b/core/tests/switch_core/telemetry/test_bridge_connect_reporting.pyindex 09324f3fe..28a720b28 100644--- a/core/tests/switch_core/telemetry/test_bridge_connect_reporting.py+++ b/core/tests/switch_core/telemetry/test_bridge_connect_reporting.py@@ -76,9 +76,7 @@ def _service_with_telemetry(sink=sink, # type: ignore[arg-type]enabled=True,client_id="deployment-uuid",- service_name="switch-core",version=None,- environment=None,telemetry_environment="prod",telemetry_internal=False,session_factory=session_factory,diff --git a/core/tests/switch_core/telemetry/test_catalogue.py b/core/tests/switch_core/telemetry/test_catalogue.pyindex 9f2e9269f..62361d2c9 100644--- a/core/tests/switch_core/telemetry/test_catalogue.py+++ b/core/tests/switch_core/telemetry/test_catalogue.py@@ -76,7 +76,8 @@ class TestNothingIdentifyingCanBeSent:}assert not offenders, (f"{sorted(offenders)} name something inside a deployment. Telemetry "- "reports counts and durations only — see docs/old/telemetry-events.md. "+ "never identifies anything inside a deployment — 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.")diff --git a/core/tests/switch_core/telemetry/test_connector_setup_time.py b/core/tests/switch_core/telemetry/test_connector_setup_time.pyindex f0206ad5f..bbe033441 100644--- a/core/tests/switch_core/telemetry/test_connector_setup_time.py+++ b/core/tests/switch_core/telemetry/test_connector_setup_time.py@@ -33,9 +33,7 @@ def _switched_off(telemetry: TelemetryService) -> TelemetryService:sink=telemetry._sink,enabled=False,client_id="deployment-uuid",- service_name="switch-core",version=None,- environment=None,telemetry_environment="prod",telemetry_internal=False,session_factory=telemetry._session_factory,diff --git a/core/tests/switch_core/telemetry/test_deployment_and_reporter.py b/core/tests/switch_core/telemetry/test_deployment_and_reporter.pyindex 2acfd7639..85e295b2a 100644--- a/core/tests/switch_core/telemetry/test_deployment_and_reporter.py+++ b/core/tests/switch_core/telemetry/test_deployment_and_reporter.py@@ -171,9 +171,7 @@ class TestEmitMilestone:sink=sink, # type: ignore[arg-type]enabled=enabled,client_id="deployment-uuid",- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,session_factory=session_factory,@@ -234,9 +232,7 @@ class TestTheSnapshotSchedule:sink=sink, # type: ignore[arg-type]enabled=True,client_id="deployment-uuid",- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,session_factory=session_factory,diff --git a/core/tests/switch_core/telemetry/test_emitters_are_live.py b/core/tests/switch_core/telemetry/test_emitters_are_live.pyindex ac5c6793c..466c266ae 100644--- a/core/tests/switch_core/telemetry/test_emitters_are_live.py+++ b/core/tests/switch_core/telemetry/test_emitters_are_live.py@@ -37,9 +37,7 @@ def _telemetry() -> TelemetryService:sink=NullSink(),enabled=True,client_id="deployment-uuid",- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,)diff --git a/core/tests/switch_core/telemetry/test_environment_reaches_the_relay.py b/core/tests/switch_core/telemetry/test_environment_reaches_the_relay.pyindex c1761266a..80f1cebb6 100644--- a/core/tests/switch_core/telemetry/test_environment_reaches_the_relay.py+++ b/core/tests/switch_core/telemetry/test_environment_reaches_the_relay.py@@ -1,9 +1,15 @@-"""A deployment's TELEMETRY_ENVIRONMENT reaches the relay as `flint_env`.+"""What a deployment's configuration puts on the relay's resource, and what it+must not.-The relay files each event under the Amplitude project that attribute names. A-server that read the setting and then sent something else would land its-usage in the wrong project with nothing anywhere reporting a fault, so this+The relay files each event under the Amplitude project `flint_env` names. A+server that read TELEMETRY_ENVIRONMENT and then sent something else would land+its usage in the wrong project with nothing anywhere reporting a fault, so thisfollows the value from configuration to the request body.++The other direction matters as much. ENVIRONMENT and SERVICE_NAME are free text+an operator sets for their own log pipeline, and may name their company; the+same request body is checked for them, whole, rather than attribute by+attribute, so a new attribute that forwards one is caught too."""from __future__ import annotations@@ -22,7 +28,7 @@ from switch_core.db.models import DeploymentIdentityfrom switch_core.telemetry import setup as telemetry_setup-def _config(environment: str) -> SwitchConfig:+def _config(telemetry_environment: str, **overrides: Any) -> SwitchConfig:return SwitchConfig( # type: ignore[call-arg]db_host="h",db_port="5432",@@ -37,25 +43,27 @@ def _config(environment: str) -> SwitchConfig:secret_keys="test:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",telemetry_enabled=True,telemetry_endpoint="https://relay.example",- telemetry_environment=environment,+ telemetry_environment=telemetry_environment,telemetry_internal=False,+ **overrides,)[email protected]("environment", ["prod", "staging", "dev", "local"])-async def test_the_configured_environment_is_sent_as_flint_env(- environment: str,+async def _send_one(+ config: SwitchConfig,session_factory: async_sessionmaker[AsyncSession],monkeypatch: pytest.MonkeyPatch,-) -> None:+) -> tuple[str, dict[str, Any]]:+ """Emit one event through the service `main` would build, and return the+ raw request body with its resource attributes."""async with session_factory() as session:await session.execute(delete(DeploymentIdentity))session.add(DeploymentIdentity(id=1, client_id=str(uuid.uuid4())))await session.commit()- bodies: list[dict[str, Any]] = []+ bodies: list[str] = []def _handle(request: httpx.Request) -> httpx.Response:- bodies.append(json.loads(request.content))+ bodies.append(request.content.decode())return httpx.Response(200)transport = httpx.MockTransport(_handle)@@ -67,16 +75,45 @@ async def test_the_configured_environment_is_sent_as_flint_env()service, _, http = await telemetry_setup.build_telemetry(- _config(environment), session_factory, "1.0.0"+ config, session_factory, "1.0.0")service.emit("deployment_started", tenant_count=1)await service.aclose()assert http is not Noneawait http.aclose()- [body] = bodies+ [raw] = bodies+ body = json.loads(raw)resource = {a["key"]: a["value"] for a in body["resourceLogs"][0]["resource"]["attributes"]}+ return raw, resource++[email protected]("environment", ["prod", "staging", "dev", "local"])+async def test_the_configured_environment_is_sent_as_flint_env(+ environment: str,+ session_factory: async_sessionmaker[AsyncSession],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ _, resource = await _send_one(_config(environment), session_factory, monkeypatch)+assert resource["flint_env"] == {"stringValue": environment}assert resource["flint_internal"] == {"stringValue": "false"}+++async def test_operator_chosen_names_never_reach_the_relay(+ session_factory: async_sessionmaker[AsyncSession],+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ config = _config(+ "prod", environment="acme-corp-prod", service_name="acme-corp-switch"+ )+ assert config.environment == "acme-corp-prod"+ assert config.service_name == "acme-corp-switch"++ raw, resource = await _send_one(config, session_factory, monkeypatch)++ assert "acme" not in raw+ assert resource["service.name"] == {"stringValue": "switch-core"}+ assert "deployment.environment" not in resourcediff --git a/core/tests/switch_core/telemetry/test_events_doc_coverage.py b/core/tests/switch_core/telemetry/test_events_doc_coverage.pynew file mode 100644index 000000000..64b0abc18--- /dev/null+++ b/core/tests/switch_core/telemetry/test_events_doc_coverage.py@@ -0,0 +1,65 @@+"""Everything the catalogue can send is named in `docs/old/telemetry-events.md`.++The doc is what a reader outside the code — InfoSec, an operator deciding+whether to switch telemetry on — takes as the list of what leaves a deployment.+An event, property or value added to the catalogue and not to the doc is sent+without anyone having been told, which is the gap this closes.++Presence anywhere in the doc, backticked, rather than under the right heading:+the doc describes events in tables, prose and shared value sets, and a check+that knew its layout would fail on every rewrite of it.++Only what follows the platform registry is left out: the platform names+`bridge_platform` accepts and the `connector_<platform>_count` snapshot keys,+so adding a platform stays a change to that platform alone; the doc covers them+generically. `bridge_platform`'s fixed values are checked like any other.+"""++from __future__ import annotations++from pathlib import Path++from switch_core.telemetry.catalogue import (+ CATALOGUE,+ PropertyType,+ _Boolean,+ _Number,+ _OneOf,+ _RegisteredPlatform,+)++DOC = Path(__file__).parents[4] / "docs" / "old" / "telemetry-events.md"+++def _closed_values(spec: PropertyType) -> frozenset[str]:+ """The values a property spells out in the catalogue, if any."""+ if isinstance(spec, _OneOf):+ return spec.values+ if isinstance(spec, _RegisteredPlatform):+ return spec.extra+ if isinstance(spec, _Number | _Boolean):+ return frozenset()+ raise AssertionError(+ f"Unknown property kind {type(spec).__name__}: teach this test which of "+ "its values the doc must name."+ )+++def _undocumented() -> list[str]:+ doc = DOC.read_text()+ missing: set[str] = set()+ for event, spec in CATALOGUE.items():+ names = {event, *spec}+ for prop in spec.values():+ names |= _closed_values(prop)+ missing |= {name for name in names if f"`{name}`" not in doc}+ return sorted(missing)+++def test_every_event_property_and_value_is_documented() -> None:+ missing = _undocumented()+ assert not missing, (+ f"{missing} can be sent to the relay but are not named in "+ f"{DOC.relative_to(DOC.parents[2])}. Document them there — the doc is "+ "the list readers are told is complete."+ )diff --git a/core/tests/switch_core/telemetry/test_first_room_active.py b/core/tests/switch_core/telemetry/test_first_room_active.pyindex 9b5690512..733ea8964 100644--- a/core/tests/switch_core/telemetry/test_first_room_active.py+++ b/core/tests/switch_core/telemetry/test_first_room_active.py@@ -64,9 +64,7 @@ def _reporter(sink=sink, # type: ignore[arg-type]enabled=enabled,client_id="deployment-uuid",- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,session_factory=session_factory,diff --git a/core/tests/switch_core/telemetry/test_merge_fixes.py b/core/tests/switch_core/telemetry/test_merge_fixes.pyindex 7264f77af..1f0784b69 100644--- a/core/tests/switch_core/telemetry/test_merge_fixes.py+++ b/core/tests/switch_core/telemetry/test_merge_fixes.py@@ -138,9 +138,7 @@ class TestASessionIsTheAgentNotTheConnection:sink=sink, # type: ignore[arg-type]enabled=True,client_id=VALID_UUID,- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,)diff --git a/core/tests/switch_core/telemetry/test_message_events.py b/core/tests/switch_core/telemetry/test_message_events.pyindex d188da64b..c2ab06a15 100644--- a/core/tests/switch_core/telemetry/test_message_events.py+++ b/core/tests/switch_core/telemetry/test_message_events.py@@ -50,9 +50,7 @@ def _service(sink: _RecordingSink, *, enabled: bool = True) -> TelemetryService:sink=sink,enabled=enabled,client_id="deployment-uuid",- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,)diff --git a/core/tests/switch_core/telemetry/test_preconfigured_connectors.py b/core/tests/switch_core/telemetry/test_preconfigured_connectors.pyindex 57ba674af..bc5f28e05 100644--- a/core/tests/switch_core/telemetry/test_preconfigured_connectors.py+++ b/core/tests/switch_core/telemetry/test_preconfigured_connectors.py@@ -266,9 +266,7 @@ class TestRegisteringRecordsTheFlag:sink=sink, # type: ignore[arg-type]enabled=True,client_id="deployment-uuid",- service_name="switch-core",version=None,- environment=None,telemetry_environment="prod",telemetry_internal=False,)diff --git a/core/tests/switch_core/telemetry/test_relay_attribute_cap.py b/core/tests/switch_core/telemetry/test_relay_attribute_cap.pyindex 7231f4d9e..bdb6b23b5 100644--- a/core/tests/switch_core/telemetry/test_relay_attribute_cap.py+++ b/core/tests/switch_core/telemetry/test_relay_attribute_cap.py@@ -78,9 +78,7 @@ async def _attributes_on_the_wire(sink=capture, # type: ignore[arg-type]enabled=True,client_id="11111111-1111-1111-1111-111111111111",- service_name="switch-core",version="1.0.0",- environment=None,telemetry_environment="prod",telemetry_internal=False,)diff --git a/core/tests/switch_core/telemetry/test_service_and_sink.py b/core/tests/switch_core/telemetry/test_service_and_sink.pyindex e98c91f14..2f28b277c 100644--- a/core/tests/switch_core/telemetry/test_service_and_sink.py+++ b/core/tests/switch_core/telemetry/test_service_and_sink.py@@ -49,9 +49,7 @@ def _service(sink: object, *, enabled: bool = True) -> TelemetryService:sink=sink, # type: ignore[arg-type]enabled=enabled,client_id="deployment-uuid",- service_name="switch-core",version="1.2.3",- environment="pilot",telemetry_environment="prod",telemetry_internal=False,)@@ -96,12 +94,10 @@ class TestTagging:await service.aclose()assert sink.sent[0].resource == {- "service.name": "switch-core","flint.client_id": "deployment-uuid","flint_env": "prod","flint_internal": "false","service.version": "1.2.3",- "deployment.environment": "pilot",}@pytest.mark.parametrize("environment", ["prod", "staging", "dev", "local"])@@ -115,9 +111,7 @@ class TestTagging:sink=sink, # type: ignore[arg-type]enabled=True,client_id="deployment-uuid",- service_name="switch-core",version="1.2.3",- environment=None,telemetry_environment=environment,telemetry_internal=False,)@@ -137,9 +131,7 @@ class TestTagging:sink=sink, # type: ignore[arg-type]enabled=True,client_id="deployment-uuid",- service_name="switch-core",version="1.2.3",- environment=None,telemetry_environment="prod",telemetry_internal=internal,)@@ -149,17 +141,15 @@ class TestTagging:assert sink.sent[0].resource["flint_internal"] == sent- 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."""+ async def test_an_unknown_version_is_omitted_rather_than_empty(self) -> None:+ """An absent attribute reads as "not known"; an empty string reads as a+ real version 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,telemetry_environment="prod",telemetry_internal=False,)@@ -167,7 +157,6 @@ class TestTagging:service.emit("deployment_started", tenant_count=1)await service.aclose()- assert "deployment.environment" not in sink.sent[0].resourceassert "service.version" not in sink.sent[0].resource@@ -221,7 +210,6 @@ class TestTheWireFormat:name="switch_core.usage_snapshot",properties={"room_count": 7, "from_template": True, "kind": "user"},resource={- "service.name": "switch-core","flint.client_id": "deployment-uuid","flint_env": "dev","flint_internal": "false",@@ -278,7 +266,6 @@ class TestTheWireFormat:"failed_attempts_before_success": 0,},resource={- "service.name": "switch-core","flint.client_id": "deployment-uuid","flint_env": "prod","flint_internal": "false",@@ -313,6 +300,47 @@ class TestTheWireFormat:assert resource["flint_env"] == {"stringValue": "dev"}assert resource["flint_internal"] == {"stringValue": "false"}+ async def test_the_sink_sends_no_service_or_environment_name_a_record_carries(+ self,+ ) -> None:+ """The sink decides what names the service, so a caller that tagged a+ record with operator-set text still cannot send it."""+ bodies: list[str] = []++ def _handle(request: httpx.Request) -> httpx.Response:+ bodies.append(request.content.decode())+ return httpx.Response(200)++ http = httpx.AsyncClient(transport=httpx.MockTransport(_handle))+ sink = _relay_sink(http)+ sink.send(+ TelemetryRecord(+ name="switch_core.deployment_started",+ properties={"tenant_count": 1},+ resource={+ "service.name": "acme-corp-switch",+ "deployment.environment": "acme-corp-prod",+ "flint.client_id": "deployment-uuid",+ "flint_env": "prod",+ "flint_internal": "false",+ },+ timestamp_ns=1,+ )+ )+ await sink.aclose()+ await http.aclose()++ [raw] = bodies+ body = json.loads(raw)+ resource = {+ a["key"]: a["value"]+ for a in body["resourceLogs"][0]["resource"]["attributes"]+ }+ assert "acme" not in raw+ assert resource["service.name"] == {"stringValue": "switch-core"}+ assert "deployment.environment" not in resource+ assert body["resourceLogs"][0]["scopeLogs"][0]["scope"]["name"] == "switch-core"+async def test_it_posts_to_the_logs_signal(self) -> None:"""Not `/v1/metrics`: the relay routes on log records, and a metricwould be dropped without complaint."""@@ -433,7 +461,6 @@ def _a_record() -> TelemetryRecord:name="switch_core.deployment_started",properties={"tenant_count": 1},resource={- "service.name": "switch-core","flint.client_id": "deployment-uuid","flint_env": "dev","flint_internal": "false",diff --git a/deploy/remote/helm/switch/values.yaml b/deploy/remote/helm/switch/values.yamlindex 34fc7d160..2cc0c00dd 100644--- a/deploy/remote/helm/switch/values.yaml+++ b/deploy/remote/helm/switch/values.yaml@@ -264,9 +264,10 @@ switchCore:# 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.+ # active users, how much traffic), durations (how long from install to a+ # working connector) and values from closed sets (which platform, which agent+ # runtime, success or failure). 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 samediff --git a/docs/TELEMETRY.md b/docs/TELEMETRY.mdindex fabbeacbc..d47ad1a5b 100644--- a/docs/TELEMETRY.md+++ b/docs/TELEMETRY.md@@ -3,8 +3,8 @@**Audience:** InfoSec.**Scope:** the Switch Console desktop app, and the consent decision it carriesto a Switch server it runs for the user (§4.1). What that server itself-collects is documented separately; Switch server-side logging is out of scope-here and needs its own pass.+collects is documented in [`old/telemetry-events.md`](old/telemetry-events.md);+Switch server-side logging is out of scope here and needs its own pass.**Claim:** the data we transmit is anonymous. No field identifies a person, andno combination of the fields we transmit can be resolved back to one.@@ -241,7 +241,7 @@ every time the Console starts it, in both directions. "No" is written downexplicitly rather than left out, because a stack started under a "yes" wouldotherwise keep the setting it started with.-Two limits are stated in the app rather than left to be discovered.+Three limits are stated in the app rather than left to be discovered.- **The server reads the setting when it starts.** Changing the answer while itis running does not reach it until it restarts, and the Console does not@@ -254,6 +254,36 @@ Two limits are stated in the app rather than left to be discovered.- **A server reached by URL is not covered.** It is somebody else's deploymentwith its own answer, and the toggle neither reaches it nor claims to.+The third is stated in the same note as the second, in a sentence; the detail+is here. **On a server other people's Consoles also use, a "yes" does not turn+sharing on over them, but a "yes" can keep it on.** This concerns a server on+an SSH host, which several people can run from their own Consoles; the server+on the user's own machine has no other users, and the answer is applied there+as given.++- **A "no" applies to everyone on the server**, but only when the Console that+ holds it starts the server. Until then the server keeps the setting it+ started with, and that person's server page says it is still sharing and+ offers the restart.+- **A "yes" applies only if the server's saved configuration already asks to+ share, or no other Console has been seen on it in the last 14 days.** Each+ Console records itself in a list kept on the host when it starts, stops,+ connects to or resets the server, and once a day while it is open on a+ running one. The list holds nobody's answer, so holding a "yes" back is a+ precaution, not a check that someone said no.+- **So an earlier "yes" can outlast a later "no".** If sharing was turned on+ while one Console was alone, later starts under a "yes" keep it on with+ others present. A co-user's "no" stops it only when their own Console+ restarts the server.+- **Failing to read the list holds a "yes" back** for that start. A host with+ no list yet counts as nobody else, entries that cannot be parsed are+ skipped, and a Console too old to write to the list is not counted.++When a "yes" is held back, the Console does not say so at the time: the note+states the rule, and the log records each case. The server's page does not+report the server as out of step, because a restart from that Console would+hold it back again.+---## 5. The identifierdiff --git a/docs/old/telemetry-events.md b/docs/old/telemetry-events.mdindex ed5b8c12b..65dadbdc0 100644--- a/docs/old/telemetry-events.md+++ b/docs/old/telemetry-events.md@@ -163,8 +163,10 @@ Specifically never sent, in addition to any identifier:- error messages and stack traces — an enumerated reason code insteadFree 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.+or a value from a closed set fixed in code. Almost every set is written out in+the catalogue; `bridge_platform` is the platforms this build registers, which+are code too. A property carrying an unexpected value is a bug to be raised,+not a string to be passed through.## Deployment identity and the install clock@@ -214,16 +216,19 @@ On every event:| Attribute | Value ||---|---|-| `service.name` | `switch-core` |-| `service.version` | the running version, as `/version` reports it |+| `service.name` | `switch-core`, always |+| `service.version` | the running version, as `/version` reports it; omitted when unknown || `flint.client_id` | the per-deployment id |-| `deployment.environment` | from the existing `ENVIRONMENT` setting |+| `flint_env` | `prod` \| `staging` \| `dev` \| `local`, from `TELEMETRY_ENVIRONMENT` |+| `flint_internal` | `true` \| `false`, from `TELEMETRY_INTERNAL` |-`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.+The rule against free text holds here too. `service.name` is a constant rather+than the `SERVICE_NAME` setting, and the `ENVIRONMENT` setting is not sent as+`deployment.environment`: both are free text an operator sets for their own log+pipeline, and either could name their company. The operational OTLP export+(`OTLP_ENDPOINT`) still carries both, because it goes to the operator's own+collector. A test sets both to a company name and checks the whole request body+the relay receives for it.## Four kinds of event@@ -547,9 +552,9 @@ a slow average.(tri-state: `true` | `false` | `unknown` — `unknown` when the activity countitself could not be run, which is not evidence the room was never used).-**`room_agents_added`** — `agent_count` (number), `added_by_kind`.+**`room_agents_added`** — `agent_count` (number), `added_by_kind` (`user` | `agent` | `system`).-**`room_agents_removed`** — `agent_count` (number), `removed_by_kind`.+**`room_agents_removed`** — `agent_count` (number), `removed_by_kind` (as above).### Removals@@ -584,7 +589,7 @@ that as `false` would misfile a lookup failure as a failed setup.| Property | Type ||---|---|-| `agent_type` | `always_on` \| `session_addressable` \| `session_passive` |+| `agent_type` | `always_on` \| `session_addressable` \| `session_passive` \| `auto_session` || `known_agent_type` | `claude-code` \| `codex` \| `opencode` \| `other` \| `none` || `registration_path` | `bootstrap` \| `personal_key` \| `gateway` \| `other` || `has_parent` | boolean — a subagent rather than a top-level agent |@@ -624,8 +629,9 @@ The connection registry already records a reason on every close, which is wherethese values come from; the set is closed here so a new reason string added inthe code does not silently become a new Amplitude value.-**`bridge_connected`** — `bridge_platform`, `outcome`, `failure_reason`,-`duration_ms`.+**`bridge_connected`** — `bridge` (`collaboration` \| `agent`), `bridge_platform`,+`outcome`, `failure_reason`, `duration_ms`. `bridge` is always `collaboration`+today; `agent` is declared so the agent bridge can report the same events.Fires for every attempt, including the ones that fail before the bridge's taskis ever scheduled — an unregistered adapter type, a stored config that no@@ -641,9 +647,9 @@ failure half is the more interesting one, because a timeout and a refusal carrythe same `failure_reason` and nothing alike in the time. `-1` if no reading wastaken, following the convention below.-**`bridge_disconnected`** — `bridge_platform`, `reason`+**`bridge_disconnected`** — `bridge` (as above), `bridge_platform`, `reason`(`shutdown` \| `restart` \| `auth_failed` \| `network` \| `platform_error` \|-`unknown`).+`config_invalid` \| `unknown`).Bridge drops are worth having as events rather than only as a snapshot count:the snapshot says two bridges are down right now, the events say one platform@@ -730,17 +736,66 @@ separates an agent answering people from agents talking among themselves.| `has_attachment` | boolean || `in_thread` | boolean |+### Resources, keys, groups and the rest++What each one is for, and how to make it fire, is under+[Every event, and how to make it fire](#every-event-and-how-to-make-it-fire).+This is what each carries.++| Event | Properties |+|---|---|+| `reference_created` | `reference_type`; `read_visibility` (`private` \| `public`); `created_by_kind` (`user` \| `agent` \| `system`) |+| `reference_attached_to_room` | `reference_type` |+| `reference_detached_from_room` | `reference_type` |+| `reference_deleted` | `reference_type`; `age_days` (number) |+| `document_created` | `scope` (`library` \| `room`); `created_by_kind` (`user` \| `agent` \| `system`); `has_instructions` (boolean) |+| `document_attached_to_room` | none |+| `document_detached_from_room` | none |+| `document_deleted` | `scope` (`library` \| `room`); `age_days` (number) |+| `package_created` | `created_by_kind` (`user` \| `agent` \| `system`) |+| `package_attached_to_room` | `reference_count` (number); `document_count` (number) |+| `package_detached_from_room` | none |+| `package_deleted` | `age_days` (number) |+| `reference_type_created` | none |+| `reference_type_deleted` | `age_days` (number) |+| `api_key_created` | `key_type` (`agent` \| `registration` \| `bootstrap` \| `other`) |+| `api_key_revoked` | `key_type` (`agent` \| `registration` \| `bootstrap` \| `other`); `age_days` (number) |+| `room_group_created` | `has_parent` (boolean) |+| `room_group_deleted` | `room_count` (number); `age_days` (number) |+| `template_created` | `template_kind` (`room` \| `group` \| `agent` \| `other`) |+| `template_deleted` | `template_kind` (`room` \| `group` \| `agent` \| `other`); `age_days` (number) |+| `agent_request_refused` | `operation` (`list_templates` \| `get_template` \| `run_template` \| `save_template` \| `update_template` \| `delete_template` \| `create_room` \| `create_room_from_yaml`); `reason` (`not_found` \| `not_yours` \| `name_taken` \| `visibility_not_allowed` \| `invalid` \| `too_large` \| `missing_agents` \| `agent_creation_console_only` \| `busy` \| `run_paused` \| `run_stopped` \| `repeat` \| `kickoff_ignored`) |+| `room_link_created` | none |+| `room_link_removed` | none |+| `room_role_defined` | `exclusive` (boolean) |+| `room_role_deleted` | none |+| `room_users_added` | `user_count` (number) |+| `server_connector_registered` | `connector_kind` (`opencode` \| `other`) |+| `server_connector_removed` | `connector_kind` (`opencode` \| `other`) |+| `connector_configured` | `bridge_platform`; `is_preconfigured` (boolean) |+| `invitation_sent` | `delivery` (`sent` \| `not_configured` \| `failed` \| `not_requested`) |+| `invitation_accepted` | `age_hours` (number) |+### Closed value sets-`bridge_platform`: `slack` | `mattermost` | `discord` | `teams` | `telegram` |-`none` | `unknown`. `none` is "no bridge" (an internal-only room); `unknown` is-"there is one and the lookup that would have named it failed" — the two are-kept apart because collapsing them would misreport a Slack-bridged room as-internal-only whenever that lookup has a transient error.+`bridge_platform`: a platform this build registers — today `slack` |+`mattermost` | `discord` | `teams` | `telegram` — or `none` | `unknown`. The+set is read from the platform registry when an event is checked, so a new+platform adds its own value; a platform key is code, a short lowercase name,+never anything an operator typed. `none` is "no bridge" (an internal-only+room); `unknown` is "there is one and it could not be named", because the+lookup failed or its platform is no longer registered. The two are kept apart+because collapsing them would misreport a Slack-bridged room as internal-only+whenever that lookup has a transient error.`channel_type`: `channel_public` | `channel_private` | `direct` | `none` |-`unknown`, with `unknown` meaning what it does for `bridge_platform`. Only the-message events can carry it.+`unknown`, with `unknown` meaning what it does for `bridge_platform`. Every+event with a `channel_type` accepts `unknown`, but only the message events send+it today; the room events read the type from a row they already hold.++`reference_type`: `google_drive` | `confluence` | `github` | `jira` | `other`. The+four built-in types; a user-defined type's slug is free text, so it reports as+`other`.`sender_kind`: `user` | `agent` | `platform` | `unknown`. `platform` is Switchitself speaking; `unknown` a sender whose client could not be looked up.@@ -748,10 +803,13 @@ itself speaking; `unknown` a sender whose client could not be looked up.`outcome`: `success` | `failure`. `failure_reason` is an enumerated code perevent, `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.+`bridge_connected.failure_reason` is `none` | `auth_failed` | `network` |+`platform_error` | `config_invalid` | `unknown`. `bridge_disconnected.reason`+takes the same failure codes without `none`, plus `shutdown` and `restart`. The+failure codes are shared because one classifier feeds both: a value that+classifier can produce and only one of the two declares is an event that fails+validation at the moment a bridge drops — which is precisely the event worth+not losing.**Tri-state facts**: `true` | `false` | `unknown`, for a yes/no property theserver can fail to establish (`room_archived`/`room_deleted`.`was_ever_active`,