autotel-cloudflare 18.0.0 → 18.1.0

package/README.md

@@ -40,6 +40,8 @@ enabled = true
 
 When native tracing is active, autotel **defers to the platform**: it does not proxy-instrument bindings (no duplicate spans) and does not run its own exporter. It routes your custom spans to `tracing.enterSpan()` and surfaces the `cf-ray` id as `ctx.correlationId` + a `correlation.id` span attribute. Controlled by `nativeTracing: 'auto' | 'on' | 'off'` (default `'auto'`).
 
+In both modes autotel also records the issue signals Workers Issues derives from logs, as span exceptions: `console.error(...)` (status untouched, `captureConsoleErrors: false` to opt out), `autotel.LogFlood` for logging in a loop (`logFloodThreshold`, default `100`), and `autotel.RunawayAlarm` when a Durable Object's `alarm()` runs more than 10 times in 60s (`runawayAlarm: { maxRuns, windowMs }` or `false`).
+
 ### Same code, both modes: captured evidence
 
 This is real output from [`apps/cloudflare-example`](../../apps/cloudflare-example) (`node scripts/capture-evidence.mjs`). Identical business logic, two runtimes:
@@ -68,6 +70,44 @@ Note the native tree has **no `KV MY_KV: get` span**. Cloudflare emits that nati
 
 Full details, degradation map, and the forward-compatible trace-id story: [docs/CLOUDFLARE-NATIVE-TRACING.md](../../docs/CLOUDFLARE-NATIVE-TRACING.md).
 
+## No SDK: a Tail Worker
+
+Observe a Worker without changing its code. A [Tail Worker](https://developers.cloudflare.com/workers/observability/logs/tail-workers/)
+receives every invocation of the Workers that list it: outcome, uncaught
+exceptions, console output (with the exception behind each `console.error`
+argument), the request and response status, and the version that ran.
+`autotel-cloudflare/tail` turns each invocation into an OTLP span and its
+console output into OTLP logs, so autotel-devtools and autotel-mcp group them
+into issues (with source maps and automations) exactly as for an instrumented
+app. A request carrying `traceparent` joins the caller's trace.
+
+```ts
+// tail-worker/src/index.ts
+import { createTailHandler } from 'autotel-cloudflare/tail';
+
+export default {
+  tail: createTailHandler({
+    endpoint: (env) => env.OTLP_ENDPOINT, // posts to /v1/traces and /v1/logs
+    headers: (env) => ({ authorization: `Bearer ${env.OTLP_TOKEN}` }),
+  }),
+};
+```
+
+```jsonc
+// the observed Worker's wrangler.jsonc: no code change
+{ "tail_consumers": [{ "service": "tail-worker" }] }
+```
+
+It also reports logging in a loop (`autotel.LogFlood`) and Durable Object
+alarms firing in a loop (`autotel.RunawayAlarm`). Tail Workers need the Workers
+Paid plan in production. Under `wrangler dev` (run both with
+`wrangler dev -c app/wrangler.jsonc -c tail/wrangler.jsonc`), wrangler's error
+middleware turns an uncaught exception into a plain 500 before the tail sees it
+and events carry no script name, so pass `serviceName`; deployed, the
+exception and the Worker's name arrive as-is. What the tail cannot see are
+attributes set inside the Worker (`user.id` and the like): add those with the
+SDK or Cloudflare's `tracing.getActiveSpan()`.
+
 ## Installation
 
 ```bash

package/dist/actors.d.ts

@@ -120,7 +120,7 @@ type ActorEnv = UnknownRecord;
  * @param config - Configuration (static object or function)
  * @returns Instrumented Actor class
  */
-declare function instrumentActor<C extends ActorConstructor>(actorClass: C, config: ActorConfig | ((env: ActorEnv, trigger?: ActorPayload) => ActorConfig)): C;
+export declare function instrumentActor<C extends ActorConstructor>(actorClass: C, config: ActorConfig | ((env: ActorEnv, trigger?: ActorPayload) => ActorConfig)): C;
 //#endregion
 //#region src/actors/traced-handler.d.ts
 /**
@@ -162,7 +162,7 @@ interface WorkerHandler<E = unknown> {
  * @param config - Configuration (static object or function)
  * @returns A Worker handler with full tracing
  */
-declare function tracedHandler<E, A extends ActorLike>(actorClass: ActorConstructor<A> & {
+export declare function tracedHandler<E, A extends ActorLike>(actorClass: ActorConstructor<A> & {
   nameFromRequest?(request: Request): Promise<string | undefined>;
   configuration?(request: Request): {
     locationHint?: DurableObjectLocationHint;
@@ -186,7 +186,7 @@ declare function tracedHandler<E, A extends ActorLike>(actorClass: ActorConstruc
  * }))
  * ```
  */
-declare function wrapHandler<E>(originalHandler: WorkerHandler<E>, config: ActorConfig | ((env: E, trigger?: unknown) => ActorConfig)): WorkerHandler<E>;
+export declare function wrapHandler<E>(originalHandler: WorkerHandler<E>, config: ActorConfig | ((env: E, trigger?: unknown) => ActorConfig)): WorkerHandler<E>;
 //#endregion
 //#region src/actors/storage.d.ts
 /**
@@ -196,7 +196,7 @@ declare function wrapHandler<E>(originalHandler: WorkerHandler<E>, config: Actor
  * - SQL query operations
  * - Key-value operations (if available)
  */
-declare function instrumentActorStorage(storage: unknown, actorInstance: ActorLike, actorClass: object): unknown;
+export declare function instrumentActorStorage(storage: unknown, actorInstance: ActorLike, actorClass: object): unknown;
 //#endregion
 //#region src/actors/alarms.d.ts
 /**
@@ -208,7 +208,7 @@ declare function instrumentActorStorage(storage: unknown, actorInstance: ActorLi
  * - cancel: Cancel an alarm
  * - cancelAll: Cancel all alarms
  */
-declare function instrumentActorAlarms(alarms: unknown, actorInstance: ActorLike, actorClass: object): unknown;
+export declare function instrumentActorAlarms(alarms: unknown, actorInstance: ActorLike, actorClass: object): unknown;
 //#endregion
 //#region src/actors/sockets.d.ts
 /**
@@ -219,6 +219,6 @@ declare function instrumentActorAlarms(alarms: unknown, actorInstance: ActorLike
  * - broadcast: Send message to all connected sockets
  * - send: Send message to a specific socket
  */
-declare function instrumentActorSockets(sockets: unknown, actorInstance: ActorLike, actorClass: object): unknown;
+export declare function instrumentActorSockets(sockets: unknown, actorInstance: ActorLike, actorClass: object): unknown;
 //#endregion
-export { type ActorConfig, type ActorInstrumentationOptions, type ActorLifecycle, instrumentActor, instrumentActorAlarms, instrumentActorSockets, instrumentActorStorage, tracedHandler, wrapHandler };
+export type { ActorConfig, ActorInstrumentationOptions, ActorLifecycle };

package/dist/agents.d.ts

@@ -362,7 +362,7 @@ interface ObservabilityChannel<TEvent extends ObservabilityEvent = Observability
   name: string;
   publish(event: TEvent): void;
 }
-declare const channels: {
+export declare const channels: {
   readonly state: ObservabilityChannel<BaseEvent<"state:update">>;
   readonly rpc: ObservabilityChannel<BaseEvent<"rpc", {
     method: string;
@@ -371,99 +371,99 @@ declare const channels: {
     method: string;
     error: string;
   }>>;
-  readonly message: ObservabilityChannel<BaseEvent<"message:request"> | BaseEvent<"message:response"> | BaseEvent<"message:clear"> | BaseEvent<"message:cancel", {
+  readonly message: ObservabilityChannel<BaseEvent<"message:clear"> | BaseEvent<"message:request"> | BaseEvent<"message:response"> | BaseEvent<"message:cancel", {
     requestId: string;
   }> | BaseEvent<"message:error", {
     error: string;
-  }> | BaseEvent<"tool:result", {
-    toolCallId: string;
-    toolName: string;
-  }> | BaseEvent<"tool:approval", {
-    toolCallId: string;
-    approved: boolean;
   }> | BaseEvent<"submission:create", {
     submissionId: string;
     requestId?: string;
     idempotencyKey?: string;
-  }> | BaseEvent<"submission:status", {
-    submissionId: string;
-    requestId?: string;
-    status: string;
   }> | BaseEvent<"submission:error", {
     submissionId: string;
     requestId?: string;
     error: string;
+  }> | BaseEvent<"submission:status", {
+    submissionId: string;
+    requestId?: string;
+    status: string;
+  }> | BaseEvent<"tool:approval", {
+    toolCallId: string;
+    approved: boolean;
+  }> | BaseEvent<"tool:result", {
+    toolCallId: string;
+    toolName: string;
   }>>;
-  readonly chat: ObservabilityChannel<BaseEvent<"chat:request:failed", {
+  readonly chat: ObservabilityChannel<BaseEvent<"chat:context:compacted", {
+    reason: 'proactive' | 'reactive';
+    shortened: boolean;
     requestId?: string;
-    stage: "parse" | "persist" | "turn" | "stream" | "recovery" | "transcript";
-    messagesPersisted?: boolean;
+    attempt?: number;
+  }> | BaseEvent<"chat:hydration:windowed", {
+    totalContentBytes: number;
+    budgetBytes: number;
+    hydratedMessages: number;
+  }> | BaseEvent<"chat:media:evicted", {
+    messages: number;
+    parts: number;
+    bytes: number;
+    externalizedBytes: number;
+  }> | BaseEvent<"chat:onstart:degraded", {
+    step: 'transcript-hydration' | 'scheduled-task-reconcile' | 'durable-work-recovery';
     error: string;
-  }> | BaseEvent<"chat:recovery:detected", {
+  }> | BaseEvent<"chat:recovery:attempt", {
     incidentId: string;
     requestId: string;
     attempt: number;
     maxAttempts: number;
-    recoveryKind: "retry" | "continue";
-  }> | BaseEvent<"chat:recovery:scheduled", {
+    recoveryKind: 'retry' | 'continue';
+  }> | BaseEvent<"chat:recovery:completed", {
     incidentId: string;
     requestId: string;
     attempt: number;
     maxAttempts: number;
-    recoveryKind: "retry" | "continue";
-  }> | BaseEvent<"chat:recovery:attempt", {
+    recoveryKind: 'retry' | 'continue';
+  }> | BaseEvent<"chat:recovery:detected", {
     incidentId: string;
     requestId: string;
     attempt: number;
     maxAttempts: number;
-    recoveryKind: "retry" | "continue";
-  }> | BaseEvent<"chat:recovery:completed", {
+    recoveryKind: 'retry' | 'continue';
+  }> | BaseEvent<"chat:recovery:exhausted", {
     incidentId: string;
     requestId: string;
     attempt: number;
     maxAttempts: number;
-    recoveryKind: "retry" | "continue";
-  }> | BaseEvent<"chat:recovery:skipped", {
+    recoveryKind: 'retry' | 'continue';
+    reason: string;
+  }> | BaseEvent<"chat:recovery:failed", {
     incidentId: string;
     requestId: string;
     attempt: number;
     maxAttempts: number;
-    recoveryKind: "retry" | "continue";
+    recoveryKind: 'retry' | 'continue';
     reason?: string;
-  }> | BaseEvent<"chat:recovery:exhausted", {
+  }> | BaseEvent<"chat:recovery:scheduled", {
     incidentId: string;
     requestId: string;
     attempt: number;
     maxAttempts: number;
-    recoveryKind: "retry" | "continue";
-    reason: string;
-  }> | BaseEvent<"chat:recovery:failed", {
+    recoveryKind: 'retry' | 'continue';
+  }> | BaseEvent<"chat:recovery:skipped", {
     incidentId: string;
     requestId: string;
     attempt: number;
     maxAttempts: number;
-    recoveryKind: "retry" | "continue";
+    recoveryKind: 'retry' | 'continue';
     reason?: string;
-  }> | BaseEvent<"chat:onstart:degraded", {
-    step: "transcript-hydration" | "scheduled-task-reconcile" | "durable-work-recovery";
+  }> | BaseEvent<"chat:request:failed", {
+    requestId?: string;
+    stage: 'parse' | 'persist' | 'turn' | 'stream' | 'recovery' | 'transcript';
+    messagesPersisted?: boolean;
     error: string;
-  }> | BaseEvent<"chat:hydration:windowed", {
-    totalContentBytes: number;
-    budgetBytes: number;
-    hydratedMessages: number;
-  }> | BaseEvent<"chat:media:evicted", {
-    messages: number;
-    parts: number;
-    bytes: number;
-    externalizedBytes: number;
   }> | BaseEvent<"chat:stream:stalled", {
     requestId: string;
     timeoutMs: number;
-  }> | BaseEvent<"chat:context:compacted", {
-    reason: "proactive" | "reactive";
-    shortened: boolean;
-    requestId?: string;
-    attempt?: number;
   }>>;
   readonly transcript: ObservabilityChannel<BaseEvent<"chat:transcript:repaired", {
     requestId?: string;
@@ -471,116 +471,116 @@ declare const channels: {
     normalizedInputs: number;
     toolCallIds?: string[];
   }>>;
-  readonly fiber: ObservabilityChannel<BaseEvent<"fiber:run:started", {
+  readonly fiber: ObservabilityChannel<BaseEvent<"fiber:recovery:attempt", {
     fiberId: string;
     fiberName: string;
     managed?: boolean;
-  }> | BaseEvent<"fiber:run:completed", {
+    recoveryReason: 'interrupted';
+  }> | BaseEvent<"fiber:recovery:detected", {
     fiberId: string;
     fiberName: string;
     elapsedMs?: number;
     managed?: boolean;
-  }> | BaseEvent<"fiber:run:failed", {
+    recoveryReason: 'interrupted';
+  }> | BaseEvent<"fiber:recovery:failed", {
     fiberId: string;
     fiberName: string;
     error: string;
     elapsedMs?: number;
-    managed?: boolean;
-  }> | BaseEvent<"fiber:run:interrupted", {
+    reason?: string;
+  }> | BaseEvent<"fiber:recovery:handled", {
     fiberId: string;
     fiberName: string;
+    status?: string;
     elapsedMs?: number;
     managed?: boolean;
-    recoveryReason: "interrupted";
-  }> | BaseEvent<"fiber:recovery:detected", {
+  }> | BaseEvent<"fiber:recovery:skipped", {
     fiberId: string;
     fiberName: string;
+    reason: string;
     elapsedMs?: number;
     managed?: boolean;
-    recoveryReason: "interrupted";
-  }> | BaseEvent<"fiber:recovery:attempt", {
+  }> | BaseEvent<"fiber:run:completed", {
     fiberId: string;
     fiberName: string;
+    elapsedMs?: number;
     managed?: boolean;
-    recoveryReason: "interrupted";
-  }> | BaseEvent<"fiber:recovery:handled", {
+  }> | BaseEvent<"fiber:run:failed", {
     fiberId: string;
     fiberName: string;
-    status?: string;
+    error: string;
     elapsedMs?: number;
     managed?: boolean;
-  }> | BaseEvent<"fiber:recovery:skipped", {
+  }> | BaseEvent<"fiber:run:interrupted", {
     fiberId: string;
     fiberName: string;
-    reason: string;
     elapsedMs?: number;
     managed?: boolean;
-  }> | BaseEvent<"fiber:recovery:failed", {
+    recoveryReason: 'interrupted';
+  }> | BaseEvent<"fiber:run:started", {
     fiberId: string;
     fiberName: string;
-    error: string;
-    elapsedMs?: number;
-    reason?: string;
+    managed?: boolean;
   }>>;
   readonly agentTool: ObservabilityChannel<BaseEvent<"agent_tool:recovery:begin", {
     runCount: number;
     totalTimeoutMs?: number;
-  }> | BaseEvent<"agent_tool:recovery:row", {
-    runId: string;
-    agentType: string;
-    status: string;
-    reason?: string;
+  }> | BaseEvent<"agent_tool:recovery:complete", {
+    runCount: number;
     elapsedMs?: number;
   }> | BaseEvent<"agent_tool:recovery:deadline", {
     runId: string;
     agentType: string;
     elapsedMs?: number;
+  }> | BaseEvent<"agent_tool:recovery:failed", {
+    error: string;
   }> | BaseEvent<"agent_tool:recovery:reattach", {
     runId: string;
     agentType: string;
     budgetMs: number;
-  }> | BaseEvent<"agent_tool:recovery:complete", {
-    runCount: number;
+  }> | BaseEvent<"agent_tool:recovery:row", {
+    runId: string;
+    agentType: string;
+    status: string;
+    reason?: string;
     elapsedMs?: number;
-  }> | BaseEvent<"agent_tool:recovery:failed", {
-    error: string;
   }>>;
-  readonly schedule: ObservabilityChannel<BaseEvent<"schedule:create", {
-    callback: string;
-    id: string;
-  }> | BaseEvent<"schedule:execute", {
+  readonly schedule: ObservabilityChannel<BaseEvent<"queue:create", {
     callback: string;
     id: string;
-  }> | BaseEvent<"schedule:cancel", {
+  }> | BaseEvent<"queue:error", {
     callback: string;
     id: string;
-  }> | BaseEvent<"schedule:retry", {
+    error: string;
+    attempts: number;
+  }> | BaseEvent<"queue:retry", {
     callback: string;
     id: string;
     attempt: number;
     maxAttempts: number;
-  }> | BaseEvent<"schedule:error", {
+  }> | BaseEvent<"schedule:cancel", {
+    callback: string;
+    id: string;
+  }> | BaseEvent<"schedule:create", {
     callback: string;
     id: string;
-    error: string;
-    attempts: number;
   }> | BaseEvent<"schedule:duplicate_warning", {
     callback: string;
     count: number;
     type: string;
-  }> | BaseEvent<"queue:create", {
+  }> | BaseEvent<"schedule:error", {
     callback: string;
     id: string;
-  }> | BaseEvent<"queue:retry", {
+    error: string;
+    attempts: number;
+  }> | BaseEvent<"schedule:execute", {
     callback: string;
     id: string;
-    attempt: number;
-    maxAttempts: number;
-  }> | BaseEvent<"queue:error", {
+  }> | BaseEvent<"schedule:retry", {
     callback: string;
     id: string;
-    error: string;
-    attempts: number;
+    attempt: number;
+    maxAttempts: number;
   }>>;
   readonly lifecycle: ObservabilityChannel<BaseEvent<"destroy"> | BaseEvent<"connect", {
     connectionId: string;
@@ -589,28 +589,28 @@ declare const channels: {
     code: number;
     reason: string;
   }>>;
-  readonly workflow: ObservabilityChannel<BaseEvent<"workflow:start", {
+  readonly workflow: ObservabilityChannel<BaseEvent<"workflow:approved", {
     workflowId: string;
-    workflowName?: string;
+    reason?: string;
   }> | BaseEvent<"workflow:event", {
     workflowId: string;
     eventType?: string;
-  }> | BaseEvent<"workflow:approved", {
+  }> | BaseEvent<"workflow:paused", {
     workflowId: string;
-    reason?: string;
+    workflowName?: string;
   }> | BaseEvent<"workflow:rejected", {
     workflowId: string;
     reason?: string;
-  }> | BaseEvent<"workflow:terminated", {
+  }> | BaseEvent<"workflow:restarted", {
     workflowId: string;
     workflowName?: string;
-  }> | BaseEvent<"workflow:paused", {
+  }> | BaseEvent<"workflow:resumed", {
     workflowId: string;
     workflowName?: string;
-  }> | BaseEvent<"workflow:resumed", {
+  }> | BaseEvent<"workflow:start", {
     workflowId: string;
     workflowName?: string;
-  }> | BaseEvent<"workflow:restarted", {
+  }> | BaseEvent<"workflow:terminated", {
     workflowId: string;
     workflowName?: string;
   }>>;
@@ -629,8 +629,8 @@ declare const channels: {
     subject: string;
   }>>;
 };
-declare const genericObservability: Observability;
-declare function subscribe<K extends keyof ChannelEventMap>(channelKey: K, callback: (event: ChannelEventMap[K]) => void): () => void;
+export declare const genericObservability: Observability;
+export declare function subscribe<K extends keyof ChannelEventMap>(channelKey: K, callback: (event: ChannelEventMap[K]) => void): () => void;
 //#endregion
 //#region src/agents/types.d.ts
 type ObservabilityExecutionContext = DurableObjectState | ExecutionContext;
@@ -681,7 +681,7 @@ interface AgentSpanAttributes {
  * Implements the Agents SDK Observability interface and converts
  * events into OpenTelemetry spans.
  */
-declare class OtelObservability implements Observability {
+export declare class OtelObservability implements Observability {
   private readonly config;
   private readonly options;
   private initialized;
@@ -689,7 +689,7 @@ declare class OtelObservability implements Observability {
   private initialize;
   emit(event: ObservabilityEvent, ctx?: ObservabilityExecutionContext): void;
 }
-declare function createOtelObservability(config: OtelObservabilityConfig): OtelObservability;
-declare function createOtelObservabilityFromEnv(env: UnknownRecord, options?: AgentInstrumentationOptions): OtelObservability;
+export declare function createOtelObservability(config: OtelObservabilityConfig): OtelObservability;
+export declare function createOtelObservabilityFromEnv(env: UnknownRecord, options?: AgentInstrumentationOptions): OtelObservability;
 //#endregion
-export { type AgentInstrumentationOptions, type AgentObservabilityEvent, type AgentSpanAttributes, type BaseEvent, type ChannelEventMap, type MCPObservabilityEvent, type Observability, type ObservabilityEvent, OtelObservability, type OtelObservabilityConfig, channels, createOtelObservability, createOtelObservabilityFromEnv, genericObservability, subscribe };
+export type { AgentInstrumentationOptions, AgentObservabilityEvent, AgentSpanAttributes, BaseEvent, ChannelEventMap, MCPObservabilityEvent, Observability, ObservabilityEvent, OtelObservabilityConfig };

package/dist/{handlers-BRfAgfP7.d.ts → handlers-CEAD5hVy.d.ts}

@@ -1,5 +1,7 @@
 import { ConfigurationOption } from "autotel-edge";
 //#region src/handlers/durable-objects.d.ts
+/** `exception.type` of the alarm-loop signal. */
+declare const RUNAWAY_ALARM_EXCEPTION = "autotel.RunawayAlarm";
 /**
  * Instrument a Durable Object class
  *
@@ -91,4 +93,4 @@ declare function instrumentDO<C extends new (...args: any[]) => any>(doClass: C,
  */
 declare function instrumentWorkflow<C extends new (...args: any[]) => any>(workflowClass: C, workflowName: string, config: ConfigurationOption): C;
 //#endregion
-export { instrumentDO as n, instrumentWorkflow as t };
+export { RUNAWAY_ALARM_EXCEPTION as n, instrumentDO as r, instrumentWorkflow as t };