Skip to main content

Telemetry

$.telemetry logs analytics records. A record is sent only when Claude Code or a built-in mod makes the call. A mod you install can watch and rewrite records, but it must give its telemetry hook the filter { to: 'collector' }. Without the filter the mod fails claude plugin validate, and * does not select these events.

A hook can return { deny }. The built-in cc-plugin-telemetry sends the records. The collector is the one the operator of the session configured.

Official page: Mods Reference. Source: the program (types-2.1.304.d.ts).

Example​

on('telemetry.log', { to: 'collector' }, ($, e, next) => next(e))

Members​

ItemStatusWhat it doesHow it worksWhere it can be used
$.telemetry.logDocumentedLogs one record to the destination entry.to names. It is the event telemetry.log. anthropic is the default.(entry: TelemetryLogArgs) => Promise<void>. Sends a first-party row or a collector record. A first-party row is queued for built-ins only. Rejects if a hook denies.Only built-ins and the engine make records that are sent.
$.telemetry.markDocumentedMarks one use of a feature, as the CLI's own feature events do. It takes no to and always means anthropic.(entry: TelemetryMarkInput) => Promise<void>. The engine does nothing with it. Built-in plugins that hook the event queue the row.Only built-ins and the engine make records that are sent.

Engine Events​

ItemStatusWhat it doesHow it worksWhere it can be used
telemetry.logDocumentedFires when a record is about to be logged to the destination e.to names.Input TelemetryLogInput. Result { value: undefined } or { deny }. e.to is pinned.on('telemetry.log', ...). Also $.telemetry.log(...).
telemetry.markDocumentedFires when one use of a feature is marked. It always goes to anthropic, with no to.Input TelemetryMarkInput. Result { value: undefined } or { deny }. { deny } rejects the caller.on('telemetry.mark', ...). Also $.telemetry.mark(...).

Types​

ItemStatusWhat it is forShape and limits
TelemetryAttributeDocumentedOne attribute of a collector record.string | number | boolean | readonly string[]
TelemetryChoiceDocumentedA string property of a first-party row: the value and the list it is chosen from, so no free text reaches a row.Fields value and of. Every member of of is a lowercase token of letters, digits, _, and -. At most 32 members. value is one of them.
TelemetryDestinationDocumentedWhere a record goes.'anthropic' (first-party analytics) or 'collector' (the one the operator configured).
TelemetryLogArgsDocumentedWhat a call of $.telemetry.log passes.TelemetryRowArgs | TelemetryRecordEntry
TelemetryLogInputDocumentedThe input of telemetry.log. to is always present and pinned.TelemetryRowEntry | TelemetryRecordEntry
TelemetryLogResult, TelemetryMarkResultDocumentedWhat a hook returns and next(e) resolves to.{ value: undefined }, or { deny }, which rejects the caller's promise.
TelemetryMarkInputDocumentedThe input of telemetry.mark.feature (snake_case name), kind (TelemetryMarkKind), reason? (a short token), props? (Readonly<Record<string, TelemetryProp>>).
TelemetryMarkKindDocumentedHow one use of a feature went.'ok' (the person got what they asked), 'sad' (degraded, they still got something), 'bad' (failed, they got nothing).
TelemetryPropDocumentedOne property of a first-party row or a mark.number | boolean | TelemetryChoice
TelemetryRecordEntryDocumentedA record for the collector the operator configured.to ('collector', pinned), event (leaves as claude_code.<event>), attributes (go out as they stand), loggedAt (ISO 8601 to the millisecond), span? (TelemetrySpan).
TelemetryRowArgsDocumentedA first-party row as a call passes it.to? ('anthropic'), event, props?.
TelemetryRowEntryDocumentedA first-party row as a hook reads it. to is always present.to ('anthropic', pinned), event, props?.
TelemetrySpanDocumentedThe span a collector record belongs to, in W3C trace context spelling.traceId (32 hex digits), spanId (16 hex digits), traceFlags (bit 0 set when the trace is sampled).