> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/docs/de/insights/onsite/traffic/cloudflare-worker-agent-analytics.md).

# Cloudflare Worker

Diese Anleitung führt dich durch die Konfiguration eines Cloudflare Workers, um Anforderungsprotokolle für Agent Analytics in AirOps zu streamen.

Dieser Leitfaden führt dich durch die Konfiguration von Cloudflare, um über **Workers**. Sobald die Verbindung hergestellt ist, analysiert AirOps deinen Traffic automatisch, klassifiziert Besuche von KI-Bots (ChatGPT, Claude, Perplexity, Google und mehr) und zeigt Einblicke in deinem Agent-Analytics-Dashboard an.

{% hint style="info" %}
**Logpush oder Worker?** Wenn du einen Cloudflare-Enterprise-Tarif hast, empfehlen wir [Cloudflare Logpush](/docs/de/insights/onsite/traffic/cloudflare-logpush-agent-analytics.md) stattdessen. Es ist die einfachste Option und erfordert keinen Code. Verwende Workers, wenn Logpush nicht verfügbar ist, z. B. bei Nicht-Enterprise-Tarifen.
{% endhint %}

***

## Voraussetzungen

* Ein aktives **AirOps** Konto mit aktiviertem Agent Analytics
* Ein **Cloudflare** Konto, das deine Website bereitstellt und entweder auf der Enterprise-Stufe ist oder das Workers-Paid-Add-on hat
* Ein Entwicklungsrechner mit installiertem Node.js
* Dein **Workspace-API-Schlüssel**, verfügbar in `Einstellungen → Workspace`
* Dein **Brand-Kit-ID**, verfügbar in der URL durch Navigieren zu `Kontext → Brand Kits`. Die URL hat die Form `https://app.airops.com/<YOUR_WORKSPACE_SLUG>/data/brand_kits/<YOUR_BRAND_KIT_ID>`

***

## Workers-Batching

Die Batching-Integration ist der **empfohlene** Ansatz für die meisten Websites. Sie verwendet eine Cloudflare-Queue, um Protokollereignisse pro Anfrage zu puffern und sie in Batches an AirOps weiterzuleiten, sodass du selbst bei hohem Traffic deutlich unter dem AirOps-Ratenlimit bleibst.

### Schritt 1: Initialisiere den Cloudflare Worker

Für diesen Prozess verwenden wir Version `2.68.2` der Cloudflare CLI. Andere Minor-Versionen funktionieren möglicherweise, aber es kann Unterschiede in den CLI-Eingabeaufforderungen geben.

{% hint style="info" %}
Je nach Entwicklungsumgebung musst du möglicherweise die folgenden Node-Pakete manuell installieren: `node-addon-api`, `node-gyp`und `sharp`.
{% endhint %}

```bash
npm create cloudflare@2.68.2
```

Setze das Verzeichnis auf `airops-log-collector`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-d3a82ed25616b153b6eb6c41dda860f1162cc66f%2Fcloudflare-workers-01-directory.png?alt=media" alt=""><figcaption></figcaption></figure>

Setze das Startbeispiel auf `Hello-World-Beispiel`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-6a28ae22cd704f476ba29a5fa1df7a42b9a99b03%2Fcloudflare-workers-02-project-example.png?alt=media" alt=""><figcaption></figcaption></figure>

Setze die Vorlage auf `Queue-Consumer- und -Producer-Worker`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-d40a4b5afebeebd3322857bbad322cec2f01addb%2Fcloudflare-workers-03-batch-template.png?alt=media" alt=""><figcaption></figcaption></figure>

Setze die Sprache auf `TypeScript`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-06e645b730047ef5c67a980815390d43a54effba%2Fcloudflare-workers-04-language.png?alt=media" alt=""><figcaption></figcaption></figure>

Wähle **Ja** für die Verwendung von Git zur Versionskontrolle.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-9bbaf28aa13bf1c613af4e0628740b1d2a86fe94%2Fcloudflare-workers-05-git.png?alt=media" alt=""><figcaption></figcaption></figure>

Wähle **Nein** für das Deployen deiner Anwendung (das erledigen wir später).

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-bdb363dcdf8ddde3f76b8bcc194361f9b46905d1%2Fcloudflare-workers-06-deploy.png?alt=media" alt=""><figcaption></figcaption></figure>

### Schritt 2: Konfiguriere die Cloudflare-Worker-Route

Bearbeite die `wrangler.json` Datei und konfiguriere dein `Muster`, `zone_name`, Queue-Bindings und `AIROPS_API_URL`.

{% hint style="info" %}
Die `Muster` sollte deine tatsächliche Domain oder Zielseiten-URL sein, während die `zone_name` die kanonische Domain sein sollte. Wenn deine Zielseite beispielsweise `https://blog.example.com`, dann sollte die `Muster` sein `blog.example.com` und deine `zone_name` sein `example.com`.
{% endhint %}

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "airops-log-collector",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-18",
  "observability": {
    "enabled": true
  },
  "queues": {
    "consumers": [
      {
        "queue": "airops-log-collector-queue",
        "max_batch_size": 1000,
        "max_batch_timeout": 60
      }
    ],
    "producers": [
      {
        "binding": "AIROPS_LOG_COLLECTOR_QUEUE",
        "queue": "airops-log-collector-queue"
      }
    ]
  },
  "upload_source_maps": true,
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "route": {
    "pattern": "example.com/*",
    "zone_name": "example.com"
  },
  "vars": {
    "AIROPS_API_URL": "https://ingest.airops.com/api/v1/cloudflare-worker/<YOUR_BRAND_KIT_ID>/ingest"
  }
}
```

### Schritt 3: Konfiguriere den Cloudflare-Worker-Code

Ersetze den Inhalt der `src/index.ts` Datei durch den folgenden Code.

```typescript
export interface Env {
  AIROPS_API_URL: string;
  AIROPS_API_KEY: string;
  AIROPS_LOG_COLLECTOR_QUEUE: Queue;
}

export default {
  // Der Queue-Producer wird bei jedem Seitenaufruf aufgerufen und speichert die Anfragemetadaten in der Queue
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Speichere den Zeitpunkt, zu dem die Anfrage gestartet wurde
    const startTime = Date.now();

    // Sende die Anfrage
    const response = await fetch(request);

    // Klone die Antwort, damit sie erneut verwendet werden kann
    const responseClone = response.clone();

    ctx.waitUntil(handleRequest(startTime, request, responseClone, env));
    return response;
  },

  // Der Queue-Consumer liest Nachrichten aus der Queue und sendet regelmäßige Batches an AirOps
  async queue(batch: MessageBatch<string>, env: Env): Promise<void> {
    const body = batch.messages.map(m => m.body).join('\n');

    await fetch(env.AIROPS_API_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': env.AIROPS_API_KEY,
      },
      body,
    }).catch(error => console.error('Senden der Logs fehlgeschlagen:', error))
  }
} satisfies ExportedHandler<Env, string>;

async function handleRequest(startTime: number, request: Request, response: Response, env: Env) {
  const logData = {
    request_start_time: startTime,
    request_end_time: Date.now(),
    status_code: response.status,
    response_bytes: response.bytes.length,
    method: request.method,
    url: request.url,
    user_agent: request.headers.get('user-agent'),
    referer: request.headers.get('referer'),
  };

  await env.AIROPS_LOG_COLLECTOR_QUEUE.send(JSON.stringify(logData));
}
```

### Schritt 4: Konfiguriere den AirOps-API-Schlüssel

{% hint style="info" %}
Dein `AIROPS_API_KEY` sollte auf denselben Wert wie dein Workspace-API-Schlüssel gesetzt werden, verfügbar in `Einstellungen → Workspace`.
{% endhint %}

```bash
# Bei Cloudflare anmelden
npx wrangler login

# Den API-Schlüssel konfigurieren
npx wrangler secret put AIROPS_API_KEY
```

### Schritt 5: Erstelle die Cloudflare-Queue

```bash
npx wrangler queues create airops-log-collector-queue
```

### Schritt 6: Deploye den Cloudflare Worker

```bash
# Den Cloudflare Worker deployen
npx wrangler deploy
```

### Schritt 7: Überprüfe die Verbindung

Nach dem Deployen des Cloudflare Workers sollten innerhalb von **2–5 Minuten**.

1. Erzeuge etwas Traffic auf deiner Website.
2. In deinem **AirOps-Dashboard**, navigiere zu **Agent Analytics**. Traffic-Daten sollten kurz darauf erscheinen.

***

## Workers-Alternative

Der alternative Integrationsansatz sendet bei jedem Seitenaufruf ein Ereignis an AirOps. Er eignet sich am besten für Websites mit weniger Seitenaufrufen, um ein Überschreiten der Ratenlimits zu vermeiden, und wird daher für die meisten Websites nicht empfohlen.

### Schritt 1: Initialisiere den Cloudflare Worker

Für diesen Prozess verwenden wir Version `2.68.2` der Cloudflare CLI. Andere Minor-Versionen funktionieren möglicherweise, aber es kann Unterschiede in den CLI-Eingabeaufforderungen geben.

{% hint style="info" %}
Je nach Entwicklungsumgebung musst du möglicherweise die folgenden Node-Pakete manuell installieren: `node-addon-api`, `node-gyp`und `sharp`.
{% endhint %}

```bash
npm create cloudflare@2.68.2
```

Setze das Verzeichnis auf `airops-log-collector`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-d3a82ed25616b153b6eb6c41dda860f1162cc66f%2Fcloudflare-workers-01-directory.png?alt=media" alt=""><figcaption></figcaption></figure>

Setze das Startbeispiel auf `Hello-World-Beispiel`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-6a28ae22cd704f476ba29a5fa1df7a42b9a99b03%2Fcloudflare-workers-02-project-example.png?alt=media" alt=""><figcaption></figcaption></figure>

Setze die Vorlage auf `Nur Worker`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-47978f6b8874aeb95c2b8401bcc062ab98c15ee9%2Fcloudflare-workers-03-alternate-template.png?alt=media" alt=""><figcaption></figcaption></figure>

Setze die Sprache auf `TypeScript`.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-06e645b730047ef5c67a980815390d43a54effba%2Fcloudflare-workers-04-language.png?alt=media" alt=""><figcaption></figcaption></figure>

Wähle **Ja** für die Verwendung von Git zur Versionskontrolle.

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-9bbaf28aa13bf1c613af4e0628740b1d2a86fe94%2Fcloudflare-workers-05-git.png?alt=media" alt=""><figcaption></figcaption></figure>

Wähle **Nein** für das Deployen deiner Anwendung (das erledigen wir später).

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-bdb363dcdf8ddde3f76b8bcc194361f9b46905d1%2Fcloudflare-workers-06-deploy.png?alt=media" alt=""><figcaption></figcaption></figure>

### Schritt 2: Konfiguriere die Cloudflare-Worker-Route

Bearbeite die `wrangler.json` Datei und konfiguriere dein `Muster`, `zone_name`und `AIROPS_API_URL`.

{% hint style="info" %}
Die `Muster` sollte deine tatsächliche Domain oder Zielseiten-URL sein, während die `zone_name` die kanonische Domain sein sollte. Wenn deine Zielseite beispielsweise `https://blog.example.com`, dann sollte die `Muster` sein `blog.example.com` und deine `zone_name` sein `example.com`.
{% endhint %}

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "airops-log-collector",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-18",
  "observability": {
    "enabled": true
  },
  "upload_source_maps": true,
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "route": {
    "pattern": "example.com/*",
    "zone_name": "example.com"
  },
  "vars": {
    "AIROPS_API_URL": "https://ingest.airops.com/api/v1/cloudflare-worker/<YOUR_BRAND_KIT_ID>/ingest"
  }
}
```

### Schritt 3: Konfiguriere den Cloudflare-Worker-Code

Ersetze den Inhalt der `src/index.ts` Datei durch den folgenden Code.

```typescript
export interface Env {
  AIROPS_API_URL: string;
  AIROPS_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Speichere den Zeitpunkt, zu dem die Anfrage gestartet wurde
    const startTime = Date.now();

    // Sende die Anfrage
    const response = await fetch(request);

    // Klone die Antwort, damit sie erneut verwendet werden kann
    const responseClone = response.clone();

    ctx.waitUntil(handleRequest(startTime, request, responseClone, env));
    return response;
  }
} satisfies ExportedHandler<Env>;

async function handleRequest(startTime: number, request: Request, response: Response, env: Env) {
	const logData = {
		request_start_time: startTime,
		request_end_time: Date.now(),
		status_code: response.status,
		response_bytes: response.bytes.length,
		method: request.method,
		url: request.url,
		user_agent: request.headers.get('user-agent'),
		referer: request.headers.get('referer'),
    }

  await fetch(env.AIROPS_API_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': env.AIROPS_API_KEY
    },
    body: JSON.stringify(logData)
  }).catch(error => console.error('Senden der Logs fehlgeschlagen:', error))
}
```

### Schritt 4: Konfiguriere den AirOps-API-Schlüssel

{% hint style="info" %}
Dein `AIROPS_API_KEY` sollte auf denselben Wert wie dein Workspace-API-Schlüssel gesetzt werden, verfügbar in `Einstellungen → Workspace`.
{% endhint %}

```bash
# Bei Cloudflare anmelden
npx wrangler login

# Den API-Schlüssel konfigurieren
npx wrangler secret put AIROPS_API_KEY
```

### Schritt 5: Deploye den Cloudflare Worker

```bash
# Den Cloudflare Worker deployen
npx wrangler deploy
```

### Schritt 6: Überprüfe die Verbindung

Nach dem Deployen des Cloudflare Workers sollten innerhalb von **2–5 Minuten**.

1. Erzeuge etwas Traffic auf deiner Website.
2. In deinem **AirOps-Dashboard**, navigiere zu **Agent Analytics**. Traffic-Daten sollten kurz darauf erscheinen.

***

## Ratenlimits

Der AirOps-Ingestor erzwingt ein Ratenlimit von **5 Anfragen pro Minute und API-Schlüssel**. Der Echtzeit-Worker sendet eine Anfrage pro Seitenaufruf, daher eignet sich diese Option am besten für Websites mit geringerem Traffic. Für Websites mit hohem Traffic solltest du Anfragen bündeln oder eine gepufferte Ingestions-Option verwenden.

***

## Was AirOps verfolgt

Sobald die Verbindung hergestellt ist, führt AirOps automatisch Folgendes aus:

* **Nimmt alle Cloudflare-Anfragen auf**: Seitenaufrufe, Assets und API-Aufrufe
* **Klassifiziert KI-Bot-Traffic**: erkennt Besuche von ChatGPT, Claude, Google, Perplexity, Meta, Apple, Bing, Bytedance, Common Crawl und anderen
* **Kategorisiert Crawling-Verhalten**: unterscheidet zwischen KI-Trainings-Crawlern, KI-Suchabrufen, KI-Indexierung und vom Nutzer initiiertem KI-Browsing
* **Zeigt Analysen an**: Traffic-Aufschlüsselungen, Bot-zu-Mensch-Verhältnisse und Crawl-Trends in deinem Dashboard


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/docs/de/insights/onsite/traffic/cloudflare-worker-agent-analytics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.