effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/Tracer.d.ts

@@ -1,4 +1,42 @@
 /**
+ * The `Tracer` module defines the low-level tracing model used by Effect to
+ * describe and propagate spans. A span records the lifetime of an operation,
+ * including its name, parent, attributes, links, annotations, sampling decision,
+ * kind, and completion status.
+ *
+ * **Mental model**
+ *
+ * - `Tracer` is the backend interface responsible for creating spans
+ * - `Span` values represent Effect-managed operations with mutable lifecycle
+ *   hooks for ending spans and adding attributes, events, or links
+ * - `ExternalSpan` represents trace context imported from another tracing
+ *   system so Effect spans can be parented by or linked to external work
+ * - `ParentSpan`, `Tracer`, and related context references control propagation,
+ *   sampling, and trace-level filtering through the Effect context
+ *
+ * **Common tasks**
+ *
+ * - Implement a custom tracing backend with {@link make}
+ * - Provide or inspect parent span context with {@link ParentSpan}
+ * - Convert external trace identifiers into Effect span values with
+ *   {@link externalSpan}
+ * - Configure span metadata with {@link SpanOptions}, {@link SpanKind}, and
+ *   {@link SpanLink}
+ * - Disable propagation or adjust trace filtering with
+ *   {@link DisablePropagation}, {@link CurrentTraceLevel}, and
+ *   {@link MinimumTraceLevel}
+ *
+ * **Gotchas**
+ *
+ * - This module exposes the tracing data model and backend hooks; most
+ *   application code should create spans through higher-level Effect APIs such
+ *   as `Effect.withSpan`
+ * - `ExternalSpan` only carries identity and metadata from another system; it
+ *   does not have lifecycle methods like `Span`
+ * - Propagation and sampling are context-dependent, so parent selection can be
+ *   affected by disabled propagation, root span options, and trace-level
+ *   thresholds
+ *
  * @since 2.0.0
  */
 import * as Context from "./Context.ts";
@@ -8,8 +46,14 @@ import { type LazyArg } from "./Function.ts";
 import type { LogLevel } from "./LogLevel.ts";
 import * as Option from "./Option.ts";
 /**
- * @since 2.0.0
+ * A tracing backend used by Effect to create spans.
+ *
+ * Custom tracers implement `span` to allocate a span from the supplied name,
+ * parent, annotations, links, start time, kind, root flag, and sampling
+ * decision.
+ *
  * @category models
+ * @since 2.0.0
  */
 export interface Tracer {
     span(this: Tracer, options: {
@@ -26,34 +70,48 @@ export interface Tracer {
 }
 declare const evaluate = "~effect/Effect/evaluate";
 /**
- * @since 4.0.0
+ * A low-level Effect primitive that can be evaluated by a tracer-specific
+ * context for the current fiber.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface EffectPrimitive<X> {
     [evaluate](this: EffectPrimitive<X>, fiber: Fiber<any, any>): X;
 }
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * Lifecycle state of a span.
+ *
+ * `Started` records the start time, while `Ended` records the start time, end
+ * time, and exit value with which the span completed.
+ *
+ * **Example** (Creating span statuses)
+ *
  * ```ts
  * import type { Tracer } from "effect"
  * import { Exit } from "effect"
  *
- * // Started span status
+ * const startTime = 1_000_000_000n
+ * const endTime = 1_500_000_000n
+ *
  * const startedStatus: Tracer.SpanStatus = {
  *   _tag: "Started",
- *   startTime: BigInt(Date.now() * 1000000)
+ *   startTime
  * }
  *
- * // Ended span status
  * const endedStatus: Tracer.SpanStatus = {
  *   _tag: "Ended",
- *   startTime: BigInt(Date.now() * 1000000),
- *   endTime: BigInt(Date.now() * 1000000 + 1000000),
+ *   startTime,
+ *   endTime,
  *   exit: Exit.succeed("result")
  * }
+ *
+ * console.log(startedStatus._tag) // "Started"
+ * console.log(endedStatus.endTime - endedStatus.startTime) // 500000000n
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export type SpanStatus = {
     _tag: "Started";
@@ -65,9 +123,11 @@ export type SpanStatus = {
     exit: Exit.Exit<unknown, unknown>;
 };
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * A span value that can participate in tracing, either an Effect-managed
+ * `Span` or an `ExternalSpan` propagated from another tracing system.
+ *
+ * **Example** (Accepting any span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -83,25 +143,34 @@ export type SpanStatus = {
  *   traceId: "trace-456"
  * })
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export type AnySpan = Span | ExternalSpan;
 /**
- * @since 2.0.0
- * @category tags
- * @example
+ * The string key used to identify the `ParentSpan` context service.
+ *
+ * **Example** (Reading the parent span key)
+ *
  * ```ts
  * import { Tracer } from "effect"
  *
  * // The key used to identify parent spans in the context
  * console.log(Tracer.ParentSpanKey) // "effect/Tracer/ParentSpan"
  * ```
+ *
+ * @category tags
+ * @since 2.0.0
  */
 export declare const ParentSpanKey = "effect/Tracer/ParentSpan";
 declare const ParentSpan_base: Context.ServiceClass<ParentSpan, "effect/Tracer/ParentSpan", AnySpan>;
 /**
- * @since 2.0.0
- * @category tags
- * @example
+ * Context service containing the `Span` or `ExternalSpan` to use as the parent
+ * of newly-created child spans.
+ *
+ * **Example** (Accessing the parent span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -111,13 +180,19 @@ declare const ParentSpan_base: Context.ServiceClass<ParentSpan, "effect/Tracer/P
  *   console.log(`Parent span: ${parentSpan.spanId}`)
  * })
  * ```
+ *
+ * @category tags
+ * @since 2.0.0
  */
 export declare class ParentSpan extends ParentSpan_base {
 }
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * Represents a span created outside Effect's tracer, carrying trace and span
+ * identifiers, sampling state, and annotations so it can be used as a parent or
+ * link in Effect tracing.
+ *
+ * **Example** (Creating an external span value)
+ *
  * ```ts
  * import type { Tracer } from "effect"
  * import { Context } from "effect"
@@ -133,6 +208,9 @@ export declare class ParentSpan extends ParentSpan_base {
  *
  * console.log(`External span: ${externalSpan.spanId}`)
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export interface ExternalSpan {
     readonly _tag: "ExternalSpan";
@@ -142,9 +220,12 @@ export interface ExternalSpan {
     readonly annotations: Context.Context<never>;
 }
 /**
- * @since 3.1.0
- * @category models
- * @example
+ * Options accepted by span-creating APIs, combining span metadata such as
+ * attributes, links, parent/root selection, kind, sampling, and trace level
+ * with stack trace capture settings.
+ *
+ * **Example** (Configuring span options)
+ *
  * ```ts
  * import type { Tracer } from "effect"
  * import { Effect } from "effect"
@@ -161,12 +242,19 @@ export interface ExternalSpan {
  *   Effect.withSpan("my-operation", options)
  * )
  * ```
+ *
+ * @category models
+ * @since 3.1.0
  */
 export interface SpanOptions extends SpanOptionsNoTrace, TraceOptions {
 }
 /**
- * @since 3.1.0
+ * Span creation options that do not control stack trace capture, including
+ * attributes, links, parent or root selection, annotations, span kind,
+ * sampling, and the trace level used for filtering.
+ *
  * @category models
+ * @since 3.1.0
  */
 export interface SpanOptionsNoTrace {
     readonly attributes?: Record<string, unknown> | undefined;
@@ -179,16 +267,22 @@ export interface SpanOptionsNoTrace {
     readonly level?: LogLevel | undefined;
 }
 /**
- * @since 3.1.0
+ * Options that control stack trace capture for tracing wrappers.
+ *
+ * `captureStackTrace` can disable capture or provide a lazy stack string.
+ *
  * @category models
+ * @since 3.1.0
  */
 export interface TraceOptions {
     readonly captureStackTrace?: boolean | LazyArg<string | undefined> | undefined;
 }
 /**
- * @since 3.1.0
- * @category models
- * @example
+ * OpenTelemetry-style role describing the kind of operation represented by a
+ * span: internal work, server handling, client calls, producing, or consuming.
+ *
+ * **Example** (Configuring span kinds)
+ *
  * ```ts
  * import type { Tracer } from "effect"
  * import { Effect } from "effect"
@@ -206,23 +300,69 @@ export interface TraceOptions {
  *   kind: "internal" as Tracer.SpanKind
  * })
  * ```
+ *
+ * @category models
+ * @since 3.1.0
  */
 export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * A span created by an Effect tracer.
+ *
+ * It carries trace identity, parent, annotations, attributes, links, sampling
+ * and kind information, lifecycle status, and methods to end the span or add
+ * attributes, events, and links.
+ *
+ * **Example** (Working with spans)
+ *
  * ```ts
- * import { Effect } from "effect"
+ * import type { Tracer } from "effect"
+ * import { Context, Exit, Option } from "effect"
  *
- * // Working with spans using withSpan
- * const program = Effect.succeed("Hello World").pipe(
- *   Effect.withSpan("my-operation")
- * )
+ * const attributes = new Map<string, unknown>()
+ * const links: Array<Tracer.SpanLink> = []
+ * let status: Tracer.SpanStatus = {
+ *   _tag: "Started",
+ *   startTime: 1_000_000_000n
+ * }
+ *
+ * const span: Tracer.Span = {
+ *   _tag: "Span",
+ *   name: "load-user",
+ *   spanId: "span-1",
+ *   traceId: "trace-1",
+ *   parent: Option.none(),
+ *   annotations: Context.empty(),
+ *   get status() {
+ *     return status
+ *   },
+ *   attributes,
+ *   links,
+ *   sampled: true,
+ *   kind: "internal",
+ *   end(endTime, exit) {
+ *     status = { _tag: "Ended", startTime: status.startTime, endTime, exit }
+ *   },
+ *   attribute(key, value) {
+ *     attributes.set(key, value)
+ *   },
+ *   event(name, startTime, eventAttributes = {}) {
+ *     console.log(`${name} at ${startTime} with ${Object.keys(eventAttributes).length} attributes`)
+ *   },
+ *   addLinks(newLinks) {
+ *     links.push(...newLinks)
+ *   }
+ * }
+ *
+ * span.attribute("user.id", "123")
+ * span.end(1_500_000_000n, Exit.succeed("user"))
  *
- * // The span interface defines the properties available
- * // when working with tracing in your effects
+ * console.log(span.name) // "load-user"
+ * console.log(span.attributes.get("user.id")) // "123"
+ * console.log(span.status._tag) // "Ended"
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export interface Span {
     readonly _tag: "Span";
@@ -242,9 +382,11 @@ export interface Span {
     addLinks(links: ReadonlyArray<SpanLink>): void;
 }
 /**
- * @since 2.0.0
- * @category models
- * @example
+ * A relationship from one span to another span, with attributes describing the
+ * relationship.
+ *
+ * **Example** (Linking spans)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -263,20 +405,28 @@ export interface Span {
  *   Effect.withSpan("linked-operation", { links: [link] })
  * )
  * ```
+ *
+ * @category models
+ * @since 2.0.0
  */
 export interface SpanLink {
     readonly span: AnySpan;
     readonly attributes: Readonly<Record<string, unknown>>;
 }
 /**
- * @since 2.0.0
+ * Creates a `Tracer` value from a tracer implementation object.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: (options: Tracer) => Tracer;
 /**
- * @since 2.0.0
- * @category constructors
- * @example
+ * Creates an `ExternalSpan` from trace and span identifiers, defaulting
+ * `sampled` to `true` and annotations to an empty context when they are not
+ * provided.
+ *
+ * **Example** (Creating an external span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -292,6 +442,9 @@ export declare const make: (options: Tracer) => Tracer;
  *   Effect.withSpan("child-operation", { parent: span })
  * )
  * ```
+ *
+ * @category constructors
+ * @since 2.0.0
  */
 export declare const externalSpan: (options: {
     readonly spanId: string;
@@ -300,9 +453,14 @@ export declare const externalSpan: (options: {
     readonly annotations?: Context.Context<never> | undefined;
 }) => ExternalSpan;
 /**
- * @since 3.12.0
- * @category references
- * @example
+ * Reference used to disable trace propagation.
+ *
+ * When set on the fiber or span annotations, new spans are created as
+ * non-propagating no-op spans and disabled spans are skipped when deriving a
+ * parent span.
+ *
+ * **Example** (Disabling span propagation)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -313,6 +471,9 @@ export declare const externalSpan: (options: {
  *   Effect.provideService(Tracer.DisablePropagation, true)
  * )
  * ```
+ *
+ * @category references
+ * @since 3.12.0
  */
 export declare const DisablePropagation: Context.Reference<boolean>;
 /**
@@ -332,14 +493,19 @@ export declare const CurrentTraceLevel: Context.Reference<LogLevel>;
  */
 export declare const MinimumTraceLevel: Context.Reference<LogLevel>;
 /**
- * @since 4.0.0
+ * The string key used to identify the active `Tracer` context reference.
+ *
  * @category references
+ * @since 4.0.0
  */
 export declare const TracerKey = "effect/Tracer";
 /**
- * @since 4.0.0
- * @category references
- * @example
+ * Context reference for the active tracer service.
+ *
+ * By default it uses the native tracer, which creates `NativeSpan` instances.
+ *
+ * **Example** (Accessing the current tracer)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -355,11 +521,19 @@ export declare const TracerKey = "effect/Tracer";
  *   console.log("Current tracer obtained")
  * })
  * ```
+ *
+ * @category references
+ * @since 4.0.0
  */
 export declare const Tracer: Context.Reference<Tracer>;
 /**
- * @since 4.0.0
+ * Default in-memory `Span` implementation used by the native tracer.
+ *
+ * It generates span and trace identifiers, stores attributes, events, and
+ * links, and records `Started` or `Ended` status.
+ *
  * @category native tracer
+ * @since 4.0.0
  */
 export declare class NativeSpan implements Span {
     readonly _tag = "Span";

package/dist/Tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tracer.d.ts","sourceRoot":"","sources":["../src/Tracer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Tracer.d.ts","sourceRoot":"","sources":["../src/Tracer.ts"],"names":[],"mappings":"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"}

package/dist/Tracer.js

@@ -1,4 +1,42 @@
 /**
+ * The `Tracer` module defines the low-level tracing model used by Effect to
+ * describe and propagate spans. A span records the lifetime of an operation,
+ * including its name, parent, attributes, links, annotations, sampling decision,
+ * kind, and completion status.
+ *
+ * **Mental model**
+ *
+ * - `Tracer` is the backend interface responsible for creating spans
+ * - `Span` values represent Effect-managed operations with mutable lifecycle
+ *   hooks for ending spans and adding attributes, events, or links
+ * - `ExternalSpan` represents trace context imported from another tracing
+ *   system so Effect spans can be parented by or linked to external work
+ * - `ParentSpan`, `Tracer`, and related context references control propagation,
+ *   sampling, and trace-level filtering through the Effect context
+ *
+ * **Common tasks**
+ *
+ * - Implement a custom tracing backend with {@link make}
+ * - Provide or inspect parent span context with {@link ParentSpan}
+ * - Convert external trace identifiers into Effect span values with
+ *   {@link externalSpan}
+ * - Configure span metadata with {@link SpanOptions}, {@link SpanKind}, and
+ *   {@link SpanLink}
+ * - Disable propagation or adjust trace filtering with
+ *   {@link DisablePropagation}, {@link CurrentTraceLevel}, and
+ *   {@link MinimumTraceLevel}
+ *
+ * **Gotchas**
+ *
+ * - This module exposes the tracing data model and backend hooks; most
+ *   application code should create spans through higher-level Effect APIs such
+ *   as `Effect.withSpan`
+ * - `ExternalSpan` only carries identity and metadata from another system; it
+ *   does not have lifecycle methods like `Span`
+ * - Propagation and sampling are context-dependent, so parent selection can be
+ *   affected by disabled propagation, root span options, and trace-level
+ *   thresholds
+ *
  * @since 2.0.0
  */
 import * as Context from "./Context.js";
@@ -6,21 +44,27 @@ import { constFalse } from "./Function.js";
 import * as Option from "./Option.js";
 const evaluate = "~effect/Effect/evaluate";
 /**
- * @since 2.0.0
- * @category tags
- * @example
+ * The string key used to identify the `ParentSpan` context service.
+ *
+ * **Example** (Reading the parent span key)
+ *
  * ```ts
  * import { Tracer } from "effect"
  *
  * // The key used to identify parent spans in the context
  * console.log(Tracer.ParentSpanKey) // "effect/Tracer/ParentSpan"
  * ```
+ *
+ * @category tags
+ * @since 2.0.0
  */
 export const ParentSpanKey = "effect/Tracer/ParentSpan";
 /**
- * @since 2.0.0
- * @category tags
- * @example
+ * Context service containing the `Span` or `ExternalSpan` to use as the parent
+ * of newly-created child spans.
+ *
+ * **Example** (Accessing the parent span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -30,17 +74,25 @@ export const ParentSpanKey = "effect/Tracer/ParentSpan";
  *   console.log(`Parent span: ${parentSpan.spanId}`)
  * })
  * ```
+ *
+ * @category tags
+ * @since 2.0.0
  */
 export class ParentSpan extends /*#__PURE__*/Context.Service()(ParentSpanKey) {}
 /**
- * @since 2.0.0
+ * Creates a `Tracer` value from a tracer implementation object.
+ *
  * @category constructors
+ * @since 2.0.0
  */
 export const make = options => options;
 /**
- * @since 2.0.0
- * @category constructors
- * @example
+ * Creates an `ExternalSpan` from trace and span identifiers, defaulting
+ * `sampled` to `true` and annotations to an empty context when they are not
+ * provided.
+ *
+ * **Example** (Creating an external span)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -56,6 +108,9 @@ export const make = options => options;
  *   Effect.withSpan("child-operation", { parent: span })
  * )
  * ```
+ *
+ * @category constructors
+ * @since 2.0.0
  */
 export const externalSpan = options => ({
   _tag: "ExternalSpan",
@@ -65,9 +120,14 @@ export const externalSpan = options => ({
   annotations: options.annotations ?? Context.empty()
 });
 /**
- * @since 3.12.0
- * @category references
- * @example
+ * Reference used to disable trace propagation.
+ *
+ * When set on the fiber or span annotations, new spans are created as
+ * non-propagating no-op spans and disabled spans are skipped when deriving a
+ * parent span.
+ *
+ * **Example** (Disabling span propagation)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -78,6 +138,9 @@ export const externalSpan = options => ({
  *   Effect.provideService(Tracer.DisablePropagation, true)
  * )
  * ```
+ *
+ * @category references
+ * @since 3.12.0
  */
 export const DisablePropagation = /*#__PURE__*/Context.Reference("effect/Tracer/DisablePropagation", {
   defaultValue: constFalse
@@ -103,14 +166,19 @@ export const MinimumTraceLevel = /*#__PURE__*/Context.Reference("effect/Tracer/M
   defaultValue: () => "All"
 });
 /**
- * @since 4.0.0
+ * The string key used to identify the active `Tracer` context reference.
+ *
  * @category references
+ * @since 4.0.0
  */
 export const TracerKey = "effect/Tracer";
 /**
- * @since 4.0.0
- * @category references
- * @example
+ * Context reference for the active tracer service.
+ *
+ * By default it uses the native tracer, which creates `NativeSpan` instances.
+ *
+ * **Example** (Accessing the current tracer)
+ *
  * ```ts
  * import { Effect, Tracer } from "effect"
  *
@@ -126,6 +194,9 @@ export const TracerKey = "effect/Tracer";
  *   console.log("Current tracer obtained")
  * })
  * ```
+ *
+ * @category references
+ * @since 4.0.0
  */
 export const Tracer = /*#__PURE__*/Context.Reference(TracerKey, {
   defaultValue: () => make({
@@ -133,8 +204,13 @@ export const Tracer = /*#__PURE__*/Context.Reference(TracerKey, {
   })
 });
 /**
- * @since 4.0.0
+ * Default in-memory `Span` implementation used by the native tracer.
+ *
+ * It generates span and trace identifiers, stores attributes, events, and
+ * links, and records `Started` or `Ended` status.
+ *
  * @category native tracer
+ * @since 4.0.0
  */
 export class NativeSpan {
   _tag = "Span";