@beignet/core/dist/tracing/index.d.ts

Core framework primitives for Beignet

/**
 * @beignet/core/tracing
 *
 * W3C trace context primitives used to correlate Beignet activity across
 * requests, use cases, providers, and instrumentation sinks.
 *
 * This module is dependency-free so client bundles that import app context
 * types stay clean.
 */
/** Current version of Beignet's durable trace carrier. */
export declare const TRACE_CARRIER_VERSION: 1;
/**
 * Vendor-neutral trace context stored in durable messages and transport
 * envelopes. Unknown versions and malformed values are ignored by consumers.
 */
export interface TraceCarrier {
    /** Carrier schema version. */
    readonly version: typeof TRACE_CARRIER_VERSION;
    /** W3C traceparent value captured at the producing boundary. */
    readonly traceparent: string;
    /** Optional W3C tracestate value captured at the producing boundary. */
    readonly tracestate?: string;
}
/**
 * Trace context used to correlate related activity.
 */
export interface TraceContext {
    /**
     * W3C trace ID.
     */
    traceId: string;
    /**
     * Current span ID.
     */
    spanId: string;
    /**
     * Parent span ID when available.
     */
    parentSpanId?: string;
    /**
     * W3C traceparent header value.
     */
    traceparent: string;
    /**
     * Optional W3C tracestate value associated with this context.
     */
    tracestate?: string;
}
/**
 * Parsed W3C traceparent header.
 */
export interface ParsedTraceparent {
    /**
     * W3C trace ID.
     */
    traceId: string;
    /**
     * Span ID from the traceparent header.
     */
    spanId: string;
    /**
     * Trace flags from the traceparent header.
     */
    traceFlags: string;
    /**
     * Normalized traceparent header value.
     */
    traceparent: string;
}
/**
 * Input accepted when creating trace context.
 */
export interface TraceContextInput {
    traceId?: string;
    spanId?: string;
    parentSpanId?: string;
    traceparent?: string;
    tracestate?: string;
}
/** Values accepted as tracing attributes. */
export type TraceAttributeValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
/** Attributes attached to a traced Beignet operation. */
export type TraceAttributes = Readonly<Record<string, TraceAttributeValue>>;
/** Span kinds understood by tracing providers. */
export type TraceSpanKind = "internal" | "server" | "client" | "producer" | "consumer";
/** Stable Beignet operation categories used by tracing and metrics providers. */
export type TraceOperationType = "request" | "useCase" | "agentCapability" | "listener" | "job" | "schedule" | "task" | "outbox" | "provider";
/** Description of one operation to run inside an active trace span. */
export interface TraceOperation {
    name: string;
    type: TraceOperationType;
    kind?: TraceSpanKind;
    parent?: TraceContextInput;
    /** Attributes attached to the operation span. */
    attributes?: TraceAttributes;
    /**
     * Bounded attributes attached to operation metrics. Values must describe a
     * stable operation dimension, never a request, actor, tenant, or payload.
     */
    metricAttributes?: TraceAttributes;
}
/** Framework-neutral span handle exposed to Beignet execution wrappers. */
export interface TraceSpan {
    readonly context: TraceContext;
    setAttribute(name: string, value: TraceAttributeValue): void;
    setAttributes(attributes: TraceAttributes): void;
    addEvent(name: string, attributes?: TraceAttributes): void;
    setStatus(status: "ok" | "error"): void;
    recordError(error: unknown): void;
}
/** Optional app port implemented by production tracing integrations. */
export interface TracingPort {
    current(): TraceContext | undefined;
    startActiveSpan<T>(operation: TraceOperation, run: (span: TraceSpan) => T): T;
}
/** Return whether a value implements `TracingPort`. */
export declare function isTracingPort(value: unknown): value is TracingPort;
/** Resolve a tracing port from a direct port, ports object, or app context. */
export declare function resolveTracingPort(target: unknown): TracingPort | undefined;
/**
 * Parse an untrusted durable trace carrier.
 *
 * Invalid carriers return `undefined`; trace metadata must never prevent
 * message delivery.
 */
export declare function parseTraceCarrier(value: unknown): TraceCarrier | undefined;
/**
 * Capture the current trace context from a tracing port, ports object, app
 * context, or explicit trace context. Returns `undefined` when no valid
 * context is available.
 */
export declare function captureTraceCarrier(target: unknown): TraceCarrier | undefined;
/** Resolve trace fields from a trace context or context-like object. */
export declare function resolveTraceContextInput(target: unknown): TraceContextInput | undefined;
/** Run a callback inside a tracing span when an app tracing port is installed. */
export declare function runWithTracing<T>(target: unknown, operation: TraceOperation, run: (span?: TraceSpan) => T): T;
/**
 * Create a non-zero W3C trace ID.
 */
export declare function createTraceId(): string;
/**
 * Create a non-zero W3C span ID.
 */
export declare function createSpanId(): string;
/**
 * Create a W3C traceparent header value.
 */
export declare function createTraceparent(args: {
    traceId: string;
    spanId: string;
    traceFlags?: string;
}): string;
/**
 * Parse and validate a W3C traceparent header value.
 */
export declare function parseTraceparent(value: string | null | undefined): ParsedTraceparent | undefined;
/**
 * Create trace context from explicit IDs or an existing traceparent.
 */
export declare function createTraceContext(input?: TraceContextInput): TraceContext;
/**
 * Create child trace context from a parent context.
 */
export declare function createChildTraceContext(parent: TraceContextInput): TraceContext;
//# sourceMappingURL=index.d.ts.map