From c0646cb404baeba9bc8b219c2ea7f40d213edf1e Mon Sep 17 00:00:00 2001 From: "Bender (Fable)" Date: Fri, 18 Sep 2026 07:54:08 +0000 Subject: [PATCH] docs(telemetry): document connector event semantics in the telemetry README Greptile review on the adoption draft flagged the AGENTS.md same-PR README rule: promotion enables transmission, so the durable rules the generated types cannot express (connector_key catalog-slug-or-custom, committed-write emission, duration rounding/omission, best-effort delivery) now live in the telemetry README without duplicating event tables. Co-Authored-By: Claude Fable 5 (cherry picked from commit 08c6832e8089cfd8b7cb7f3849013e8d049f4ea2) --- packages/shared/src/telemetry/README.md | 29 +++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/packages/shared/src/telemetry/README.md b/packages/shared/src/telemetry/README.md index 9dd03c7b569..8d6b57351dc 100644 --- a/packages/shared/src/telemetry/README.md +++ b/packages/shared/src/telemetry/README.md @@ -108,6 +108,35 @@ data paths document their own contract in their own file: - [Run-Log Events](../../../../doc/run-log-events.md) — events written to the local `heartbeat_run_events` table. +## Connector Events + +The three `connector.*` events record tool-connector lifecycle and usage for +connections whose `connection_purpose` is `tool`. The generated contract +remains the authority for their exact dimensions and optionality. These +durable rules are not expressible in the generated `string`/`number` types: + +- `connector_key` is never a free-text connector name or URL. It carries the + connection's `sourceTemplateKey` only when that key resolves to a reviewed + first-party catalog definition; every other connection emits the literal + `custom`. `connectorKeyForConnection()` in + `server/src/services/connector-telemetry.ts` owns this rule. +- `connector.connection_created` and `connector.connection_updated` are + emitted only after the lifecycle write commits, from returned rows. Writes + that affect no rows and no-op changes do not emit. +- `connector.invocation_completed` is emitted once per invocation reaching a + terminal status. Its `origin` dimension separates setup tests (the Apps → + Test tab) from agent and user calls using the durable test-origin columns. + `duration_seconds` is `completedAt - startedAt` rounded to whole seconds and + floored at zero; it is omitted when either timestamp is unavailable. +- Delivery is best-effort and never blocks product writes. A duplicate (never + contradictory) `failed` invocation event is possible when failure-path + bookkeeping itself fails, and a crash between the product write and emission + loses that event. Do not treat these events as an exactly-once ledger. + +Use `trackConnectorConnectionCreated()`, `trackConnectorConnectionUpdated()`, +and `trackConnectorInvocationCompleted()` from `events.ts` to emit these +events. + ## Dimension Values Telemetry dimension values must be primitives. Use only the value types allowed