eve/dist/src/compiled/@workflow/core/telemetry.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import type * as api from '#compiled/@opentelemetry/api/index.js';
import type { Span, SpanKind, SpanOptions } from '#compiled/@opentelemetry/api/index.js';
/**
 * Controls how workflow/step queue-handler spans relate to the run-origin
 * trace context carried in queue messages:
 *
 * - `'linked'` (default): each invocation starts a NEW root trace; the
 *   run-origin context (and the incoming delivery context) are attached as
 *   span links. This keeps traces bounded per invocation instead of
 *   stitching a long-lived run into one giant trace.
 * - `'continuous'`: the restored run-origin context becomes the parent of
 *   the invocation span (legacy behavior), producing a single trace that
 *   spans the entire run.
 */
export type WorkflowTraceMode = 'linked' | 'continuous';
/**
 * Resolves the active trace mode from the `WORKFLOW_TRACE_MODE` env var.
 * Defaults to `'linked'`; any value other than `'continuous'` selects it.
 * Unrecognized non-empty values (e.g. typos like `continous`) emit a
 * one-time warning so silent fallback to `linked` is at least visible.
 */
export declare function getWorkflowTraceMode(): WorkflowTraceMode;
/**
 * Returns whether a serialized trace carrier is usable, i.e. present and
 * non-empty. `serializeTraceCarrier()` returns `{}` when no OTEL SDK is
 * registered or no span is active, and `start()` always attaches the
 * carrier to the first queue message — so an empty carrier must be treated
 * the same as an absent one wherever the trace-mode logic branches.
 */
export declare function isUsableTraceCarrier(carrier: Record<string, string> | undefined): carrier is Record<string, string>;
/**
 * Returns the trace carrier to attach to messages the current invocation
 * enqueues. In `linked` mode the ORIGINAL run-origin carrier is forwarded
 * unchanged (when usable) so every future invocation links back to the same
 * origin; otherwise — `continuous` mode, or no usable incoming carrier —
 * the current (active) context is serialized, so the trace keeps chaining
 * (continuous) or the first instrumented invocation becomes the de-facto
 * origin (linked).
 */
export declare function getNextTraceCarrier(traceMode: WorkflowTraceMode, incomingCarrier: Record<string, string> | undefined): Promise<Record<string, string>>;
/**
 * Builds the span links for a queue-delivered invocation span
 * (`workflow.execute` / `step.execute`):
 *
 * - In `linked` mode the invocation span is a CHILD of the local delivery
 *   (flow-route) context, so the only link is to the run-origin context
 *   from the message's trace carrier — connecting this bounded per-invocation
 *   trace back to where the run was started. The run-origin context is a
 *   link, never a parent, and re-enqueues forward the original carrier
 *   unchanged, so the whole run is never stitched into one giant trace.
 *   The link is skipped when the carrier is absent, empty, or invalid.
 * - In `continuous` mode the run-origin context is restored as the parent
 *   instead, and the link points at the incoming delivery context.
 */
export declare function buildInvocationSpanLinks(traceMode: WorkflowTraceMode, incomingCarrier: Record<string, string> | undefined): Promise<api.Link[] | undefined>;
/**
 * Serializes the current trace context into a format that can be passed through queues
 * @returns A record of strings representing the trace context
 */
export declare function serializeTraceCarrier(): Promise<Record<string, string>>;
/**
 * Deserializes trace context and returns a context that can be used to continue the trace
 * @param traceCarrier The serialized trace context
 * @returns OpenTelemetry context with the restored trace
 */
export declare function deserializeTraceCarrier(traceCarrier: Record<string, string>): Promise<api.Context | undefined>;
/**
 * Runs a function within the context of a deserialized trace
 * @param traceCarrier The serialized trace carrier (optional)
 * @param fn The function to run within the trace context
 * @returns The result of the function
 */
export declare function withTraceContext<T>(traceCarrier: Record<string, string> | undefined, fn: () => Promise<T>): Promise<T>;
export declare function trace<T>(spanName: string, ...args: [fn: (span?: Span) => Promise<T>] | [opts: SpanOptions, fn: (span?: Span) => Promise<T>]): Promise<T>;
/**
 * Emit a span whose start is back-dated to `startEpochMs` and whose end is now,
 * so its duration reflects an interval only measurable at its end (e.g.
 * time-to-first-chunk, known when the first chunk arrives). Unlike `trace()`,
 * this records an already-elapsed span in one shot rather than wrapping a
 * callback. No-op when OpenTelemetry is not available.
 */
export declare function recordElapsedSpan(spanName: string, startEpochMs: number, opts?: SpanOptions): Promise<void>;
export declare function getSpanContextForTraceCarrier(carrier: Record<string, string>): Promise<api.SpanContext | undefined>;
export declare function getActiveSpan(): Promise<api.Span | undefined>;
/**
 * Wraps all methods of an object with tracing spans.
 * @param prefix - Prefix for span names (e.g., "WORLD.runs")
 * @param o - Object with methods to instrument
 * @returns Instrumented object with same interface
 */
export declare function instrumentObject<T extends object>(prefix: string, o: T): T;
export declare function getSpanKind(field: keyof typeof SpanKind): Promise<api.SpanKind | undefined>;
export declare function withOtel<T>(fn: (otel: typeof api) => T): Promise<Awaited<T> | undefined>;
export declare function linkToCurrentContext(): Promise<[api.Link] | undefined>;
/**
 * Builds a span link pointing at the span context embedded in a serialized
 * trace carrier (e.g. the run-origin context flowing through queue
 * messages). Returns `undefined` when OTEL is unavailable, the carrier is
 * absent, or it does not contain a valid span context.
 */
export declare function linkToTraceCarrier(carrier: Record<string, string> | undefined): Promise<api.Link | undefined>;
/**
 * Workflow context to propagate via baggage
 */
export interface WorkflowBaggageContext {
    workflowRunId: string;
    workflowName: string;
}
/**
 * Sets workflow context as OTEL baggage for automatic propagation.
 * Baggage is propagated across service boundaries via HTTP headers.
 * @param context - Workflow context to set as baggage
 * @returns A function to run within the baggage context
 */
export declare function withWorkflowBaggage<T>(context: WorkflowBaggageContext, fn: () => Promise<T>): Promise<T>;
/**
 * Retrieves workflow context from OTEL baggage.
 * @returns Workflow context if present in baggage, undefined otherwise
 */
export declare function getWorkflowBaggage(): Promise<WorkflowBaggageContext | undefined>;
//# sourceMappingURL=telemetry.d.ts.map