Cloudflare Integration (Worker)

Ansehn's Cloudflare Worker integration forwards your Cloudflare traffic to Ansehn using a small edge Worker that runs on your domain's routes. It works on every Cloudflare plan (Free, Pro, Business, Enterprise) and delivers data in near real time. Once connected, Ansehn automatically detects AI crawler activity (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Gemini, Google-Extended, and more) and surfaces it in your Server Logs dashboard and Our Pages analytics.

On the Cloudflare Enterprise plan, prefer the code-free Cloudflare Logpush integration. Use a Worker when Logpush isn't available or you want near-real-time delivery.

Which method should I use?

Method	Best for	Setup effort
Manual Upload	One-time analysis, quick checks, any web server	Low — upload a .log/.txt file
AWS CloudFront	Continuous monitoring of CloudFront distributions	Medium — one-time AWS setup
Cloudflare Logpush	Code-free monitoring on Cloudflare Enterprise	Low — configure a Logpush job
Cloudflare Worker (this page)	Continuous monitoring on any Cloudflare plan	Medium — deploy a small Worker
Custom Log API	Continuous, automated monitoring from any system	Medium — point a log drain or script at our endpoint

How it works

Visitor / AI crawler
        │
        ▼
Cloudflare Worker (your routes)  ──►  origin response returned to visitor
        │
        │  Request metadata (JSON over HTTPS, fire-and-forget)
        ▼
https://ingest.ansehn.com/v1/logs/cloudflare_worker
        │
        │  API key auth · AI crawler detection · validation
        ▼
Your Server Logs & Our Pages Analytics

The Worker transparently passes every request through to your origin, then forwards the request metadata to Ansehn on a background task (ctx.waitUntil). Logging never blocks the response, so your visitors are never affected. Ansehn detects AI crawler traffic by User-Agent and stores only the recognized AI crawler rows, tagged as a native Cloudflare source.

Prerequisites

• A Cloudflare account with access to Workers (any plan).

• Your domain proxied through Cloudflare (orange cloud enabled — see Step 5).

• An Ansehn account with an active project for the domain you want to monitor.

• An API key with the logs:ingest scope (see Step 1).

Step-by-step setup

Step 1 — Generate an API key in Ansehn

[!INFO] API key generation is available in your dashboard under Project Settings → API Keys.

1. Navigate to Projects → [Your Project] → Settings → API Keys

2. Click + New API Key

3. Give the key a descriptive name (e.g., Production Cloudflare Worker)

4. Under Scopes, select logs:ingest

5. Under Project, select the project for the domain you want to monitor

6. Click Generate and copy the key immediately — it is only shown once

Your key will look like: ank_a1b2c3d4e5f6...

Step 2 — Create the Worker

1. In the Cloudflare dashboard, go to Workers & Pages → Create application → Start with Hello World!

2. Give it a name (e.g., ansehn-analytics) and click Deploy

3. Click Edit code and replace the contents with the script below

/**
 * Ansehn Server Logs — Cloudflare Worker
 *
 * Transparently proxies every request and forwards request metadata to Ansehn.
 * Logging is fire-and-forget (ctx.waitUntil) so it never adds latency for visitors.
 */
const ANSEHN_ENDPOINT = "https://ingest.ansehn.com/v1/logs/cloudflare_worker";

export default {
  async fetch(request, env, ctx) {
    // Pass the request through untouched; logging never blocks the response.
    const response = await fetch(request);
    ctx.waitUntil(forwardLog(request, response, env));
    return response;
  },
};

async function forwardLog(request, response, env) {
  try {
    const url = new URL(request.url);
    const timestamp = new Date().toISOString();
    const method = request.method;
    const host = request.headers.get("host") || url.hostname;
    const path = url.pathname + url.search;
    const status = response.status;

    // Use Content-Length — never read the response body (keeps large responses fast).
    const bytesSent = Number(response.headers.get("content-length") || 0);
    const cfRay = request.headers.get("cf-ray") || "";

    const log = {
      timestamp,
      method,
      host,
      path,
      status_code: status,
      ip: request.headers.get("cf-connecting-ip") || "",
      user_agent: request.headers.get("user-agent") || "",
      referer: request.headers.get("referer") || "-",
      bytes_sent: bytesSent,
    };

    // Stable idempotency key so re-execution / retries never double-count.
    // CF-Ray uniquely identifies the request at Cloudflare's edge and is stable
    // across re-execution, so we key on it plus deterministic request fields.
    // Only when CF-Ray is somehow absent do we fall back to the runtime timestamp.
    const keyMaterial = cfRay
      ? [cfRay, method, host, path, status].join("|")
      : [timestamp, method, host, path, status, bytesSent].join("|");
    const idempotencyKey = await sha256Hex(keyMaterial);

    await fetch(ANSEHN_ENDPOINT, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Ansehn-Api-Key": env.ANSEHN_API_KEY,
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify({ logs: [log] }),
    });
  } catch (err) {
    // Swallow errors — logging must never affect the visitor's request.
    console.error("Ansehn log forward failed:", err);
  }
}

async function sha256Hex(input) {
  const data = new TextEncoder().encode(input);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return [...new Uint8Array(digest)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

Step 3 — Add your API key as a secret

1. Open the Worker's Settings → Variables and secrets

2. Click Add, choose Secret

3. Set the name to ANSEHN_API_KEY and the value to your ank_... key

[!WARNING] Always store the key as a Secret, never as a plain-text variable and never hard-coded in the script. Rotate it periodically from Project Settings → API Keys.

Step 4 — Run the Worker on your domain

1. Open the Worker's Settings → Domains & Routes → Add route

2. Add a route for your site, e.g., example.com/*

3. Select this Worker and save

The Worker transparently passes all traffic through while forwarding request metadata to Ansehn.

Step 5 — Verify the Cloudflare proxy is enabled

Worker routes only intercept traffic that flows through Cloudflare.

1. Go to your Cloudflare dashboard → DNS → Records

2. Confirm the Proxy status shows the orange cloud ("Proxied") for your A/AAAA/CNAME records

[!WARNING] If the proxy is off (gray cloud / "DNS only"), requests bypass the Worker entirely and no logs are sent.

What gets stored

Ansehn stores only recognized AI crawler rows, tagged with the source cloudflare_worker. You can safely forward all requests — non-AI-crawler traffic is detected and dropped before it is ever persisted.

The Worker sends a stable Idempotency-Key (derived from CF-Ray) so retries and re-execution never double-count.

Response status codes

Traffic volume and rate limits

The Worker sends one request per pageview. The Worker ingest endpoint accepts up to roughly 20 requests per second per API key.

[!TIP] High-traffic sites should use Cloudflare Logpush (Enterprise) — it batches logs and has no per-request limit. If you exceed the Worker limit you'll receive 429 responses, and those logs are not stored (your visitors are never affected). For very high volume on non-Enterprise plans, contact us about advanced Worker batching.

Verification

1. Visit a page on your site (or wait for normal AI crawler traffic).

2. Data appears in near real time — allow a minute or two.

3. Open your Ansehn Server Logs dashboard — activity appears under Daily Visits, Top Pages, and Top Crawlers.

4. The connection status indicator next to the tab bar shows whether logs are flowing and when the last ingest occurred.

Frequently asked questions

Troubleshooting

Need help?

If you run into any issues during setup or have questions about the integration, reach out to us at [email protected] and mention "Cloudflare Worker" in the subject line. We're happy to help you wire it up.