> 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.

Diese Anleitung führt Sie durch die Konfiguration von Cloudflare, damit es per **Workers**. Sobald die Verbindung hergestellt ist, analysiert AirOps Ihren Traffic automatisch, klassifiziert KI-Bot-Besuche (ChatGPT, Claude, Perplexity, Google und mehr) und stellt Erkenntnisse in Ihrem Agent-Analytics-Dashboard bereit.

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

***

## Voraussetzungen

* Ein aktives **AirOps** Konto mit aktiviertem Agent Analytics
* Ein **Cloudflare** Konto, das Ihre Website bereitstellt und entweder auf der Enterprise-Stufe ist oder das Workers Paid Add-on hat
* Ein Entwicklungsrechner mit installiertem Node.js
* Ihre **Workspace-API-Schlüssel**, verfügbar in `Einstellungen → Workspace`
* Ihre **Brand-Kit-ID**, verfügbar in der URL, indem Sie zu `Kontext → Brand Kits`. Die URL hat das Format `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 zwischenzuspeichern und sie in Batches an AirOps zu senden, sodass Sie selbst bei hohem Traffic deutlich unter dem AirOps-Ratenlimit bleiben.

### Schritt 1: Initialisieren Sie den Cloudflare Worker

Für diesen Vorgang verwenden wir Version `2.68.2` der Cloudflare-CLI. Andere Nebenversionen können funktionieren, aber es kann Unterschiede bei den CLI-Eingabeaufforderungen geben.

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

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

Setzen Sie 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>

Setzen Sie 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>

Setzen Sie die Vorlage auf `Worker für Queue-Consumer und -Producer`.

<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>

Setzen Sie 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ählen Sie **Ja** zum Verwenden von Git für die Versionsverwaltung.

<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ählen Sie **Nein** zum Bereitstellen Ihrer Anwendung (wir werden dies später tun).

<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: Konfigurieren Sie die Cloudflare-Worker-Route

Bearbeiten Sie die `wrangler.json` Datei und konfigurieren Sie Ihr `Muster`, `zone_name`, Queue-Bindings und `AIROPS_API_URL`.

{% hint style="info" %}
Die `Muster` sollte Ihre tatsächliche Domain oder die Zielseiten-URL sein, während die `zone_name` sollte die kanonische Domain sein. Wenn Ihre Zielseite zum Beispiel `https://blog.example.com`, sollte die `Muster` sollte `blog.example.com` und Ihre `zone_name` sollte `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: Konfigurieren Sie den Cloudflare-Worker-Code

Ersetzen Sie den Inhalt von `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 ausgelöst und speichert Anfragemetadaten in der Queue
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Speichere die Zeit, zu der die Anfrage begonnen hat
    const startTime = Date.now();

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

    // Klone die Antwort, damit sie wiederverwendet 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äßig 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('Fehler beim Senden der Protokolle:', 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: Konfigurieren Sie den AirOps-API-Schlüssel

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

```bash
# Bei Cloudflare anmelden
npx wrangler login

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

<figure><img src="https://1960680173-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-e819bcce3dcd2051f4b685120cc1796c628e0f8d%2Fagent-worker-01-setup-panel.png?alt=media" alt="Set up Agent Analytics panel for Cloudflare Worker with the ingest endpoint URL and workspace API token to copy"><figcaption><p>Kopieren Sie die AirOps-Werte für das Cloudflare-Worker-Setup.</p></figcaption></figure>

### Schritt 5: Erstellen Sie die Cloudflare Queue

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

### Schritt 6: Stellen Sie den Cloudflare Worker bereit

```bash
# Cloudflare Worker bereitstellen
npx wrangler deploy
```

### Schritt 7: Überprüfen Sie die Verbindung

Nachdem der Cloudflare Worker bereitgestellt wurde, sollten innerhalb von **2–5 Minuten**.

1. Erzeugen Sie etwas Traffic auf Ihrer Website.
2. In Ihrem **AirOps-Dashboard**, navigieren Sie zu **Agent Analytics**. Die Traffic-Daten sollten bald 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 Ratenlimits nicht zu überschreiten, und wird daher für die meisten Websites nicht empfohlen.

### Schritt 1: Initialisieren Sie den Cloudflare Worker

Für diesen Vorgang verwenden wir Version `2.68.2` der Cloudflare-CLI. Andere Nebenversionen können funktionieren, aber es kann Unterschiede bei den CLI-Eingabeaufforderungen geben.

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

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

Setzen Sie 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>

Setzen Sie 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>

Setzen Sie 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>

Setzen Sie 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ählen Sie **Ja** zum Verwenden von Git für die Versionsverwaltung.

<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ählen Sie **Nein** zum Bereitstellen Ihrer Anwendung (wir werden dies später tun).

<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: Konfigurieren Sie die Cloudflare-Worker-Route

Bearbeiten Sie die `wrangler.json` Datei und konfigurieren Sie Ihr `Muster`, `zone_name`, und `AIROPS_API_URL`.

{% hint style="info" %}
Die `Muster` sollte Ihre tatsächliche Domain oder die Zielseiten-URL sein, während die `zone_name` sollte die kanonische Domain sein. Wenn Ihre Zielseite zum Beispiel `https://blog.example.com`, sollte die `Muster` sollte `blog.example.com` und Ihre `zone_name` sollte `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: Konfigurieren Sie den Cloudflare-Worker-Code

Ersetzen Sie den Inhalt von `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 die Zeit, zu der die Anfrage begonnen hat
    const startTime = Date.now();

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

    // Klone die Antwort, damit sie wiederverwendet 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('Fehler beim Senden der Protokolle:', error))
}
```

### Schritt 4: Konfigurieren Sie den AirOps-API-Schlüssel

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

```bash
# Bei Cloudflare anmelden
npx wrangler login

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

### Schritt 5: Stellen Sie den Cloudflare Worker bereit

```bash
# Cloudflare Worker bereitstellen
npx wrangler deploy
```

### Schritt 6: Überprüfen Sie die Verbindung

Nachdem der Cloudflare Worker bereitgestellt wurde, sollten innerhalb von **2–5 Minuten**.

1. Erzeugen Sie etwas Traffic auf Ihrer Website.
2. In Ihrem **AirOps-Dashboard**, navigieren Sie zu **Agent Analytics**. Die Traffic-Daten sollten bald erscheinen.

***

## Ratenlimits

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

***

## Was AirOps erfasst

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

* **Erfasst alle Cloudflare-Anfragen**: 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 Crawl-Verhalten**: unterscheidet zwischen KI-Trainings-Crawlern, KI-Suchabrufen, KI-Indexierung und vom Nutzer initiiertem KI-Browsing
* **Stellt Analysen bereit**: Traffic-Aufschlüsselungen, Verhältnisse von Bots zu Menschen und Crawl-Trends in Ihrem 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.
