@frontmcp/observability 0.0.1 → 1.0.0-rc.1

package/plugin/observability.plugin.d.ts

@@ -0,0 +1,141 @@
+import { DynamicPlugin, ProviderType } from '@frontmcp/sdk';
+import type { ObservabilityPluginOptions, ObservabilityPluginOptionsInput } from './observability.plugin.types';
+import type { StartupTelemetryData } from '../otel/spans/startup.span';
+/**
+ * ObservabilityPlugin — comprehensive, zero-config OpenTelemetry instrumentation
+ * for the entire FrontMCP system.
+ *
+ * When installed, spans are created automatically for:
+ * - HTTP requests (every stage: trace → auth → route → transport → finalize)
+ * - Tool calls (parseInput → findTool → auth → validate → execute → UI → finalize)
+ * - Resource reads (parseInput → find → execute → validate → finalize)
+ * - Prompt invocations (parseInput → find → execute → validate → finalize)
+ * - Agent calls (parseInput → find → auth → validate → execute → finalize)
+ * - Skills (search, load)
+ * - List operations (tools, resources, prompts, resource templates)
+ * - Completions
+ * - Session lifecycle (creation, auth verification)
+ *
+ * Single trace ID per request. Privacy-safe session tracing ID.
+ * Every flow stage recorded as a timed span event.
+ */
+export default class ObservabilityPlugin extends DynamicPlugin<ObservabilityPluginOptions, ObservabilityPluginOptionsInput> {
+    static defaultOptions: ObservabilityPluginOptions;
+    options: ObservabilityPluginOptions;
+    private tracingOpts;
+    constructor(options?: ObservabilityPluginOptionsInput);
+    private get tracingEnabled();
+    _httpWillTrace(ctx: unknown): void;
+    _httpWillQuota(ctx: unknown): void;
+    _httpDidSemaphore(ctx: unknown): void;
+    _httpWillAuth(ctx: unknown): void;
+    _httpDidAuth(ctx: unknown): void;
+    _httpWillRoute(ctx: unknown): void;
+    _httpDidRoute(ctx: unknown): void;
+    _httpDidFinalize(ctx: unknown): void;
+    _toolWillParse(ctx: unknown): void;
+    _toolWillFind(ctx: unknown): void;
+    _toolWillCheckAuth(ctx: unknown): void;
+    _toolWillCreateCtx(ctx: unknown): void;
+    _toolWillValidate(ctx: unknown): void;
+    _toolWillExecute(ctx: unknown): void;
+    _toolDidExecute(ctx: unknown): void;
+    _toolWillValidateOut(ctx: unknown): void;
+    _toolWillApplyUI(ctx: unknown): void;
+    _toolDidFinalize(ctx: unknown): void;
+    _resourceWillParse(ctx: unknown): void;
+    _resourceWillFind(ctx: unknown): void;
+    _resourceWillExecute(ctx: unknown): void;
+    _resourceDidExecute(ctx: unknown): void;
+    _resourceDidFinalize(ctx: unknown): void;
+    _promptWillParse(ctx: unknown): void;
+    _promptWillFind(ctx: unknown): void;
+    _promptWillExecute(ctx: unknown): void;
+    _promptDidExecute(ctx: unknown): void;
+    _promptDidFinalize(ctx: unknown): void;
+    _agentWillParse(ctx: unknown): void;
+    _agentWillFind(ctx: unknown): void;
+    _agentWillExecute(ctx: unknown): void;
+    _agentDidExecute(ctx: unknown): void;
+    _agentDidFinalize(ctx: unknown): void;
+    _listToolsWill(ctx: unknown): void;
+    _listToolsDidFind(ctx: unknown): void;
+    _listToolsDone(ctx: unknown): void;
+    _listResourcesWill(ctx: unknown): void;
+    _listResourcesDone(ctx: unknown): void;
+    _listTemplatesWill(ctx: unknown): void;
+    _listTemplatesDone(ctx: unknown): void;
+    _listPromptsWill(ctx: unknown): void;
+    _listPromptsDone(ctx: unknown): void;
+    _skillSearchWill(ctx: unknown): void;
+    _skillSearchDone(ctx: unknown): void;
+    _skillLoadWill(ctx: unknown): void;
+    _skillLoadStage(ctx: unknown): void;
+    _skillLoadDone(ctx: unknown): void;
+    _completionWill(ctx: unknown): void;
+    _completionDone(ctx: unknown): void;
+    _sseWillParse(ctx: unknown): void;
+    _sseDidRoute(ctx: unknown): void;
+    _sseDidInit(ctx: unknown): void;
+    _sseDidMsg(ctx: unknown): void;
+    _sseDidElicit(ctx: unknown): void;
+    _sseDidCleanup(ctx: unknown): void;
+    _shttpWillParse(ctx: unknown): void;
+    _shttpDidRoute(ctx: unknown): void;
+    _shttpDidInit(ctx: unknown): void;
+    _shttpDidMsg(ctx: unknown): void;
+    _shttpDidElicit(ctx: unknown): void;
+    _shttpDidSse(ctx: unknown): void;
+    _shttpDidExtApps(ctx: unknown): void;
+    _shttpDidCleanup(ctx: unknown): void;
+    _slhttpWillParse(ctx: unknown): void;
+    _slhttpDidHandle(ctx: unknown): void;
+    _slhttpDidCleanup(ctx: unknown): void;
+    _authVerifyWill(ctx: unknown): void;
+    _authVerifyDidMode(ctx: unknown): void;
+    _authVerifyDidToken(ctx: unknown): void;
+    _authVerifyDidBuild(ctx: unknown): void;
+    _sessionVerifyWill(ctx: unknown): void;
+    _sessionVerifyDidJwt(ctx: unknown): void;
+    _sessionVerifyDidBuild(ctx: unknown): void;
+    _oauthTokenWill(ctx: unknown): void;
+    _oauthTokenDone(ctx: unknown): void;
+    _oauthAuthzWill(ctx: unknown): void;
+    _oauthAuthzDone(ctx: unknown): void;
+    _oauthCallbackWill(ctx: unknown): void;
+    _oauthCallbackDone(ctx: unknown): void;
+    _oauthProviderWill(ctx: unknown): void;
+    _oauthProviderDone(ctx: unknown): void;
+    _oauthRegisterWill(ctx: unknown): void;
+    _oauthRegisterDone(ctx: unknown): void;
+    _elicitReqWill(ctx: unknown): void;
+    _elicitReqDone(ctx: unknown): void;
+    _elicitResWill(ctx: unknown): void;
+    _elicitResDone(ctx: unknown): void;
+    _subscribeWill(ctx: unknown): void;
+    _subscribeDone(ctx: unknown): void;
+    _unsubscribeWill(ctx: unknown): void;
+    _unsubscribeDone(ctx: unknown): void;
+    _skillsLlmTxtWill(ctx: unknown): void;
+    _skillsLlmTxtDone(ctx: unknown): void;
+    _skillsLlmFullTxtWill(ctx: unknown): void;
+    _skillsLlmFullTxtDone(ctx: unknown): void;
+    _skillsApiWill(ctx: unknown): void;
+    _skillsApiDone(ctx: unknown): void;
+    _jwksWill(ctx: unknown): void;
+    _jwksDone(ctx: unknown): void;
+    _oauthServerWill(ctx: unknown): void;
+    _oauthServerDone(ctx: unknown): void;
+    _prmWill(ctx: unknown): void;
+    _prmDone(ctx: unknown): void;
+    _setLevelWill(ctx: unknown): void;
+    _setLevelDone(ctx: unknown): void;
+    _toolDidCreateCtxFetch(ctx: unknown): void;
+    _agentDidExecuteMeta(ctx: unknown): void;
+    /**
+     * Emit startup telemetry report.
+     * Call after scope.initialize() completes with component counts.
+     */
+    reportStartupTelemetry(data: StartupTelemetryData): void;
+    static dynamicProviders: (input: ObservabilityPluginOptionsInput) => ProviderType[];
+}

package/plugin/observability.plugin.types.d.ts

@@ -0,0 +1,38 @@
+import type { TracingOptions } from '../otel/otel.types';
+import type { SinkConfig } from '../logging/log-sink.interface';
+import type { RequestLogCollectorOptions } from '../request-log/request-log.types';
+/**
+ * Full resolved options for ObservabilityPlugin.
+ */
+export interface ObservabilityPluginOptions {
+    /** OTel tracing configuration */
+    tracing: TracingOptions | false;
+    /** Structured logging configuration */
+    logging: ObservabilityLoggingOptions | false;
+    /** Request log collection configuration */
+    requestLogs: RequestLogCollectorOptions | false;
+}
+/**
+ * Logging options within the plugin.
+ */
+export interface ObservabilityLoggingOptions {
+    /** Sink configurations (default: StdoutSink in Node.js, ConsoleSink in browser) */
+    sinks?: SinkConfig[];
+    /** Field names to redact from log attributes */
+    redactFields?: string[];
+    /** Include stack traces in error entries (default: true) */
+    includeStacks?: boolean;
+    /** Static fields to include in every log entry */
+    staticFields?: Record<string, unknown>;
+}
+/**
+ * User-facing input options (everything is optional).
+ */
+export interface ObservabilityPluginOptionsInput {
+    /** Enable/configure OTel tracing (default: true with all spans enabled) */
+    tracing?: boolean | TracingOptions;
+    /** Enable/configure structured logging */
+    logging?: boolean | ObservabilityLoggingOptions;
+    /** Enable/configure request log collection */
+    requestLogs?: boolean | RequestLogCollectorOptions;
+}

package/request-log/index.d.ts

@@ -0,0 +1,3 @@
+export type { RequestLog, RequestLogEntry, RequestLogCollectorOptions } from './request-log.types';
+export { RequestLogCollector } from './request-log.collector';
+export { REQUEST_LOG_COLLECTOR } from './request-log.tokens';

package/request-log/request-log.collector.d.ts

@@ -0,0 +1,97 @@
+import type { StructuredLogEntry } from '../logging/structured-log.types';
+import type { RequestLog, RequestLogCollectorOptions } from './request-log.types';
+/**
+ * RequestLogCollector — per-request accumulator for structured log entries.
+ *
+ * Created once per request (CONTEXT-scoped). Accumulates log entries
+ * and metadata, then produces a complete RequestLog on finalize.
+ */
+export declare class RequestLogCollector {
+    private readonly entries;
+    private readonly hooksTriggered;
+    private readonly maxEntries;
+    private readonly onComplete?;
+    private readonly requestId;
+    private readonly traceId;
+    private readonly sessionIdHash;
+    private readonly scopeId;
+    private readonly startTime;
+    private httpMethod?;
+    private httpPath?;
+    private rpcMethod?;
+    private toolName?;
+    private resourceUri?;
+    private promptName?;
+    private authType?;
+    private authenticated;
+    private status;
+    private statusCode?;
+    private error?;
+    private finalized;
+    private finalizedLog?;
+    constructor(context: {
+        requestId: string;
+        traceId: string;
+        sessionIdHash: string;
+        scopeId: string;
+    }, options?: RequestLogCollectorOptions);
+    /**
+     * Add a structured log entry to this request's log.
+     * Called by StructuredLogTransport for each log record that
+     * matches this request's requestId.
+     */
+    addEntry(entry: StructuredLogEntry): void;
+    /**
+     * Record a hook stage that was triggered during this request.
+     */
+    addHook(stage: string): void;
+    /**
+     * Set HTTP request metadata.
+     */
+    setHttpInfo(method: string, path: string): void;
+    /**
+     * Set the MCP JSON-RPC method being invoked.
+     */
+    setRpcMethod(method: string): void;
+    /**
+     * Set the tool name being invoked.
+     */
+    setToolName(name: string): void;
+    /**
+     * Set the resource URI being read.
+     */
+    setResourceUri(uri: string): void;
+    /**
+     * Set the prompt name being invoked.
+     */
+    setPromptName(name: string): void;
+    /**
+     * Set authentication info.
+     */
+    setAuthInfo(type: string, authenticated: boolean): void;
+    /**
+     * Set request status.
+     */
+    setStatus(status: RequestLog['status'], statusCode?: number): void;
+    /**
+     * Set error details.
+     */
+    setError(error: RequestLog['error']): void;
+    /**
+     * Finalize and produce the complete RequestLog.
+     * Fires the onRequestComplete callback if configured.
+     */
+    finalize(): Promise<RequestLog>;
+    /**
+     * Build the RequestLog object from accumulated state.
+     */
+    toRequestLog(): RequestLog;
+    /**
+     * Check if the collector has been finalized.
+     */
+    isFinalized(): boolean;
+    /**
+     * Get the number of accumulated entries.
+     */
+    getEntryCount(): number;
+}

package/request-log/request-log.tokens.d.ts

@@ -0,0 +1,7 @@
+/**
+ * DI token for the RequestLogCollector.
+ *
+ * Used as a CONTEXT-scoped provider — one collector per request.
+ * The symbol ensures uniqueness across packages.
+ */
+export declare const REQUEST_LOG_COLLECTOR: unique symbol;

package/request-log/request-log.types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Request Log — per-request aggregated view of all events
+ * during a request lifecycle.
+ */
+/**
+ * Single entry within a request log.
+ */
+export interface RequestLogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log level */
+    level: string;
+    /** Log message */
+    message: string;
+    /** Flow stage that produced the entry */
+    stage?: string;
+    /** Elapsed time since request start (ms) */
+    elapsed_ms?: number;
+    /** Additional structured attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Complete request log — aggregated view of a single request lifecycle.
+ */
+export interface RequestLog {
+    /** Unique request identifier */
+    request_id: string;
+    /** W3C trace ID */
+    trace_id: string;
+    /** SHA-256 truncated session ID */
+    session_id_hash: string;
+    /** Scope identifier */
+    scope_id: string;
+    /** ISO 8601 start time */
+    start_time: string;
+    /** ISO 8601 end time */
+    end_time: string;
+    /** Total duration in milliseconds */
+    duration_ms: number;
+    /** HTTP method (GET, POST, etc.) */
+    http_method?: string;
+    /** URL path */
+    http_path?: string;
+    /** MCP JSON-RPC method (e.g., "tools/call", "resources/read") */
+    rpc_method?: string;
+    /** Tool name (for tools/call requests) */
+    tool_name?: string;
+    /** Resource URI (for resources/read requests) */
+    resource_uri?: string;
+    /** Prompt name (for prompts/get requests) */
+    prompt_name?: string;
+    /** Authentication type used */
+    auth_type?: string;
+    /** Whether the request was authenticated */
+    authenticated: boolean;
+    /** Overall request status */
+    status: 'ok' | 'error' | 'aborted' | 'rate_limited';
+    /** HTTP response status code */
+    status_code?: number;
+    /** Error details (if status = 'error') */
+    error?: {
+        type: string;
+        message: string;
+        code?: string;
+        error_id?: string;
+    };
+    /** Hook stages that were triggered during this request */
+    hooks_triggered: string[];
+    /** All structured log entries for this request */
+    entries: RequestLogEntry[];
+}
+/**
+ * Options for RequestLogCollector.
+ */
+export interface RequestLogCollectorOptions {
+    /** Maximum entries to collect per request (default: 500) */
+    maxEntries?: number;
+    /** Include input/output summaries (default: true) */
+    includeSummaries?: boolean;
+    /** Callback when request log is complete */
+    onRequestComplete?: (log: RequestLog) => void | Promise<void>;
+}

package/telemetry/index.d.ts

@@ -0,0 +1,3 @@
+export { TelemetryAccessor, TelemetrySpan } from './telemetry.accessor';
+export { TELEMETRY_ACCESSOR } from './telemetry.tokens';
+import './telemetry.context-extension';

package/telemetry/telemetry.accessor.d.ts

@@ -0,0 +1,151 @@
+/**
+ * TelemetryAccessor — developer-facing telemetry API.
+ *
+ * Exposed as `this.telemetry` on all execution contexts (ToolContext,
+ * ResourceContext, PromptContext, AgentContext) when ObservabilityPlugin
+ * is installed.
+ *
+ * Key design: `addEvent()` and `setAttributes()` target the **active
+ * flow execution span** (e.g., the tool span during tool.execute()).
+ * This means events appear in the correct parent span timeline,
+ * not as detached spans.
+ *
+ * `startSpan()` and `withSpan()` create child spans under the active
+ * execution span, so they nest correctly in the trace.
+ *
+ * @example
+ * ```typescript
+ * class MyTool extends ToolContext {
+ *   async execute(input) {
+ *     // Events go directly on the tool's execution span
+ *     this.telemetry.addEvent('validation-complete', { valid: true });
+ *     this.telemetry.setAttributes({ 'user.tier': 'premium' });
+ *
+ *     // Child span — nested under the tool span
+ *     const result = await this.telemetry.withSpan('fetch-api', async (span) => {
+ *       const res = await this.fetch('https://api.example.com');
+ *       span.setAttribute('response.status', res.status);
+ *       return res.json();
+ *     });
+ *   }
+ * }
+ * ```
+ */
+import { type Span } from '@opentelemetry/api';
+import { type TraceContextLike } from '../otel/trace-context-bridge';
+/**
+ * Minimal context shape — avoids tight coupling to FrontMcpContext.
+ */
+interface TelemetryContextData {
+    requestId: string;
+    sessionId: string;
+    scopeId: string;
+    traceContext: TraceContextLike;
+    /** FrontMcpContext.get() for reading the active span */
+    get?<T>(key: string | symbol): T | undefined;
+}
+/**
+ * A lightweight span wrapper for developer use.
+ * Hides OTel complexity while preserving full functionality.
+ */
+export declare class TelemetrySpan {
+    private readonly span;
+    private hasError;
+    constructor(span: Span);
+    /** Set a string/number/boolean attribute */
+    setAttribute(key: string, value: string | number | boolean): this;
+    /** Set multiple attributes at once */
+    setAttributes(attrs: Record<string, string | number | boolean>): this;
+    /** Add a named event (with optional attributes) */
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+    /** Record an error on this span */
+    recordError(error: Error): this;
+    /** End the span (preserves ERROR status if already set) */
+    end(): void;
+    /** End the span with error */
+    endWithError(error: Error | string): void;
+    /** Get the underlying OTel span (escape hatch) */
+    get raw(): Span;
+}
+/**
+ * TelemetryAccessor — the developer-facing API exposed as `this.telemetry`.
+ *
+ * One instance per request (CONTEXT-scoped). Automatically inherits
+ * the request's trace context for seamless span correlation.
+ *
+ * `addEvent` and `setAttributes` target the active flow span (set by
+ * the auto-instrumentation hooks during willExecute). `startSpan` and
+ * `withSpan` create child spans under the active flow span.
+ */
+export declare class TelemetryAccessor {
+    private readonly tracer;
+    private readonly fallbackContext;
+    private readonly sessionHash;
+    private readonly baseAttributes;
+    private readonly ctx;
+    constructor(ctx: TelemetryContextData);
+    /**
+     * Get the active OTel context — prefers the execution span's context
+     * (set by hooks during willExecute), falls back to the request-level trace.
+     */
+    private getActiveContext;
+    /**
+     * Get the active execution span (set by auto-instrumentation hooks).
+     * Returns undefined if not inside an instrumented execution stage.
+     */
+    private getActiveSpan;
+    /**
+     * Start a new child span under the current execution span.
+     *
+     * If called inside a tool's execute(), the span is a child of
+     * the tool execution span. Otherwise falls back to the request trace.
+     *
+     * You MUST call `span.end()` or `span.endWithError()` when done.
+     */
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): TelemetrySpan;
+    /**
+     * Run a function within a child span. Automatically ended on
+     * success (OK) or error (ERROR + exception recorded).
+     *
+     * @example
+     * ```typescript
+     * const data = await this.telemetry.withSpan('fetch-api', async (span) => {
+     *   span.addEvent('request-sent');
+     *   const res = await this.fetch(url);
+     *   span.setAttribute('status', res.status);
+     *   return res.json();
+     * });
+     * ```
+     */
+    withSpan<T>(name: string, fn: (span: TelemetrySpan) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
+    /**
+     * Add an event to the **active flow execution span**.
+     *
+     * If called inside a tool's execute(), the event appears on the
+     * tool execution span. If no active span exists, creates a
+     * lightweight child span carrying the event.
+     *
+     * @param name — event name (e.g., 'validation-complete', 'cache-hit')
+     * @param attributes — optional event attributes
+     */
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Set attributes on the **active flow execution span**.
+     *
+     * If called inside a tool's execute(), attributes are set on the
+     * tool execution span. If no active span exists, this is a no-op.
+     *
+     * @param attrs — key-value attributes
+     */
+    setAttributes(attrs: Record<string, string | number | boolean>): void;
+    /**
+     * Get the trace ID of the current request.
+     * Useful for including in external API calls or logs.
+     */
+    get traceId(): string;
+    /**
+     * Get the session tracing ID (privacy-safe hash).
+     */
+    get sessionId(): string;
+}
+export {};

package/telemetry/telemetry.context-extension.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Module augmentation for TypeScript — adds `this.telemetry` to all
+ * execution contexts (ToolContext, ResourceContext, PromptContext, AgentContext).
+ *
+ * This file provides type information only. The runtime getter is
+ * installed by the SDK's context extension mechanism when the
+ * ObservabilityPlugin registers its `contextExtensions`.
+ */
+import type { TelemetryAccessor } from './telemetry.accessor';
+declare module '@frontmcp/sdk' {
+    interface ExecutionContextBase {
+        /**
+         * Telemetry API — create spans, add events, set attributes.
+         *
+         * Available when ObservabilityPlugin is installed.
+         * Automatically inherits the current request's trace context.
+         *
+         * @example
+         * ```typescript
+         * // Create a child span
+         * const span = this.telemetry.startSpan('my-operation');
+         * span.setAttribute('key', 'value');
+         * span.end();
+         *
+         * // Auto-managed span
+         * await this.telemetry.withSpan('fetch-data', async (span) => {
+         *   const data = await this.fetch(url);
+         *   span.addEvent('data-received', { count: data.length });
+         *   return data;
+         * });
+         * ```
+         */
+        readonly telemetry: TelemetryAccessor;
+    }
+}

package/telemetry/telemetry.tokens.d.ts

@@ -0,0 +1,7 @@
+/**
+ * DI token for the TelemetryAccessor.
+ *
+ * CONTEXT-scoped — one instance per request.
+ * Registered by ObservabilityPlugin when tracing is enabled.
+ */
+export declare const TELEMETRY_ACCESSOR: unique symbol;

package/testing/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Testing utilities for @frontmcp/observability.
+ *
+ * Provides helpers to set up OTel tracing in tests and assert
+ * on exported spans without boilerplate.
+ *
+ * @example
+ * ```typescript
+ * import { createTestTracer, getFinishedSpans, assertSpanExists } from '@frontmcp/observability/testing';
+ *
+ * describe('my tool', () => {
+ *   const { tracer, exporter, cleanup } = createTestTracer();
+ *
+ *   afterEach(() => {
+ *     exporter.reset();
+ *   });
+ *
+ *   afterAll(async () => {
+ *     await cleanup();
+ *   });
+ *
+ *   it('should create a span', async () => {
+ *     // ... invoke tool ...
+ *     const spans = getFinishedSpans(exporter);
+ *     assertSpanExists(spans, 'tool get_weather');
+ *   });
+ * });
+ * ```
+ */
+import { type Tracer } from '@opentelemetry/api';
+import { BasicTracerProvider, InMemorySpanExporter, type ReadableSpan } from '@opentelemetry/sdk-trace-base';
+/**
+ * Result from createTestTracer().
+ */
+export interface TestTracer {
+    /** OTel Tracer instance (from the test provider, not global) */
+    tracer: Tracer;
+    /** In-memory span exporter — call .getFinishedSpans() to inspect */
+    exporter: InMemorySpanExporter;
+    /** The test TracerProvider */
+    provider: BasicTracerProvider;
+    /** Cleanup function — call in afterAll/afterEach to shutdown the provider */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Create a test tracer with an in-memory span exporter.
+ *
+ * Does NOT register globally — uses provider.getTracer() directly
+ * to avoid polluting the global tracer provider across tests.
+ *
+ * @param name - Tracer name (default: 'test')
+ */
+export declare function createTestTracer(name?: string): TestTracer;
+/**
+ * Get finished spans from an exporter.
+ */
+export declare function getFinishedSpans(exporter: InMemorySpanExporter): ReadableSpan[];
+/**
+ * Assert that a span with the given name exists.
+ *
+ * @returns The matching span
+ * @throws If no span with the name is found
+ */
+export declare function assertSpanExists(spans: ReadableSpan[], name: string): ReadableSpan;
+/**
+ * Assert that a span has a specific attribute value.
+ */
+export declare function assertSpanAttribute(span: ReadableSpan, key: string, value: string | number | boolean): void;
+/**
+ * Find a span by name.
+ */
+export declare function findSpan(spans: ReadableSpan[], name: string): ReadableSpan | undefined;
+/**
+ * Find all spans with a specific attribute value.
+ */
+export declare function findSpansByAttribute(spans: ReadableSpan[], key: string, value: string | number | boolean): ReadableSpan[];