Skip to content

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

Keep operator-set names out of usage telemetry (#735)

Christian McDermottc56333b91319
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 checks
could 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-in
as an invalid URL. It now accepts either of the server's own origins, over
HTTPS. 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-12
diff --git a/console/AGENTS.md b/console/AGENTS.md
index dd2b873f9..47517ca13 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -420,7 +420,11 @@ pnpm run lint
reads 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 when
the `.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 at
boot, so a running stack can be out of step; that is surfaced on the server's page with
a restart offered, never applied by restarting the user's server for them. Whether it
diff --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.ts
index 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.ts
index 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.py
index 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 same
diff --git a/core/switch_core/telemetry/__init__.py b/core/switch_core/telemetry/__init__.py
index 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.py
index 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_factory
self._installed_at = installed_at
self._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
@property
def enabled(self) -> bool:
diff --git a/core/switch_core/telemetry/setup.py b/core/switch_core/telemetry/setup.py
index 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.py
index 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 PropertyValue
logger = 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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 this
follows 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 DeploymentIdentity
from 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 None
await 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 resource
diff --git a/core/tests/switch_core/telemetry/test_events_doc_coverage.py b/core/tests/switch_core/telemetry/test_events_doc_coverage.py
new file mode 100644
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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].resource
assert "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 metric
would 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.yaml
index 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 same
diff --git a/docs/TELEMETRY.md b/docs/TELEMETRY.md
index 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 carries
to 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, and
no 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 down
explicitly rather than left out, because a stack started under a "yes" would
otherwise 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 it
is 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 deployment
with 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 identifier
diff --git a/docs/old/telemetry-events.md b/docs/old/telemetry-events.md
index 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 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.
+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 count
itself 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 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`,
-`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 task
is 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 carry
the same `failure_reason` and nothing alike in the time. `-1` if no reading was
taken, 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 Switch
itself 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 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.
+`bridge_connected.failure_reason` is `none` | `auth_failed` | `network` |
+`platform_error` | `config_invalid` | `unknown`. `bridge_disconnected.reason`
+takes the same failure codes without `none`, plus `shutdown` and `restart`. The
+failure codes are shared because one classifier feeds both: a value that
+classifier can produce and only one of the two declares is an event that fails
+validation at the moment a bridge drops — which is precisely the event worth
+not losing.
**Tri-state facts**: `true` | `false` | `unknown`, for a yes/no property the
server can fail to establish (`room_archived`/`room_deleted`.`was_ever_active`,