@lleverage-ai/agent-sdk 0.0.1

package/dist/observability/tracing.d.ts

@@ -0,0 +1,378 @@
+/**
+ * Distributed Tracing System.
+ *
+ * Provides OpenTelemetry-compatible tracing for:
+ * - Agent request tracing
+ * - Tool execution spans
+ * - Subagent spans
+ * - Cross-service correlation
+ *
+ * The implementation is framework-agnostic and can be used with
+ * actual OpenTelemetry or any compatible tracing system.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Span status codes.
+ *
+ * @category Observability
+ */
+export type SpanStatusCode = "unset" | "ok" | "error";
+/**
+ * Span kind (direction of the span).
+ *
+ * @category Observability
+ */
+export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+/**
+ * Span attributes (key-value metadata).
+ *
+ * @category Observability
+ */
+export type SpanAttributes = Record<string, string | number | boolean | string[] | number[] | boolean[]>;
+/**
+ * Span event (point-in-time occurrence).
+ *
+ * @category Observability
+ */
+export interface SpanEvent {
+    /** Event name */
+    name: string;
+    /** Event timestamp (ISO string) */
+    timestamp: string;
+    /** Optional attributes */
+    attributes?: SpanAttributes;
+}
+/**
+ * Span link (reference to another span).
+ *
+ * @category Observability
+ */
+export interface SpanLink {
+    /** Trace ID of linked span */
+    traceId: string;
+    /** Span ID of linked span */
+    spanId: string;
+    /** Optional attributes */
+    attributes?: SpanAttributes;
+}
+/**
+ * Span status.
+ *
+ * @category Observability
+ */
+export interface SpanStatus {
+    /** Status code */
+    code: SpanStatusCode;
+    /** Optional status message */
+    message?: string;
+}
+/**
+ * A completed span data structure.
+ *
+ * @category Observability
+ */
+export interface SpanData {
+    /** Unique trace identifier */
+    traceId: string;
+    /** Unique span identifier */
+    spanId: string;
+    /** Parent span ID (if any) */
+    parentSpanId?: string;
+    /** Span name/operation */
+    name: string;
+    /** Span kind */
+    kind: SpanKind;
+    /** Start time (ISO string) */
+    startTime: string;
+    /** End time (ISO string) */
+    endTime: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Span attributes */
+    attributes: SpanAttributes;
+    /** Span events */
+    events: SpanEvent[];
+    /** Span links */
+    links: SpanLink[];
+    /** Span status */
+    status: SpanStatus;
+}
+/**
+ * An active span that can be modified.
+ *
+ * @category Observability
+ */
+export interface Span {
+    /** Trace ID */
+    readonly traceId: string;
+    /** Span ID */
+    readonly spanId: string;
+    /** Span name */
+    readonly name: string;
+    /** Set an attribute */
+    setAttribute(key: string, value: string | number | boolean): Span;
+    /** Set multiple attributes */
+    setAttributes(attributes: SpanAttributes): Span;
+    /** Add an event */
+    addEvent(name: string, attributes?: SpanAttributes): Span;
+    /** Add a link to another span */
+    addLink(traceId: string, spanId: string, attributes?: SpanAttributes): Span;
+    /** Set status */
+    setStatus(code: SpanStatusCode, message?: string): Span;
+    /** Record an exception */
+    recordException(error: Error, attributes?: SpanAttributes): Span;
+    /** End the span */
+    end(): void;
+    /** Get span data (only valid after end) */
+    getData(): SpanData | null;
+    /** Check if span is recording */
+    isRecording(): boolean;
+}
+/**
+ * Span context for propagation.
+ *
+ * @category Observability
+ */
+export interface SpanContext {
+    /** Trace ID */
+    traceId: string;
+    /** Span ID */
+    spanId: string;
+    /** Trace flags */
+    traceFlags?: number;
+    /** Trace state */
+    traceState?: string;
+}
+/**
+ * A span exporter sends spans to a backend.
+ *
+ * @category Observability
+ */
+export interface SpanExporter {
+    /** Exporter name */
+    name: string;
+    /** Export spans */
+    export(spans: SpanData[]): void | Promise<void>;
+    /** Optional flush for batch exporters */
+    flush?(): void | Promise<void>;
+    /** Optional shutdown for cleanup */
+    shutdown?(): void | Promise<void>;
+}
+/**
+ * Options for creating a tracer.
+ *
+ * @category Observability
+ */
+export interface TracerOptions {
+    /** Tracer/service name */
+    name?: string;
+    /** Tracer version */
+    version?: string;
+    /** Default attributes for all spans */
+    defaultAttributes?: SpanAttributes;
+    /** Span exporters */
+    exporters?: SpanExporter[];
+    /** Whether to enable tracing */
+    enabled?: boolean;
+    /** Sampling rate (0-1) */
+    samplingRate?: number;
+}
+/**
+ * Options for starting a span.
+ *
+ * @category Observability
+ */
+export interface StartSpanOptions {
+    /** Span kind */
+    kind?: SpanKind;
+    /** Initial attributes */
+    attributes?: SpanAttributes;
+    /** Parent span context */
+    parent?: SpanContext;
+    /** Links to other spans */
+    links?: SpanLink[];
+}
+/**
+ * A tracer creates and manages spans.
+ *
+ * @category Observability
+ */
+export interface Tracer {
+    /** Tracer name */
+    readonly name: string;
+    /** Whether tracing is enabled */
+    readonly enabled: boolean;
+    /** Start a new span */
+    startSpan(name: string, options?: StartSpanOptions): Span;
+    /**
+     * Execute a function within a span.
+     * The span is automatically ended when the function completes.
+     */
+    withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>, options?: StartSpanOptions): Promise<T>;
+    /** Get the current active span (if any) */
+    getActiveSpan(): Span | null;
+    /** Export all pending spans */
+    flush(): Promise<void>;
+    /** Shutdown the tracer */
+    shutdown(): Promise<void>;
+}
+/**
+ * Creates a tracer for distributed tracing.
+ *
+ * @param options - Tracer options
+ * @returns A tracer instance
+ *
+ * @example
+ * ```typescript
+ * const tracer = createTracer({
+ *   name: "my-agent",
+ *   exporters: [createConsoleSpanExporter()],
+ * });
+ *
+ * const span = tracer.startSpan("generate");
+ * try {
+ *   const result = await agent.generate({ prompt: "Hello" });
+ *   span.setAttribute("tokens", result.usage?.totalTokens ?? 0);
+ *   span.setStatus("ok");
+ * } catch (error) {
+ *   span.recordException(error as Error);
+ * } finally {
+ *   span.end();
+ * }
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createTracer(options?: TracerOptions): Tracer;
+/**
+ * Creates a console exporter for debugging.
+ *
+ * @returns A console span exporter
+ *
+ * @example
+ * ```typescript
+ * const tracer = createTracer({
+ *   exporters: [createConsoleSpanExporter()],
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createConsoleSpanExporter(): SpanExporter;
+/**
+ * Creates a memory exporter that stores spans.
+ *
+ * @returns A memory span exporter with access to stored spans
+ *
+ * @example
+ * ```typescript
+ * const exporter = createMemorySpanExporter();
+ * const tracer = createTracer({ exporters: [exporter] });
+ *
+ * tracer.startSpan("test").end();
+ * await tracer.flush();
+ *
+ * console.log(exporter.spans);
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createMemorySpanExporter(): SpanExporter & {
+    spans: SpanData[];
+    clear(): void;
+};
+/**
+ * Creates a callback exporter that invokes a function for each batch.
+ *
+ * @param callback - Function to call with spans
+ * @returns A callback span exporter
+ *
+ * @example
+ * ```typescript
+ * const exporter = createCallbackSpanExporter((spans) => {
+ *   sendToJaeger(spans);
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createCallbackSpanExporter(callback: (spans: SpanData[]) => void | Promise<void>): SpanExporter;
+/**
+ * Creates an OTLP-compatible exporter (OpenTelemetry Protocol).
+ *
+ * This exporter formats spans for OTLP collectors but does not
+ * include HTTP transport. Use with a custom callback for actual sending.
+ *
+ * @param options - Exporter options
+ * @returns An OTLP-compatible exporter
+ *
+ * @example
+ * ```typescript
+ * const exporter = createOTLPSpanExporter({
+ *   onExport: async (payload) => {
+ *     await fetch("http://collector:4318/v1/traces", {
+ *       method: "POST",
+ *       headers: { "Content-Type": "application/json" },
+ *       body: JSON.stringify(payload),
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createOTLPSpanExporter(options: {
+    /** Service name */
+    serviceName?: string;
+    /** Callback to handle OTLP payload */
+    onExport: (payload: unknown) => void | Promise<void>;
+}): SpanExporter;
+/**
+ * The default global tracer instance.
+ *
+ * @category Observability
+ */
+export declare let defaultTracer: Tracer;
+/**
+ * Sets the default global tracer.
+ *
+ * @param tracer - The tracer to use as default
+ *
+ * @category Observability
+ */
+export declare function setDefaultTracer(tracer: Tracer): void;
+/**
+ * Semantic attribute keys for AI/LLM operations.
+ *
+ * Based on emerging OpenTelemetry semantic conventions for GenAI.
+ *
+ * @category Observability
+ */
+export declare const SemanticAttributes: {
+    readonly SERVICE_NAME: "service.name";
+    readonly SERVICE_VERSION: "service.version";
+    readonly GEN_AI_SYSTEM: "gen_ai.system";
+    readonly GEN_AI_REQUEST_MODEL: "gen_ai.request.model";
+    readonly GEN_AI_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens";
+    readonly GEN_AI_REQUEST_TEMPERATURE: "gen_ai.request.temperature";
+    readonly GEN_AI_RESPONSE_MODEL: "gen_ai.response.model";
+    readonly GEN_AI_RESPONSE_FINISH_REASONS: "gen_ai.response.finish_reasons";
+    readonly GEN_AI_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly GEN_AI_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly GEN_AI_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens";
+    readonly AGENT_ID: "agent.id";
+    readonly AGENT_NAME: "agent.name";
+    readonly AGENT_TOOLS: "agent.tools";
+    readonly AGENT_STEP: "agent.step";
+    readonly TOOL_NAME: "tool.name";
+    readonly TOOL_INPUT: "tool.input";
+    readonly TOOL_OUTPUT: "tool.output";
+    readonly SUBAGENT_ID: "subagent.id";
+    readonly SUBAGENT_TYPE: "subagent.type";
+    readonly SUBAGENT_PROMPT: "subagent.prompt";
+    readonly EXCEPTION_TYPE: "exception.type";
+    readonly EXCEPTION_MESSAGE: "exception.message";
+    readonly EXCEPTION_STACKTRACE: "exception.stacktrace";
+};
+//# sourceMappingURL=tracing.d.ts.map

package/dist/observability/tracing.d.ts.map

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