surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / mods / telemetry / types / index.d.ts

Alice T'Poteattelemetry: log and mark are what the mod's hooks do, the noun added only where the engine has none (#96917) 6557bbe · 28 days ago History

131 lines · 4.6 KBRaw

1	/**
2	* The `$.telemetry` noun as every caller sees it: the one contract for the
3	* noun, its types exported here and the noun declared on `EngineInterface`.
4	*
5	* The telemetry mod hooks the noun's two events, `telemetry.log` and
6	* `telemetry.mark`, and is what queues and sends a row; on an engine that
7	* has no `telemetry` of its own it also adds the noun in the `engine.create`
8	* fold, checked against `EngineInterface['telemetry']`. Its hooks import
9	* these types from this folder, a mod that calls the noun and a test that
10	* answers it read them by including it in their tsconfig. Nothing here is
11	* imported, so it stands on its own.
12	*/
13
14	/**
15	* A plugin's analytics, queued through `$.telemetry` and sent in batches.
16	*
17	* The telemetry mod serves the plugins built into the CLI alone: a call from
18	* an installed plugin rejects. Where the mod is off or absent nothing is
19	* queued, and on an engine without the noun there is no `$.telemetry`.
20	*/
21	export type Telemetry = {
22	/**
23	* Queues one event, `tengu_plugin_<event>`, as one first-party row, sent
24	* with the next batch; resolves once queued, rejects a malformed entry.
25	*
26	* The calling mod names itself in `event`; one already named `tengu_…` is
27	* sent as named. A value is a finite number, a boolean or a
28	* TelemetryChoice; free text is refused. One input, as every op on `$`
29	* takes. Whether a batch went out is a line in the debug log.
30	*
31	* @param entry the event's name, a snake_case token, and its properties by
32	* snake_case key
33	* @example
34	* await $.telemetry.log({
35	* event: "suggest_learning_survey_answered",
36	* props: {
37	* answer: 2,
38	* page: { value: "ready", of: ["ready", "later"] },
39	* },
40	* })
41	*/
42	log: (entry: TelemetryLogEntry) => Promise<void>
43
44	/**
45	* Marks one use of a feature as the CLI's own feature events do, one
46	* `tengu_feature_<kind>` row queued for the next batch; resolves once
47	* queued, rejects a malformed entry.
48	*
49	* The row carries `feature_name`, `error_code` on sad or bad (`reason`,
50	* required there and refused on ok) and the entry's `props`, checked as
51	* `log`'s are; it joins the product-wide feature surface, so no prefix.
52	*
53	* @param entry the feature, how it went, why when not ok, and the row's
54	* properties by snake_case key
55	* @example
56	* await $.telemetry.mark({ feature: "learn_page", kind: "ok" })
57	* await $.telemetry.mark({
58	* feature: "learn_page",
59	* kind: "sad",
60	* reason: "blocked",
61	* })
62	*/
63	mark: (entry: TelemetryMarkEntry) => Promise<void>
64	}
65
66	/**
67	* Where a logged record goes: `anthropic`, the first-party analytics this
68	* mod sends, or `collector`, the telemetry collector a session's operator
69	* configured, which this mod leaves to whatever is beneath it.
70	*/
71	export type TelemetryDestination = 'anthropic' \| 'collector'
72
73	/**
74	* What `$.telemetry.log` takes: the event's name after the prefix, and its
75	* properties by snake_case key.
76	*
77	* `to` names the destination and is never part of the row; left out, it
78	* reads as `anthropic`. An entry for `collector` is not this mod's: its
79	* hook passes it on beneath untouched.
80	*/
81	export type TelemetryLogEntry = {
82	to?: TelemetryDestination
83	event: string
84	props?: Readonly<Record<string, TelemetryProp>>
85	}
86
87	/**
88	* What `$.telemetry.mark` takes: the feature, how it went, why when not
89	* ok, and the properties the row carries beside them by snake_case key.
90	*/
91	export type TelemetryMarkEntry = {
92	feature: string
93	kind: TelemetryMarkKind
94	reason?: string
95	props?: Readonly<Record<string, TelemetryProp>>
96	}
97
98	/**
99	* How a feature went, as the CLI's own feature events count it.
100	*
101	* `ok`: used, the person got what they asked. `sad`: degraded, a fallback
102	* or a partial, the person still got something. `bad`: failed, the person
103	* got nothing.
104	*/
105	export type TelemetryMarkKind = 'ok' \| 'sad' \| 'bad'
106
107	/**
108	* A property's value: a finite number, a boolean, or a TelemetryChoice;
109	* never free text.
110	*/
111	export type TelemetryProp = number \| boolean \| TelemetryChoice
112
113	/**
114	* A string property: the value and the list it is chosen from, declared
115	* beside it, so no free text reaches the row.
116	*
117	* Every member of `of` is a lowercase token of letters, digits, `_` and
118	* `-`, which may start with a digit, at most 32 of them; `value` is one of
119	* them.
120	*/
121	export type TelemetryChoice = { value: string; of: readonly string[] }
122
123	declare module 'claude-code' {
124	interface EngineInterface {
125	/**
126	* A built-in plugin's analytics, first-party rows sent in batches;
127	* present where the telemetry mod is seated, refused to installed plugins.
128	*/
129	telemetry: Telemetry
130	}
131	}