Skip to content
rachel/workerd
File

Blob: types/defines/trace.d.ts

typescript244 lines
1declare namespace TailStream {
2 
3interface Header {
4  readonly name: string;
5  readonly value: string;
6}
7 
8interface FetchEventInfo {
9  readonly type: "fetch";
10  readonly method: string;
11  readonly url: string;
12  readonly cfJson?: object;
13  readonly headers: Header[];
14}
15 
16interface JsRpcEventInfo {
17  readonly type: "jsrpc";
18}
19 
20interface ScheduledEventInfo {
21  readonly type: "scheduled";
22  readonly scheduledTime: Date;
23  readonly cron: string;
24}
25 
26interface AlarmEventInfo {
27  readonly type: "alarm";
28  readonly scheduledTime: Date;
29}
30 
31interface QueueEventInfo {
32  readonly type: "queue";
33  readonly queueName: string;
34  readonly batchSize: number;
35}
36 
37interface EmailEventInfo {
38  readonly type: "email";
39  readonly mailFrom: string;
40  readonly rcptTo: string;
41  readonly rawSize: number;
42}
43 
44interface TraceEventInfo {
45  readonly type: "trace";
46  readonly traces: (string | null)[];
47}
48 
49interface HibernatableWebSocketEventInfoMessage {
50  readonly type: "message";
51}
52interface HibernatableWebSocketEventInfoError {
53  readonly type: "error";
54}
55interface HibernatableWebSocketEventInfoClose {
56  readonly type: "close";
57  readonly code: number;
58  readonly wasClean: boolean;
59}
60 
61interface HibernatableWebSocketEventInfo {
62  readonly type: "hibernatableWebSocket";
63  readonly info: HibernatableWebSocketEventInfoClose |
64                 HibernatableWebSocketEventInfoError |
65                 HibernatableWebSocketEventInfoMessage;
66}
67 
68interface CustomEventInfo {
69  readonly type: "custom";
70}
71 
72interface FetchResponseInfo {
73  readonly type: "fetch";
74  readonly statusCode: number;
75}
76 
77interface ConnectEventInfo {
78  readonly type: "connect";
79}
80 
81type EventOutcome = "ok" | "canceled" | "exception" | "unknown" | "killSwitch" |
82                    "daemonDown" | "exceededCpu" | "exceededMemory" | "loadShed" |
83                    "responseStreamDisconnected" | "scriptNotFound" | "internalError";
84 
85interface ScriptVersion {
86  readonly id: string;
87  readonly tag?: string;
88  readonly message?: string;
89}
90 
91interface TracePreviewInfo {
92  readonly id: string;
93  readonly slug: string;
94  readonly name: string;
95}
96 
97interface Onset {
98  readonly type: "onset";
99  readonly attributes: Attribute[];
100  // id for the span being opened by this Onset event.
101  readonly spanId: string;
102  readonly dispatchNamespace?: string;
103  readonly entrypoint?: string;
104  readonly executionModel: string;
105  readonly scriptName?: string;
106  readonly scriptTags?: string[];
107  readonly scriptVersion?: ScriptVersion;
108  readonly preview?: TracePreviewInfo;
109  readonly info: FetchEventInfo | ConnectEventInfo | JsRpcEventInfo |
110                 ScheduledEventInfo | AlarmEventInfo | QueueEventInfo |
111                 EmailEventInfo | TraceEventInfo |
112                 HibernatableWebSocketEventInfo | CustomEventInfo;
113}
114 
115interface Outcome {
116  readonly type: "outcome";
117  readonly outcome: EventOutcome;
118  readonly cpuTime: number;
119  readonly wallTime: number;
120}
121 
122interface SpanOpen {
123  readonly type: "spanOpen";
124  readonly name: string;
125  // id for the span being opened by this SpanOpen event.
126  readonly spanId: string;
127  readonly info?: FetchEventInfo | JsRpcEventInfo | Attributes;
128}
129 
130interface SpanClose {
131  readonly type: "spanClose";
132  readonly outcome: EventOutcome;
133}
134 
135interface DiagnosticChannelEvent {
136  readonly type: "diagnosticChannel";
137  readonly channel: string;
138  readonly message: any;
139}
140 
141interface Exception {
142  readonly type: "exception";
143  readonly name: string;
144  readonly message: string;
145  readonly stack?: string;
146}
147 
148interface Log {
149  readonly type: "log";
150  readonly level: "debug" | "error" | "info" | "log" | "warn";
151  readonly message: object;
152}
153 
154interface DroppedEventsDiagnostic {
155  readonly diagnosticsType: "droppedEvents";
156  readonly count: number;
157}
158 
159interface StreamDiagnostic {
160  readonly type: 'streamDiagnostic';
161  // To add new diagnostic types, define a new interface and add it to this union type.
162  readonly diagnostic: DroppedEventsDiagnostic;
163}
164 
165// This marks the worker handler return information.
166// This is separate from Outcome because the worker invocation can live for a long time after
167// returning. For example - Websockets that return an http upgrade response but then continue
168// streaming information or SSE http connections.
169interface Return {
170  readonly type: "return";
171  readonly info?: FetchResponseInfo;
172}
173 
174interface Attribute {
175  readonly name: string;
176  readonly value: string | string[] | boolean | boolean[] | number | number[] | bigint | bigint[];
177}
178 
179interface Attributes {
180  readonly type: "attributes";
181  readonly info: Attribute[];
182}
183 
184type EventType =
185  | Onset
186  | Outcome
187  | SpanOpen
188  | SpanClose
189  | DiagnosticChannelEvent
190  | Exception
191  | Log
192  | StreamDiagnostic
193  | Return
194  | Attributes;
195 
196// Context in which this trace event lives.
197interface SpanContext {
198  // Single id for the entire top-level invocation
199  // This should be a new traceId for the first worker stage invoked in the eyeball request and then
200  // same-account service-bindings should reuse the same traceId but cross-account service-bindings
201  // should use a new traceId.
202  readonly traceId: string;
203  // spanId in which this event is handled
204  // for Onset and SpanOpen events this would be the parent span id
205  // for Outcome and SpanClose these this would be the span id of the opening Onset and SpanOpen events
206  // For Hibernate and Mark this would be the span under which they were emitted.
207  // spanId is not set ONLY if:
208  //  1. This is an Onset event
209  //  2. We are not inheriting any SpanContext. (e.g. this is a cross-account service binding or a new top-level invocation)
210  readonly spanId?: string;
211  // W3C trace flags from an upstream traceparent. Absent when no upstream
212  // sampling decision was made.
213  readonly traceFlags?: number;
214}
215 
216interface TailEvent<Event extends EventType> {
217  // invocation id of the currently invoked worker stage.
218  // invocation id will always be unique to every Onset event and will be the same until the Outcome event.
219  readonly invocationId: string;
220  // Inherited spanContext for this event.
221  readonly spanContext: SpanContext;
222  readonly timestamp: Date;
223  readonly sequence: number;
224  readonly event: Event;
225}
226 
227type TailEventHandler<Event extends EventType = EventType> = (
228  event: TailEvent<Event>
229) => void | Promise<void>;
230 
231type TailEventHandlerObject = {
232  outcome?: TailEventHandler<Outcome>;
233  spanOpen?: TailEventHandler<SpanOpen>;
234  spanClose?: TailEventHandler<SpanClose>;
235  diagnosticChannel?: TailEventHandler<DiagnosticChannelEvent>;
236  exception?: TailEventHandler<Exception>;
237  log?: TailEventHandler<Log>;
238  return?: TailEventHandler<Return>;
239  attributes?: TailEventHandler<Attributes>;
240};
241 
242type TailEventHandlerType = TailEventHandler | TailEventHandlerObject;
243}