> 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/pt/insights/onsite/traffic/cloudfront-agent-analytics.md).

# CloudFront

Este guia mostra como configurar os registos em tempo real do Amazon CloudFront para serem transmitidos para o AirOps via Amazon Kinesis Data Firehose.

Este guia acompanha-o na configuração do Amazon CloudFront **logs em tempo real** para transmitir para a AirOps através de **Amazon Kinesis Data Firehose**. Uma vez ligado, a AirOps analisará automaticamente o seu tráfego, classificará as visitas de bots de IA (ChatGPT, Claude, Perplexity, Google e outros) e apresentará insights no seu painel Agent Analytics.

***

### Pré-requisitos

* Uma **AirOps** conta ativa com Agent Analytics ativado
* Uma **conta AWS** com acesso a CloudFront, Kinesis Data Firehose e IAM
* Uma **distribuição CloudFront** a servir o seu site
* A sua **Chave de API do Workspace:** disponível em Definições (barra de navegação à esquerda) > Workspace
* A sua **ID do Brand Kit:** disponível na URL, navegando para Contexto (barra de navegação à esquerda) > BrandKits, algo no formato de `https://app.airops.com/<YOUR_WORKSPACE_SLUG>/data/brand_kits/<YOUR_BRAND_KIT_ID>`

***

### Passo 1: Criar um fluxo de entrega do Kinesis Data Firehose

1. Abra o **Amazon Kinesis** consola e navegue até **Data Firehose**.
2. Clique em **Criar fluxo Firehose**.
3. Configure a origem e o destino:
   * **Origem:** `PUT direto`
   * **Destino:** `Endpoint HTTP`
4. Dê um nome ao seu fluxo (por exemplo, `airops-cloudfront-analytics`).

#### Configure o destino do endpoint HTTP

| Definição                     | Valor                                                                    |
| ----------------------------- | ------------------------------------------------------------------------ |
| **URL do endpoint HTTP**      | `https://ingest.airops.com/api/v1/cloudfront/<YOUR_BRAND_KIT_ID>/ingest` |
| **Chave de acesso**           | A sua chave de API do Workspace AirOps                                   |
| **Codificação do conteúdo**   | `GZIP`                                                                   |
| **Duração da nova tentativa** | `300` segundos (recomendado)                                             |

<figure><img src="https://31915162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2FVj41I6mzmUrWTy5eAlr2%2FScreenshot%202026-04-02%20at%206.52.32%E2%80%AFPM.png?alt=media&amp;token=33c45fe0-7d89-4008-9a49-c85f7a823972" alt=""><figcaption></figcaption></figure>

#### Configure as sugestões de buffer

| Definição               | Valor recomendado |
| ----------------------- | ----------------- |
| **Tamanho do buffer**   | `5 MiB`           |
| **Intervalo do buffer** | `60` segundos     |

Estas definições controlam com que frequência o Firehose entrega lotes à AirOps. Estas são as definições recomendadas para não receber erros 429 dos nossos servidores.

#### Configure as definições de cópia de segurança

* **Bucket de cópia de segurança S3:** Selecione ou crie um bucket S3 para cópias de segurança de entregas falhadas.
* **Modo de cópia de segurança:** `Apenas dados falhados` (recomendado).

5. Clique em **Criar fluxo Firehose**.

***

### Passo 2: Criar uma configuração de logs em tempo real do CloudFront

1. Abra o **CloudFront** consola.
2. Na navegação à esquerda, vá para **Registo > Adicionar > Amazon CloudWatch Logs**.
3. Selecione Entregar para Amazon Kinesis Firehose.
4. Selecione o fluxo de destino: o Firehose configurado
5. Configure as seguintes definições adicionais:

| Definição            | Valor   |
| -------------------- | ------- |
| **Campos**           | `todos` |
| **Formato de saída** | `JSON`  |

#### Selecionar campos de registo

Selecione **todos** dos seguintes campos. Todos são obrigatórios e os registos que não tiverem qualquer um deles não podem ser processados:

| Campo                 | Obrigatório |
| --------------------- | ----------- |
| `timestamp(date)`     | Sim         |
| `timestamp(time)`     | Sim         |
| `cs-method`           | Sim         |
| `cs-uri-stem`         | Sim         |
| `cs(User-Agent)`      | Sim         |
| `cs(Referer)`         | Sim         |
| `cs-protocol-version` | Sim         |
| `cs-protocol`         | Sim         |
| `cs-bytes`            | Sim         |
| `sc-status`           | Sim         |
| `sc-bytes`            | Sim         |
| `sc-content-type`     | Sim         |
| `time-taken`          | Sim         |
| `time-to-first-byte`  | Sim         |
| `ssl-protocol`        | Sim         |
| `ssl-cipher`          | Sim         |
| `x-edge-location`     | Sim         |
| `x-edge-result-type`  | Sim         |
| `x-host-header`       | Sim         |

`c-ip` quanto no `cs-uri-query` não são obrigatórios e a AirOps não armazena endereços IP dos visualizadores nem strings de consulta. Selecionar `todos` os campos envia-os, mas nós ignoramo-los. Se preferir não os partilhar, deixe-os de fora.

5. Clique em **Criar configuração**.

***

### Passo 3: Anexar a configuração de registo à sua distribuição

1. Aceda a **CloudFront > Distribuições** e selecione a sua distribuição.
2. Navegue até ao **Comportamentos** guia da Campanha.
3. Selecione o comportamento que pretende monitorizar (normalmente `Predefinido (*)`) e clique em **Editar**.
4. Em **Configuração de registos em tempo real**, selecione a `airops-analytics` configuração que acabou de criar.
5. Clique em **Guardar alterações**.

Repita para quaisquer comportamentos de cache adicionais que pretenda monitorizar.

***

### Passo 4: Verificar a ligação

Depois de anexar a configuração, os dados deverão começar a fluir dentro de **2-5 minutos**.

1. Gere algum tráfego para a sua distribuição CloudFront (visite o seu site).
2. Verifique o Firehose **Monitorização** separador na consola AWS para confirmar que os registos estão a ser entregues.
3. No seu **painel AirOps**, navegue para **Agent Analytics** — deverá ver os dados de tráfego a aparecer em breve.

<figure><img src="https://31915162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-83dcd0627e56f248caa6328ca3c0a9fd00e6880f%2Fagent-cloudfront-01-setup-panel.png?alt=media" alt="Set up Agent Analytics panel for CloudFront with the ingest endpoint URL and workspace API token to copy"><figcaption><p>Copie os valores da AirOps para a configuração do CloudFront.</p></figcaption></figure>

#### Resolução de problemas

| Sintoma                                  | Causa provável                      | Correção                                                                                               |
| ---------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| O Firehose mostra erros de entrega (401) | Chave de API inválida               | Verifique a sua chave de API em Definições da AirOps > Integrações                                     |
| O Firehose mostra erros de entrega (429) | Limite de taxa excedido             | Aumente o intervalo do buffer ou o tamanho do buffer para reduzir a frequência de entrega              |
| Sem dados na monitorização do Firehose   | Configuração de registo não anexada | Confirme que a configuração de registo em tempo real está anexada ao comportamento da sua distribuição |
| Dados no Firehose, mas não na AirOps     | Atraso de processamento             | Aguarde até 10 minutos; verifique se o seu ID do Brand Kit está correto na URL do endpoint             |

***

### Limites de taxa

O processador de entrada do AirOps impõe um limite de taxa de **5 pedidos por minuto por chave de API**. Com as definições de buffer recomendadas (5 MiB / 60 segundos), ficará bem dentro deste limite. Se tiver distribuições com tráfego muito elevado, aumente o tamanho ou o intervalo do buffer em conformidade.

***

### O que o AirOps monitoriza

Depois de ligado, o AirOps automaticamente:

* **Ingere todos os pedidos do CloudFront** — visualizações de página, recursos, chamadas de API
* **Classifica o tráfego de bots de IA** — identifica visitas de ChatGPT, Claude, Google, Perplexity, Meta, Apple, Bing, Bytedance, Common Crawl e outros
* **Categoriza o comportamento de crawl** — distingue entre crawlers de treino de IA, pedidos de pesquisa de IA, indexação de IA e navegação de IA iniciada pelo utilizador
* **Exibe análises** — repartições de tráfego, rácios entre bots e humanos e tendências de crawling no seu painel


---

# 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/pt/insights/onsite/traffic/cloudfront-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.
