> 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/fr/insights/onsite/traffic/cloudflare-worker-agent-analytics.md).

# Cloudflare Worker

Ce guide vous explique comment configurer un Cloudflare Worker pour diffuser les journaux de requêtes dans AirOps pour Agent Analytics.

Ce guide vous explique comment configurer Cloudflare pour diffuser vers AirOps via **Workers**. Une fois connecté, AirOps analyse automatiquement votre trafic, classe les visites de robots IA (ChatGPT, Claude, Perplexity, Google, et plus encore) et met en avant des insights dans votre tableau de bord Agent Analytics.

{% hint style="info" %}
**Logpush ou Worker ?** Si vous êtes sur un forfait Cloudflare Enterprise, nous recommandons [Cloudflare Logpush](https://docs.airops.com/docs/fr/insights/onsite/traffic/cloudflare-logpush-agent-analytics.md) à la place. C'est l'option la plus simple et ne nécessite aucun code. Utilisez Workers lorsque Logpush n'est pas disponible, par exemple sur les forfaits non Enterprise.
{% endhint %}

***

## Prérequis

* Un **AirOps** compte actif avec Agent Analytics activé
* Un **Cloudflare** compte Cloudflare qui sert votre site web et qui est soit au niveau Enterprise, soit dispose de l'option complémentaire Workers Paid
* Une machine de développement avec Node.js installé
* Votre **clé API de l'espace de travail**, disponible dans `Paramètres → Espace de travail`
* Votre **ID du Brand Kit**, disponible dans l'URL en naviguant vers `Contexte → Kits de marque`. L'URL prend la forme `https://app.airops.com/<YOUR_WORKSPACE_SLUG>/data/brand_kits/<YOUR_BRAND_KIT_ID>`

***

## Regroupement avec Workers

L'intégration de regroupement est l' **recommandée** approche recommandée pour la plupart des sites web. Elle utilise une Cloudflare Queue pour mettre en mémoire tampon les événements de journal par requête et les envoyer à AirOps par lots, vous maintenant bien en dessous de la limite de débit AirOps même en cas de trafic élevé.

### Étape 1 : initialiser le Worker Cloudflare

Pour ce processus, nous utiliserons la version `2.68.2` de la CLI Cloudflare. D'autres versions mineures peuvent fonctionner, mais il peut y avoir des différences dans les invites de la CLI.

{% hint style="info" %}
Selon votre environnement de développement, vous devrez peut-être installer manuellement les paquets Node suivants : `node-addon-api`, `node-gyp`, et `sharp`.
{% endhint %}

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

Définissez le répertoire sur `airops-log-collector`.

<figure><img src="https://344527547-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>

Définissez l'exemple de départ sur `exemple Hello World`.

<figure><img src="https://344527547-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>

Définissez le modèle sur `Worker consommateur et producteur de file d'attente`.

<figure><img src="https://344527547-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>

Définissez la langue sur `TypeScript`.

<figure><img src="https://344527547-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>

Choisissez **Oui** pour utiliser git pour le contrôle de version.

<figure><img src="https://344527547-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>

Choisissez **Non** pour déployer votre application (nous le ferons plus tard).

<figure><img src="https://344527547-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>

### Étape 2 : configurer la route du Worker Cloudflare

Modifiez le `wrangler.json` fichier et configurez votre `motif`, `zone_name`, liaisons de file d'attente et `AIROPS_API_URL`.

{% hint style="info" %}
La `motif` doit être votre domaine réel ou l'URL du site cible, tandis que le `zone_name` doit être le domaine canonique. Par exemple, si votre site cible est `https://blog.example.com`, le `motif` doit être `blog.example.com` et votre `zone_name` doit être `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"
  }
}
```

### Étape 3 : configurer le code du Worker Cloudflare

Remplacez le contenu du `src/index.ts` fichier par le code suivant.

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

export default {
  // Le producteur de file d'attente est invoqué à chaque visite de page et enregistre les métadonnées de la requête dans la file d'attente
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Enregistrer l'heure de début de la requête
    const startTime = Date.now();

    // Effectuer la requête
    const response = await fetch(request);

    // Cloner la réponse pour qu'elle puisse être réutilisée
    const responseClone = response.clone();

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

  // Le consommateur de file d'attente lit les messages de la file et envoie périodiquement des lots à 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('Échec de l'envoi des logs :', 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));
}
```

### Étape 4 : configurer la clé API AirOps

{% hint style="info" %}
Votre `AIROPS_API_KEY` doit être définie sur la même valeur que votre clé API d'espace de travail, disponible dans `Paramètres → Espace de travail`.
{% endhint %}

```bash
# Se connecter à Cloudflare
npx wrangler login

# Configurer la clé API
npx wrangler secret put AIROPS_API_KEY
```

<figure><img src="https://344527547-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>Copiez les valeurs AirOps pour la configuration du Worker Cloudflare.</p></figcaption></figure>

### Étape 5 : créer la file d'attente Cloudflare

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

### Étape 6 : déployer le Worker Cloudflare

```bash
# Déployer le Worker Cloudflare
npx wrangler deploy
```

### Étape 7 : vérifier la connexion

Après le déploiement du Worker Cloudflare, les données devraient commencer à circuler dans les **2 à 5 minutes**.

1. Générez un peu de trafic vers votre site web.
2. Dans votre **tableau de bord AirOps**, accédez à **Agent Analytics**. Les données de trafic devraient apparaître sous peu.

***

## Workers alternatif

L'approche d'intégration alternative envoie un événement à AirOps à chaque visite de page. Elle convient mieux aux sites web ayant moins de visites afin d'éviter de dépasser les limites de débit et n'est donc pas recommandée pour la plupart des sites web.

### Étape 1 : initialiser le Worker Cloudflare

Pour ce processus, nous utiliserons la version `2.68.2` de la CLI Cloudflare. D'autres versions mineures peuvent fonctionner, mais il peut y avoir des différences dans les invites de la CLI.

{% hint style="info" %}
Selon votre environnement de développement, vous devrez peut-être installer manuellement les paquets Node suivants : `node-addon-api`, `node-gyp`, et `sharp`.
{% endhint %}

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

Définissez le répertoire sur `airops-log-collector`.

<figure><img src="https://344527547-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>

Définissez l'exemple de départ sur `exemple Hello World`.

<figure><img src="https://344527547-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>

Définissez le modèle sur `Worker uniquement`.

<figure><img src="https://344527547-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>

Définissez la langue sur `TypeScript`.

<figure><img src="https://344527547-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>

Choisissez **Oui** pour utiliser git pour le contrôle de version.

<figure><img src="https://344527547-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>

Choisissez **Non** pour déployer votre application (nous le ferons plus tard).

<figure><img src="https://344527547-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>

### Étape 2 : configurer la route du Worker Cloudflare

Modifiez le `wrangler.json` fichier et configurez votre `motif`, `zone_name`, et `AIROPS_API_URL`.

{% hint style="info" %}
La `motif` doit être votre domaine réel ou l'URL du site cible, tandis que le `zone_name` doit être le domaine canonique. Par exemple, si votre site cible est `https://blog.example.com`, le `motif` doit être `blog.example.com` et votre `zone_name` doit être `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"
  }
}
```

### Étape 3 : configurer le code du Worker Cloudflare

Remplacez le contenu du `src/index.ts` fichier par le code suivant.

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

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Enregistrer l'heure de début de la requête
    const startTime = Date.now();

    // Effectuer la requête
    const response = await fetch(request);

    // Cloner la réponse pour qu'elle puisse être réutilisée
    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('Échec de l'envoi des logs :', error))
}
```

### Étape 4 : configurer la clé API AirOps

{% hint style="info" %}
Votre `AIROPS_API_KEY` doit être définie sur la même valeur que votre clé API d'espace de travail, disponible dans `Paramètres → Espace de travail`.
{% endhint %}

```bash
# Se connecter à Cloudflare
npx wrangler login

# Configurer la clé API
npx wrangler secret put AIROPS_API_KEY
```

### Étape 5 : déployer le Worker Cloudflare

```bash
# Déployer le Worker Cloudflare
npx wrangler deploy
```

### Étape 6 : vérifier la connexion

Après le déploiement du Worker Cloudflare, les données devraient commencer à circuler dans les **2 à 5 minutes**.

1. Générez un peu de trafic vers votre site web.
2. Dans votre **tableau de bord AirOps**, accédez à **Agent Analytics**. Les données de trafic devraient apparaître sous peu.

***

## Limites de débit

L'ingesteur AirOps applique une limite de débit de **5 requêtes par minute et par clé API**. Le Worker en temps réel envoie une requête par visite de page, donc cette option convient mieux aux sites à faible trafic. Pour les sites à fort trafic, regroupez les requêtes ou utilisez une option d'ingestion tamponnée.

***

## Ce qu'AirOps suit

Une fois connecté, AirOps :

* **Ingeste toutes les requêtes Cloudflare** : pages vues, ressources et appels API
* **Classe le trafic des robots IA** : identifie les visites provenant de ChatGPT, Claude, Google, Perplexity, Meta, Apple, Bing, Bytedance, Common Crawl et d'autres
* **Catégorise le comportement d'exploration** : distingue les robots d'entraînement IA, les récupérations de recherche IA, l'indexation IA et la navigation IA initiée par l'utilisateur
* **Met en avant des analyses** : répartitions du trafic, ratios robots/humains et tendances d'exploration dans votre tableau de bord


---

# 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/fr/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.
