1
// Copyright (c) 2026 Cloudflare, Inc.
2
// Licensed under the Apache 2.0 license found in the LICENSE file or at:
3
//     https://opensource.org/licenses/Apache-2.0
4
 
5
// A value acceptable as an attribute on a span.
6
type SpanValue = string | number | boolean;
7
 
8
declare class Span {
9
  // Returns true if this span will be recorded to the tracing system. False when the
10
  // current async context is not being traced, or when the span has already been submitted
11
  // (which happens automatically when the enterSpan callback returns). Callers can gate
12
  // expensive attribute-computation code on this.
13
  readonly isTraced: boolean;
14
 
15
  // Sets a single attribute on the span. If `value` is undefined, the attribute is not set,
16
  // which is convenient for optional fields.
17
  setAttribute(key: string, value: SpanValue | undefined): void;
18
}
19
 
20
// The default export is a singleton instance of the C++ `Tracing` class (see
21
// `src/workerd/api/tracing.h`). Importers write `import tracing from
22
// 'cloudflare-internal:tracing'` and then call methods like `tracing.enterSpan(...)` on
23
// the instance. The runtime wires this up via `addBuiltinModule<Tracing>` in
24
// `registerTracingModule`.
25
declare const tracing: {
26
  // Creates a new child span of the current span, pushes it onto the async context as
27
  // the active span, invokes `callback(span, ...args)`, and automatically ends the span
28
  // when the callback returns (sync) or when its returned promise settles (async, either
29
  // fulfilled or rejected). If no IO context is present the callback runs with a no-op
30
  // span.
31
  enterSpan<T, A extends unknown[]>(
32
    name: string,
33
    callback: (span: Span, ...args: A) => T,
34
    ...args: A
35
  ): T;
36
 
37
  // The `Span` class is exposed as a nested type so callers can reference the type via
38
  // `InstanceType<typeof tracing.Span>` (see `tracing-helpers.ts`).
39
  readonly Span: typeof Span;
40
};
41
export default tracing;
42
 
43
// Re-export `Span` as a named type export for callers that prefer `import type { Span }`
44
// over `InstanceType<typeof tracing.Span>`. The runtime module does not have a named
45
// `Span` export - this is purely a type-level convenience.
46
export type { Span };