AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/tail-workers/api.md

Tail Workers API Reference

Handler Signature

export default {
  async tail(
    events: TraceItem[],
    env: Env,
    ctx: ExecutionContext
  ): Promise<void> {
    // Process events
  }
} satisfies ExportedHandler<Env>;

Parameters:

  • events: Array of TraceItem objects (one per producer invocation)
  • env: Bindings (KV, D1, R2, env vars, etc.)
  • ctx: Context with waitUntil() for async work

CRITICAL: Tail handlers don't return values. Use ctx.waitUntil() for async operations.

TraceItem Type

interface TraceItem {
  scriptName: string;           // Producer Worker name
  eventTimestamp: number;        // Epoch milliseconds
  outcome: 'ok' | 'exception' | 'exceededCpu' | 'exceededMemory' 
         | 'canceled' | 'scriptNotFound' | 'responseStreamDisconnected' | 'unknown';
  
  event?: {
    request?: {
      url: string;               // Redacted by default
      method: string;
      headers: Record<string, string>;  // Sensitive headers redacted
      cf?: IncomingRequestCfProperties;
      getUnredacted(): TraceRequest;    // Bypass redaction (use carefully)
    };
    response?: {
      status: number;
    };
  };
  
  logs: Array<{
    timestamp: number;           // Epoch milliseconds
    level: 'debug' | 'info' | 'log' | 'warn' | 'error';
    message: unknown[];          // Args passed to console function
  }>;
  
  exceptions: Array<{
    timestamp: number;           // Epoch milliseconds
    name: string;                // Error type (Error, TypeError, etc.)
    message: string;             // Error description
  }>;
  
  diagnosticsChannelEvents: Array<{
    channel: string;
    message: unknown;
    timestamp: number;           // Epoch milliseconds
  }>;
}

Note: Official SDK uses TraceItem, not TailItem. Use @cloudflare/workers-types for accurate types.

Timestamp Handling

All timestamps are epoch milliseconds, not seconds:

// ✅ CORRECT - use directly with Date
const date = new Date(event.eventTimestamp);

// ❌ WRONG - don't multiply by 1000
const date = new Date(event.eventTimestamp * 1000);

Automatic Redaction

By default, sensitive data is redacted from TraceRequest:

Header Redaction

Headers containing these substrings (case-insensitive):

  • auth, key, secret, token, jwt
  • cookie, set-cookie

Redacted values show as "REDACTED".

URL Redaction

  • Hex IDs: 32+ hex digits → "REDACTED"
  • Base-64 IDs: 21+ chars with 2+ upper, 2+ lower, 2+ digits → "REDACTED"

Bypassing Redaction

export default {
  async tail(events, env, ctx) {
    for (const event of events) {
      // ⚠️ Use with extreme caution
      const unredacted = event.event?.request?.getUnredacted();
      // unredacted.url and unredacted.headers contain raw values
    }
  }
};

Best practices:

  • Only call getUnredacted() when absolutely necessary
  • Never log unredacted sensitive data
  • Implement additional filtering before external transmission
  • Use environment variables for API keys, never hardcode

Type-Safe Handler

interface Env {
  LOGS_KV: KVNamespace;
  ANALYTICS: AnalyticsEngineDataset;
  LOG_ENDPOINT: string;
  API_TOKEN: string;
}

export default {
  async tail(
    events: TraceItem[],
    env: Env,
    ctx: ExecutionContext
  ): Promise<void> {
    const payload = events.map(event => ({
      script: event.scriptName,
      timestamp: event.eventTimestamp,
      outcome: event.outcome,
      url: event.event?.request?.url,
      status: event.event?.response?.status,
    }));
    
    ctx.waitUntil(
      fetch(env.LOG_ENDPOINT, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(payload),
      })
    );
  }
} satisfies ExportedHandler<Env>;

Outcome vs HTTP Status

IMPORTANT: outcome is script execution status, NOT HTTP status.

  • Worker returns 500 → outcome='ok' if script completed successfully
  • Uncaught exception → outcome='exception' regardless of HTTP status
  • CPU limit exceeded → outcome='exceededCpu'
// ✅ Check outcome for script execution status
if (event.outcome === 'exception') {
  // Script threw uncaught exception
}

// ✅ Check HTTP status separately
if (event.event?.response?.status === 500) {
  // HTTP 500 returned (script may have handled error)
}

Serialization Considerations

log.message is unknown[] and may contain non-serializable objects:

// ❌ May fail with circular references or BigInt
JSON.stringify(events);

// ✅ Safe serialization
const safePayload = events.map(event => ({
  ...event,
  logs: event.logs.map(log => ({
    ...log,
    message: log.message.map(m => {
      try {
        return JSON.parse(JSON.stringify(m));
      } catch {
        return String(m);
      }
    })
  }))
}));

Common serialization issues:

  • Circular references in logged objects
  • BigInt values (not JSON-serializable)
  • Functions or symbols in console.log arguments
  • Large objects exceeding body size limits