autotel-cloudflare/dist/agents.d.ts

The #1 OpenTelemetry package for Cloudflare Workers - complete bindings coverage, native CF OTel integration, advanced sampling

import { ConfigurationOption } from 'autotel-edge';
import { Attributes } from '@opentelemetry/api';

/**
 * Type definitions for Cloudflare Agents SDK observability integration
 */

/**
 * Base event structure from Agents SDK (mirrors agents/src/observability/base.ts)
 */
interface BaseAgentEvent<T extends string, Payload extends Record<string, unknown> = Record<string, unknown>> {
    type: T;
    /** Unique identifier for the event */
    id: string;
    /** Human-readable message for logging */
    displayMessage: string;
    /** Event payload with type-specific data */
    payload: Payload & Record<string, unknown>;
    /** Timestamp in milliseconds since epoch */
    timestamp: number;
}
/**
 * Agent-specific observability events
 */
type AgentObservabilityEvent = BaseAgentEvent<'state:update', Record<string, unknown>> | BaseAgentEvent<'rpc', {
    method: string;
    streaming?: boolean;
}> | BaseAgentEvent<'message:request' | 'message:response', Record<string, unknown>> | BaseAgentEvent<'message:clear'> | BaseAgentEvent<'schedule:create' | 'schedule:execute' | 'schedule:cancel', {
    callback: string;
    id: string;
}> | BaseAgentEvent<'destroy'> | BaseAgentEvent<'connect', {
    connectionId: string;
}>;
/**
 * MCP-specific observability events
 */
type MCPObservabilityEvent = BaseAgentEvent<'mcp:client:preconnect', {
    serverId: string;
}> | BaseAgentEvent<'mcp:client:connect', {
    url: string;
    transport: string;
    state: string;
    error?: string;
}> | BaseAgentEvent<'mcp:client:authorize', {
    serverId: string;
    authUrl: string;
    clientId?: string;
}> | BaseAgentEvent<'mcp:client:discover', Record<string, unknown>>;
/**
 * Union of all observability event types
 */
type ObservabilityEvent = AgentObservabilityEvent | MCPObservabilityEvent;
/**
 * Observability interface from Agents SDK
 */
interface Observability {
    /**
     * Emit an event for the Agent's observability implementation to handle.
     * @param event - The event to emit
     * @param ctx - The execution context of the invocation (optional)
     */
    emit(event: ObservabilityEvent, ctx?: DurableObjectState): void;
}
/**
 * Agent-specific instrumentation options
 */
interface AgentInstrumentationOptions {
    /**
     * Whether to create spans for RPC calls
     * @default true
     */
    traceRpc?: boolean;
    /**
     * Whether to create spans for schedule operations
     * @default true
     */
    traceSchedule?: boolean;
    /**
     * Whether to create spans for MCP operations
     * @default true
     */
    traceMcp?: boolean;
    /**
     * Whether to create spans for state updates
     * @default false (can be noisy)
     */
    traceStateUpdates?: boolean;
    /**
     * Whether to create spans for message events
     * @default true
     */
    traceMessages?: boolean;
    /**
     * Whether to create spans for connect/destroy lifecycle events
     * @default true
     */
    traceLifecycle?: boolean;
    /**
     * Custom attribute extractor for events
     */
    attributeExtractor?: (event: ObservabilityEvent) => Attributes;
    /**
     * Custom span name formatter
     */
    spanNameFormatter?: (event: ObservabilityEvent) => string;
}
/**
 * Configuration for OtelObservability
 */
type OtelObservabilityConfig = ConfigurationOption & {
    /**
     * Agent-specific instrumentation options
     */
    agents?: AgentInstrumentationOptions;
};
/**
 * Semantic attributes for Agent spans
 */
interface AgentSpanAttributes {
    'agent.event.type': string;
    'agent.event.id': string;
    'agent.rpc.method'?: string;
    'agent.rpc.streaming'?: boolean;
    'agent.schedule.callback'?: string;
    'agent.schedule.id'?: string;
    'agent.connection.id'?: string;
    'agent.mcp.server_id'?: string;
    'agent.mcp.url'?: string;
    'agent.mcp.transport'?: string;
    'agent.mcp.state'?: string;
}

/**
 * OpenTelemetry-based Observability implementation for Cloudflare Agents SDK
 *
 * Converts Agent events into OpenTelemetry spans for distributed tracing.
 *
 * @example
 * ```typescript
 * import { Agent } from 'agents'
 * import { createOtelObservability } from 'autotel-cloudflare/agents'
 *
 * class MyAgent extends Agent<Env> {
 *   observability = createOtelObservability({
 *     service: { name: 'my-agent' },
 *     exporter: { url: env.OTLP_ENDPOINT }
 *   })
 *
 *   @callable()
 *   async doSomething() {
 *     // This RPC call will be automatically traced
 *     return 'done'
 *   }
 * }
 * ```
 */

/**
 * OpenTelemetry-based Observability implementation
 *
 * Implements the Agents SDK Observability interface and converts
 * events into OpenTelemetry spans.
 */
declare class OtelObservability implements Observability {
    private config;
    private options;
    private initialized;
    constructor(config: OtelObservabilityConfig);
    /**
     * Initialize the tracer provider (called lazily on first emit)
     */
    private initialize;
    /**
     * Emit an observability event
     *
     * Converts the event to an OpenTelemetry span based on the event type.
     */
    emit(event: ObservabilityEvent, ctx?: DurableObjectState): void;
}
/**
 * Create an OtelObservability instance
 *
 * @example
 * ```typescript
 * import { Agent } from 'agents'
 * import { createOtelObservability } from 'autotel-cloudflare/agents'
 *
 * class MyAgent extends Agent<Env> {
 *   observability = createOtelObservability({
 *     service: { name: 'my-agent' },
 *     exporter: { url: env.OTLP_ENDPOINT }
 *   })
 * }
 * ```
 */
declare function createOtelObservability(config: OtelObservabilityConfig): OtelObservability;
/**
 * Create an OtelObservability instance with environment-based config
 *
 * Use this when you need to access environment variables for configuration.
 *
 * @example
 * ```typescript
 * import { Agent } from 'agents'
 * import { createOtelObservabilityFromEnv } from 'autotel-cloudflare/agents'
 *
 * class MyAgent extends Agent<Env> {
 *   observability?: OtelObservability
 *
 *   constructor(state: DurableObjectState, env: Env) {
 *     super(state, env)
 *     this.observability = createOtelObservabilityFromEnv(env)
 *   }
 * }
 * ```
 */
declare function createOtelObservabilityFromEnv(env: Record<string, unknown>, options?: AgentInstrumentationOptions): OtelObservability;

export { type AgentInstrumentationOptions, type AgentObservabilityEvent, type AgentSpanAttributes, type MCPObservabilityEvent, type Observability, type ObservabilityEvent, OtelObservability, type OtelObservabilityConfig, createOtelObservability, createOtelObservabilityFromEnv };