Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/docs/reference/telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,10 @@ We collect the following categories of events:
| `rules_learning_changed` | The person turned learning from sessions on or off for a project, or back to the workspace's setting, with the resulting state and who decides it (`organization`, `you`, `workspace` or `default`). |
| `rules_command` | `/rules` opened in a client (`view`), or a `learn` subcommand run (its name only, never its arguments). |
| `lineage_report` | What a person did with the Claude Code plugin's lineage report, sent by the plugin through `altimate-code tool report-event`: the end-of-task summary was shown, **Open report** was pressed, `/lineage-report` was run, or the report was built, failed to build or found no browser to open in. Its payload is the action and the Claude Code session id, beside the fields every event carries (below): no model, column, file or project names. The report page itself makes no network requests. |
| `plugin_session_start` | A Claude Code session started with the Altimate Code plugin, sent by the plugin through `altimate-code tool report-event`. Its payload is the plugin version, this altimate-code's version (`altimate_code_version`), the OS as Claude Code names it (`host_os`: `macos`, `linux`, `windows`, `wsl` or `unknown`; named apart from the `os` other events carry as `process.platform`) and the plugin's anonymous install id (a random UUID the plugin makes on first run and keeps in its Claude Code plugin store). It carries no session id, machine id, project id or account (`user_id`, `tenant`), nor the per-launch `launch_id`, so it cannot be joined to the CLI's other events: beside its own fields, only `cli_version`, `client` and `source`, keyed to the install id (`ai.user.id`). It is sent in a request of its own, never in one batch with the CLI's other events. |
| `plugin_feature_used` | One of the plugin's panels or commands was opened (`lineage`, `dbt_show`, `profile_ctes`, `scan_cost`, `comments`, `sql_graph`, `health`, `runs`, `to_model`), or one of its gates held or allowed a command (`cost_gate`, `health_push_gate`). Its payload is the feature, the outcome (`opened`; `failed` when the panel could not open; `held` or `allowed` for a gate), the plugin version and the install id: no model, column, file or project names, SQL or session text. Like `plugin_session_start`, it carries no session id, machine id, project id, launch id or account: beside its own fields, only `cli_version`, `client` and `source`, keyed to the install id. |

Each event includes a timestamp, session ID, a per-launch correlation ID (`launch_id` — a random value regenerated every process start, not persisted and not derived from your machine or identity; it exists only to group events from the same run), CLI version, and a machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and not derived from your hardware or identity). When the machine is signed in to Altimate, each event also carries `user_id` and `tenant`, described under [User Identification](#new-user-identification).
Each event (except the plugin's `plugin_session_start` and `plugin_feature_used`, described above) includes a timestamp, session ID, a per-launch correlation ID (`launch_id` — a random value regenerated every process start, not persisted and not derived from your machine or identity; it exists only to group events from the same run), CLI version, and a machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and not derived from your hardware or identity). The final `telemetry_opted_out`, in the same table, is the other exception: it carries the timestamp, CLI version and machine ID, but no session ID, `launch_id` or account. When the machine is signed in to Altimate, each event also carries `user_id` and `tenant`, described under [User Identification](#new-user-identification).

### Workspace events

Expand Down Expand Up @@ -228,6 +230,8 @@ What identifies the sender of an event depends on whether the machine is signed
- **Not signed in:** A random UUID is generated using `crypto.randomUUID()` on first run and stored at `~/.altimate/machine-id`. This ID is not tied to your hardware, operating system, or identity — it is purely random and serves only to distinguish one machine from another in aggregate analytics. It is also the Application Insights user ID (`ai.user.id`).
- **Signed in to Altimate:** Events also carry `user_id`, your Altimate user ID (a UUID), and `tenant`, the name of your Altimate instance; `ai.user.id` is your user ID instead of the machine ID. These identify your account, so signed-in events are not anonymous. To find them, Altimate Code makes one `GET /users/me` request to the Altimate API with the credential you signed in with, and caches the answer at `~/.altimate/telemetry-identity.json` (readable only by you). The cache holds the user ID, the tenant and a fingerprint of the credential — no API key or token. A new credential is looked up again; a sign-out, or a credential the API rejects, removes the cache. No email address, hashed or not, is sent.

The Claude Code plugin's `plugin_session_start` and `plugin_feature_used` are the exception: signed in or not, they carry neither the machine ID nor your account, and their `ai.user.id` is the plugin's own random install id.

These identifiers are sent only while telemetry is enabled. The final `telemetry_opted_out` event carries the machine ID and nothing that identifies your account, and no `/users/me` lookup is made while telemetry is disabled. Disable telemetry entirely with `ALTIMATE_TELEMETRY_DISABLED=true` or the config option above.

### CLI Authentication Flow
Expand Down
2 changes: 2 additions & 0 deletions docs/docs/usage/tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,3 +84,5 @@ For clients that cannot use the `altimate-code` MCP server, the Claude Code plug
## Plugin events

`altimate-code tool report-event <action> --session claude:<id>` is called by the Claude Code plugin to record what a person did with its lineage report. `<action>` is one of `summary_shown`, `open_pressed`, `command_run`, `built`, `build_failed` or `no_browser`. It sends one `lineage_report` usage event (see [Telemetry](../reference/telemetry.md)) and nothing when telemetry is off. It is not meant to be run by hand.

The plugin also calls `altimate-code tool report-event plugin_session_start --plugin-version <v> --install-id <uuid> --os <os>` at each session start, and `altimate-code tool report-event plugin_feature_used --plugin-version <v> --install-id <uuid> --feature <name> --outcome <outcome>` when a panel or command opens (or its panel fails to open) or a gate holds or allows a command. They take no `--session`. Each value is checked against a fixed list or pattern, and any other flag is refused, so the events carry only those fields (see [Telemetry](../reference/telemetry.md)).
96 changes: 78 additions & 18 deletions packages/opencode/src/altimate/telemetry/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import { Log } from "@/altimate/util/log"
import { TraceContext } from "@/altimate/observability/trace-context"
// altimate_change — shared machine-id helper (race-safe, UUID-validated, size-capped)
import { getOrCreateMachineId } from "@/altimate/util/machine-id"
// altimate_change — the Claude Code plugin's actions, whose events are sent anonymous (see ANONYMOUS_EVENTS)
import { PLUGIN_ACTIONS } from "@/altimate/tool-cli/report-event"
import { TelemetryIdentity } from "./identity"
import { OptOutMarker } from "./opt-out"
import { TelemetryConfig } from "./config-state"
Expand Down Expand Up @@ -928,6 +930,39 @@ export namespace Telemetry {
action: "summary_shown" | "open_pressed" | "command_run" | "built" | "build_failed" | "no_browser"
}
// altimate_change end
// altimate_change start — the Claude Code plugin's own usage, sent through `tool report-event`
| {
/** A Claude Code session started with the plugin. Versions, OS and the plugin's random install id only: no session id. */
type: "plugin_session_start"
timestamp: number
plugin_version: string
altimate_code_version: string

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION: altimate_code_version duplicates cli_version on the same row

toAppInsightsEnvelopes already adds cli_version: InstallationVersion to every event's properties (packages/opencode/src/altimate/telemetry/index.ts:2448), and this field is stamped from the same InstallationVersion (the integration test asserts altimate_code_version === cli_version). Two property names for one value give dashboards two sources that can drift, and the row grows for no gain. Consider dropping the event field and reading cli_version instead.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Declining. altimate_code_version is part of this event's contract: the session start names the altimate-code version beside the plugin version, as the docs and the plugin's privacy notice list it. cli_version is the envelope's, added to every row by toAppInsightsEnvelopes (telemetry/index.ts, properties.cli_version). Keeping the event's own field keeps the plugin-version-by-CLI-version query on the event's documented fields. It is one short string per session start. The e2e test pins that the two are equal (report-event.test.ts, altimate_code_version toBe cli_version).

/** Claude Code's name for the OS; not `os`, which other events carry as `process.platform`. */
host_os: "macos" | "linux" | "windows" | "wsl" | "unknown"
/** A random UUID the plugin made on first run and keeps in its Claude Code plugin store. */
install_id: string
}
| {
/** A plugin panel or command was opened, or one of its gates held or allowed a command. */
type: "plugin_feature_used"
timestamp: number
plugin_version: string
install_id: string
feature:
| "lineage"
| "dbt_show"
| "profile_ctes"
| "scan_cost"
| "comments"
| "sql_graph"
| "health"
| "runs"
| "to_model"
| "cost_gate"
| "health_push_gate"
outcome: "opened" | "failed" | "held" | "allowed"
}
// altimate_change end
| {
// Sent before connecting, so an attempt that hangs or ends the process is still counted.
type: "warehouse_connect_started"
Expand Down Expand Up @@ -2383,6 +2418,12 @@ export namespace Telemetry {
// altimate_change — `ids` lets a caller build envelopes for a machine and identity other than
// the module's current state (the opt-out marker runs while telemetry is disabled and must not
// touch the state an enabled init may be using concurrently).
// altimate_change start — the Claude Code plugin's usage events are anonymous and unlinkable: they carry
// none of the identifiers the CLI's other events share (account, machine id, project, session, launch id),
// so they cannot be joined to a signed-in row. They are keyed to the plugin's own random install id only.
const ANONYMOUS_EVENTS: ReadonlySet<string> = new Set(PLUGIN_ACTIONS)
// altimate_change end

function toAppInsightsEnvelopes(
events: Event[],
cfg: AppInsightsConfig,
Expand All @@ -2400,25 +2441,31 @@ export namespace Telemetry {
const clientSource = Flag.ALTIMATE_CLI_CLIENT
return events.map((event) => {
const { type, timestamp, ...fields } = event as any
const sid: string = fields.session_id ?? sessionId
// altimate_change start — the plugin's anonymous events: no account, machine id, project, session or launch id.
const anonymous = ANONYMOUS_EVENTS.has(type)
const account = anonymous ? undefined : who
const sid: string = anonymous ? "" : (fields.session_id ?? sessionId)
// altimate_change end

const properties: Record<string, string> = {
cli_version: InstallationVersion,
// altimate_change — the emitting client, per the shared event contract; `source` below
// still says how this CLI was launched (cli, tui, serve, datamates).
client: "altimate-code",
source: clientSource,
project_id: fields.project_id ?? projectId,
...(mid && { machine_id: mid }),
...(!anonymous && { project_id: fields.project_id ?? projectId }),
...(mid && !anonymous && { machine_id: mid }),
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved
// altimate_change — the backend user uuid and tenant when signed in to Altimate, so a CLI
// row joins the PostHog person and the backend record for the same account.
...(who && { user_id: who.user_id, tenant: who.tenant }),
...(account && { user_id: account.user_id, tenant: account.tenant }),
// altimate_change — groups every event from one process launch. The onboarding funnel
// spans the TUI main thread and the server worker, and most of it runs before any chat
// session exists, so `session_id` is empty for the first half and real for the second —
// leaving no key to join a single run on. This is not persisted, not derived from the
// machine or the user, and not reused across launches; it only says "same run".
launch_id: launchId(),
// altimate_change — not on the plugin's anonymous events: shared with the same process's other rows
// (a first_launch carries the machine id), it would join them.
...(!anonymous && { launch_id: launchId() }),
}
const measurements: Record<string, number> = {}

Expand All @@ -2438,15 +2485,15 @@ export namespace Telemetry {
time: new Date(timestamp).toISOString(),
iKey: cfg.iKey,
tags: {
"ai.session.id": sid || "startup",
"ai.session.id": sid || (anonymous ? "" : "startup"),
// altimate_change start — the backend user uuid when signed in, else the machine id.
// Anonymous machines each keep a distinct identity (the random machine UUID, already a
// custom property) instead of sharing ai.user.id="". No email, hashed or not, is sent.
"ai.user.id": who?.user_id || mid || "",
"ai.user.id": anonymous ? String(fields.install_id ?? "") : account?.user_id || mid || "",
// altimate_change end
"ai.cloud.role": "altimate",
"ai.application.ver": InstallationVersion,
...(fields._operation_id && { "ai.operation.id": fields._operation_id }),
...(fields._operation_id && !anonymous && { "ai.operation.id": fields._operation_id }),
},
data: {
baseType: "EventData",
Expand Down Expand Up @@ -3009,25 +3056,38 @@ export namespace Telemetry {
const controller = new AbortController()
activeFlushAbort = controller
const timeout = setTimeout(() => controller.abort(), timeoutMs)
// altimate_change start — the plugin's anonymous events go in a request of their own, never in one
// body beside rows that carry the machine id or the account. Only an unsent batch is retried.
const batches = [events.filter((e) => !ANONYMOUS_EVENTS.has(e.type)), events.filter((e) => ANONYMOUS_EVENTS.has(e.type))].filter(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor (edge case): the two batches share one AbortController and one timeout.

Under shutdown({ timeoutMs: 600 }) I tested an ordinary request taking 450 ms and a plugin request taking 300 ms. The ordinary row arrives. The plugin request is aborted at 600 ms, and because shuttingDown is true the catch returns, so the plugin row is lost. At base both rows went in one request and would have arrived.

This does not block: a tool report-event process buffers only its plugin row. With the built CLI I saw one request per run and an exit time equal to base, so two batches at shutdown need a process that tracks both kinds. Ordinary rows are always sent first, so they can never be affected. If it matters later, give the plugin batch its own short deadline or send it first.

(batch) => batch.length > 0,
)
const sent = new Set<Event>()
const attempted = new Set<Event>()
// altimate_change end
try {
const response = await fetch(appInsights.endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(toAppInsightsEnvelopes(events, appInsights, { machineId: mid, identity: who })),
signal: controller.signal,
})
if (!response.ok) {
log.debug("telemetry flush failed", { status: response.status })
for (const batch of batches) {
for (const e of batch) attempted.add(e)
const response = await fetch(appInsights.endpoint, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(toAppInsightsEnvelopes(batch, appInsights, { machineId: mid, identity: who })),
signal: controller.signal,
})
for (const e of batch) sent.add(e)
if (!response.ok) {
log.debug("telemetry flush failed", { status: response.status })
}
}
} catch {
// altimate_change — no write-back during shutdown. The buffer is cleared a few lines later
// regardless, so re-inserting here does not save these events; it only leaves them to be
// shipped by whatever lifecycle comes next, under a different launch id.
if (shuttingDown) return
// Re-add events that haven't been retried yet to avoid data loss
const retriable = events.filter((e) => !(e as any)._retried)
const retriable = events.filter((e) => !sent.has(e) && !(e as any)._retried)
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
Resolved

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor (edge case, raised by Codex, reproduced): a plugin event that already used its retry is dropped without being attempted again.

!(e as any)._retried filters before attempted is consulted. A plugin event that failed once already has _retried = true. If the next flush's ordinary batch fails first, the plugin batch is never attempted, but it is still excluded from write-back.

Repro with mocked track posts: track a plugin_feature_used, then flush with the POST failing. Track a rules_command, then flush with the first POST failing. Then flush twice more with the network back. The requests sent are [plugin_feature_used], [rules_command], [rules_command], so the plugin row got one attempt. At base the same sequence gave it two attempts, the second inside the combined request.

This does not block: it needs two network failures in a process that buffers both kinds of row. Suggested fix: events.filter((e) => !sent.has(e) && (!attempted.has(e) || !(e as any)._retried)). All of the PR's tests still pass with it.

// altimate_change — a batch never attempted (an earlier one failed) keeps its retry.
for (const e of retriable) {
;(e as any)._retried = true
if (attempted.has(e)) (e as any)._retried = true
}
const space = Math.max(0, MAX_BUFFER_SIZE - buffer.length)
buffer.unshift(...retriable.slice(0, space))
Expand Down
Loading
Loading