eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
110 lines • 6.01 kB
TypeScript
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`):
*
* - a link to the incoming delivery context (the active span extracted from
* the queue delivery request, i.e. the enqueue site once the queue
* propagates producer context), and
* - in `linked` mode, a link to the run-origin context from the message's
* trace carrier (skipped when absent, empty, invalid, or identical to the
* 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>;
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