effect 4.0.0-beta.66 → 4.0.0-beta.68

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 4.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 2.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";

package/dist/Tracer.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tracer.js","names":["Context","constFalse","Option","evaluate","ParentSpanKey","ParentSpan","Service","make","options","externalSpan","_tag","spanId","traceId","sampled","annotations","empty","DisablePropagation","Reference","defaultValue","CurrentTraceLevel","MinimumTraceLevel","TracerKey","Tracer","span","NativeSpan","name","parent","links","startTime","kind","status","attributes","events","constructor","Map","getOrUndefined","randomHexString","end","endTime","exit","attribute","key","value","set","event","push","addLinks","characters","charactersLength","length","result","i","charAt","Math","floor","random"],"sources":["../src/Tracer.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,OAAO,KAAKA,OAAO,MAAM,cAAc;AAGvC,SAASC,UAAU,QAAsB,eAAe;AAGxD,OAAO,KAAKC,MAAM,MAAM,aAAa;AAsBrC,MAAMC,QAAQ,GAAG,yBAAiD;AAiElE;;;;;;;;;;;AAWA,OAAO,MAAMC,aAAa,GAAG,0BAA0B;AAEvD;;;;;;;;;;;;;;AAcA,OAAM,MAAOC,UAAW,sBAAQL,OAAO,CAACM,OAAO,EAAuB,CAACF,aAAa,CAAC;AAkKrF;;;;AAIA,OAAO,MAAMG,IAAI,GAAIC,OAAe,IAAaA,OAAO;AAExD;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMC,YAAY,GACvBD,OAKC,KACiB;EAClBE,IAAI,EAAE,cAAc;EACpBC,MAAM,EAAEH,OAAO,CAACG,MAAM;EACtBC,OAAO,EAAEJ,OAAO,CAACI,OAAO;EACxBC,OAAO,EAAEL,OAAO,CAACK,OAAO,IAAI,IAAI;EAChCC,WAAW,EAAEN,OAAO,CAACM,WAAW,IAAId,OAAO,CAACe,KAAK;CAClD,CAAC;AAEF;;;;;;;;;;;;;;;AAeA,OAAO,MAAMC,kBAAkB,gBAAGhB,OAAO,CAACiB,SAAS,CACjD,kCAAkC,EAClC;EAAEC,YAAY,EAAEjB;AAAU,CAAE,CAC7B;AAED;;;;;;AAMA,OAAO,MAAMkB,iBAAiB,gBAAgCnB,OAAO,CAACiB,SAAS,CAC7E,iCAAiC,EACjC;EAAEC,YAAY,EAAEA,CAAA,KAAM;AAAM,CAAE,CAC/B;AAED;;;;;;;;AAQA,OAAO,MAAME,iBAAiB,gBAAGpB,OAAO,CAACiB,SAAS,CAEhD,iCAAiC,EAAE;EAAEC,YAAY,EAAEA,CAAA,KAAM;AAAK,CAAE,CAAC;AAEnE;;;;AAIA,OAAO,MAAMG,SAAS,GAAG,eAAe;AAExC;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMC,MAAM,gBAA8BtB,OAAO,CAACiB,SAAS,CAASI,SAAS,EAAE;EACpFH,YAAY,EAAEA,CAAA,KACZX,IAAI,CAAC;IACHgB,IAAI,EAAGf,OAAO,IAAK,IAAIgB,UAAU,CAAChB,OAAO;GAC1C;CACJ,CAAC;AAEF;;;;AAIA,OAAM,MAAOgB,UAAU;EACZd,IAAI,GAAG,MAAM;EACbC,MAAM;EACNC,OAAO,GAAW,QAAQ;EAC1BC,OAAO;EAEPY,IAAI;EACJC,MAAM;EACNZ,WAAW;EACXa,KAAK;EACLC,SAAS;EACTC,IAAI;EAEbC,MAAM;EACNC,UAAU;EACVC,MAAM,GAAkF,EAAE;EAE1FC,YAAYzB,OAQX;IACC,IAAI,CAACiB,IAAI,GAAGjB,OAAO,CAACiB,IAAI;IACxB,IAAI,CAACC,MAAM,GAAGlB,OAAO,CAACkB,MAAM;IAC5B,IAAI,CAACZ,WAAW,GAAGN,OAAO,CAACM,WAAW;IACtC,IAAI,CAACa,KAAK,GAAGnB,OAAO,CAACmB,KAAK;IAC1B,IAAI,CAACC,SAAS,GAAGpB,OAAO,CAACoB,SAAS;IAClC,IAAI,CAACC,IAAI,GAAGrB,OAAO,CAACqB,IAAI;IACxB,IAAI,CAAChB,OAAO,GAAGL,OAAO,CAACK,OAAO;IAC9B,IAAI,CAACiB,MAAM,GAAG;MACZpB,IAAI,EAAE,SAAS;MACfkB,SAAS,EAAEpB,OAAO,CAACoB;KACpB;IACD,IAAI,CAACG,UAAU,GAAG,IAAIG,GAAG,EAAE;IAC3B,IAAI,CAACtB,OAAO,GAAGV,MAAM,CAACiC,cAAc,CAAC3B,OAAO,CAACkB,MAAM,CAAC,EAAEd,OAAO,IAAIwB,eAAe,CAAC,EAAE,CAAC;IACpF,IAAI,CAACzB,MAAM,GAAGyB,eAAe,CAAC,EAAE,CAAC;EACnC;EAEAC,GAAGA,CAACC,OAAe,EAAEC,IAAiC;IACpD,IAAI,CAACT,MAAM,GAAG;MACZpB,IAAI,EAAE,OAAO;MACb4B,OAAO;MACPC,IAAI;MACJX,SAAS,EAAE,IAAI,CAACE,MAAM,CAACF;KACxB;EACH;EAEAY,SAASA,CAACC,GAAW,EAAEC,KAAc;IACnC,IAAI,CAACX,UAAU,CAACY,GAAG,CAACF,GAAG,EAAEC,KAAK,CAAC;EACjC;EAEAE,KAAKA,CAACnB,IAAY,EAAEG,SAAiB,EAAEG,UAAoC;IACzE,IAAI,CAACC,MAAM,CAACa,IAAI,CAAC,CAACpB,IAAI,EAAEG,SAAS,EAAEG,UAAU,IAAI,EAAE,CAAC,CAAC;EACvD;EAEAe,QAAQA,CAACnB,KAA8B;IACrC;IACA,IAAI,CAACA,KAAK,CAACkB,IAAI,CAAC,GAAGlB,KAAK,CAAC;EAC3B;;AAGF,MAAMS,eAAe,gBAAI;EACvB,MAAMW,UAAU,GAAG,kBAAkB;EACrC,MAAMC,gBAAgB,GAAGD,UAAU,CAACE,MAAM;EAC1C,OAAO,UAASA,MAAc;IAC5B,IAAIC,MAAM,GAAG,EAAE;IACf,KAAK,IAAIC,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGF,MAAM,EAAEE,CAAC,EAAE,EAAE;MAC/BD,MAAM,IAAIH,UAAU,CAACK,MAAM,CAACC,IAAI,CAACC,KAAK,CAACD,IAAI,CAACE,MAAM,EAAE,GAAGP,gBAAgB,CAAC,CAAC;IAC3E;IACA,OAAOE,MAAM;EACf,CAAC;AACH,CAAC,CAAC,CAAE","ignoreList":[]}
+{"version":3,"file":"Tracer.js","names":["Context","constFalse","Option","evaluate","ParentSpanKey","ParentSpan","Service","make","options","externalSpan","_tag","spanId","traceId","sampled","annotations","empty","DisablePropagation","Reference","defaultValue","CurrentTraceLevel","MinimumTraceLevel","TracerKey","Tracer","span","NativeSpan","name","parent","links","startTime","kind","status","attributes","events","constructor","Map","getOrUndefined","randomHexString","end","endTime","exit","attribute","key","value","set","event","push","addLinks","characters","charactersLength","length","result","i","charAt","Math","floor","random"],"sources":["../src/Tracer.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}