> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usequotable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon CloudFront

> Deliver CloudFront real-time logs to Agent Analytics through a Kinesis data stream and an Amazon Data Firehose HTTP endpoint, with failed batches backed up to S3.

CloudFront real-time logs flow through resources in your own AWS account and reach Quotable through Amazon Data Firehose:

`CloudFront real-time logs` → `Kinesis Data Stream` → `Data Firehose (HTTP endpoint, gzip)` → `Quotable`

Nothing runs in your request path. Failed deliveries are backed up to an S3 bucket you own, so nothing is lost if delivery is interrupted.

## Requirements

* Permission in your AWS account to create a Kinesis data stream, a Firehose stream, an S3 bucket, IAM roles and a CloudFront real-time log configuration.
* **Region `us-east-1`.** CloudFront real-time log configurations must write to a Kinesis data stream in `us-east-1`.
* The distributions that serve the domain the source is created for.

**What it measures:** every field. Response time is CloudFront's `time-taken` (edge to viewer), not origin time.

## Set up with CloudFormation

The wizard's **Download CloudFormation template** button gives you a template that creates the Kinesis data stream, the Firehose stream, the S3 backup bucket, the IAM roles, the real-time log configuration with the right fields, and a CloudWatch alarm on failed deliveries. You can also [download it directly](https://app.usequotable.com/api/agent-analytics/connectors/cloudfront-firehose).

1. Create the source in Quotable (first step below) and copy the **Secrets Manager secret value**, which is your token as `{"api_key":"aa_live_…"}`.

2. Store it in Secrets Manager in `us-east-1`:

   ```bash theme={"system"}
   aws secretsmanager create-secret --region us-east-1 \
     --name quotable/agent-analytics/<source-id> \
     --secret-string '{"api_key":"aa_live_..."}'
   ```

3. Deploy the template in `us-east-1`:

   ```bash theme={"system"}
   aws cloudformation deploy --region us-east-1 \
     --stack-name quotable-agent-analytics \
     --template-file quotable-agent-analytics-cloudfront-v1.1.0.yaml \
     --capabilities CAPABILITY_IAM \
     --parameter-overrides \
       QuotableEndpoint=<your endpoint URL> \
       QuotableAccessKeySecretArn=<the secret ARN>
   ```

4. Attach the `RealtimeLogConfigArn` output to the cache behaviors of each distribution that serves the domain (see [Attach it to your distributions](#set-up-by-hand)). The stack can't edit distributions it doesn't own.

To remove everything, delete the stack. The S3 backup bucket is kept so failed deliveries aren't lost.

## Set up by hand

**1. Create the source in Quotable**

In **Agent Analytics**, select **Connect source** and choose **Amazon CloudFront**. Leave **Real-time log field order** empty unless you must reuse an existing real-time log configuration (see [Field order](#field-order)). Select **Generate credentials**.

The wizard shows the **Firehose access key** (your source token), the same key as a Secrets Manager secret value, and the field list. The endpoint URL for this connector ends in `/firehose`.

**2. Create a Kinesis data stream**

In `us-east-1`, create a Kinesis data stream. On-demand capacity mode works for most sites.

**3. Create the Firehose stream**

Create a Firehose stream with **Amazon Kinesis Data Streams** as the source (the stream from the previous step) and **HTTP Endpoint** as the destination:

| Setting | Value |
| - | - |
| HTTP endpoint URL | Your endpoint URL (ends in `/firehose`) |
| Authentication | The access key from the wizard, entered directly, or stored in AWS Secrets Manager as `{"api_key":"aa_live_…"}` |
| Content encoding | GZIP |
| Buffer size | 1 MiB |
| Buffer interval | 60 seconds |
| Retry duration | 300 seconds |
| S3 backup | Failed data only, to a private bucket you own |

Firehose sends the key in its `X-Amz-Firehose-Access-Key` header. Small buffers keep retries cheap and the dashboard within about a minute of real time.

**4. Create the real-time log configuration**

In CloudFront, create a real-time log configuration:

* **Sampling rate**: `100`. AI agent traffic is a small share of requests; lower it only if volume is a cost concern.
* **Endpoint**: the Kinesis data stream, with an IAM role CloudFront can use to write to it.
* **Fields**: exactly these:

```text theme={"system"}
timestamp, c-ip, sc-status, sc-bytes, cs-method, cs-host, cs-uri-stem, x-edge-request-id, time-taken, cs-user-agent, cs-referer, x-edge-result-type, c-country
```

This list contains no query string, cookies or request headers. In real-time logs `cs-host` is the hostname the visitor requested; `x-host-header` is the distribution's `cloudfront.net` name, so don't select it instead.

**5. Attach it to your distributions**

For each distribution that serves the domain, edit the cache behaviors and select the real-time log configuration. One source can receive logs from several distributions.

**6. Confirm delivery**

Select **Check now** in Quotable. With a 60-second buffer, the first delivery arrives within a couple of minutes of traffic.

> [!TIP]
>
> Add a CloudWatch alarm on the Firehose metric `DeliveryToHttpEndpoint.Success` so you hear about a delivery problem before anyone notices a gap in the dashboard.

## Field order

Real-time log lines have no header row: each value is matched to a field by position. CloudFront always writes the selected fields in its own fixed order, whatever order you select them in, and Quotable maps them the same way.

If you already have a real-time log configuration with a different set of fields that you can't change, enter its fields, comma-separated and in any order, in **Real-time log field order** when you create the source. Quotable reads the field names it knows (`timestamp`, `c-ip`, `sc-status`, `sc-bytes`, `cs-method`, `cs-host`, `cs-uri-stem`, `x-edge-request-id`, `time-taken`, `cs-user-agent`, `cs-referer`, `x-edge-result-type`, `c-country`) and ignores the rest.

## How delivery is answered

Quotable answers Firehose in the format Firehose requires. A delivery is acknowledged with `200` only when every record in it was processed. Any other status makes Firehose retry the whole delivery and, once the retry duration runs out, write it to your S3 backup bucket. Records already accepted from an earlier attempt aren't counted twice, because event IDs come from CloudFront's `x-edge-request-id`.

| Status | Meaning |
| - | - |
| `200` | Delivered. |
| `400` | The body isn't a Firehose envelope, or no record could be decoded. Check the destination is this endpoint and the field order. |
| `401` | Missing or wrong access key. |
| `404` | Wrong endpoint, or the source is disconnected. |
| `413` | Delivery above 5 MB. Lower the Firehose buffer size. |
| `415` | Content encoding other than GZIP or none. |
| `429` | Too many deliveries, or today's quota is reached. Firehose backs off. |

## Rotate the token

1. Rotate the token in Quotable. The old token stops working immediately.
2. Update the access key in the Firehose destination, or the value of the Secrets Manager secret (`{"api_key":"<new token>"}`).

Firehose retries failed deliveries for the retry duration, then writes them to your S3 bucket.

## Disconnect

1. Detach the real-time log configuration from your distributions.
2. Delete the Firehose stream, the Kinesis data stream and the real-time log configuration, or delete the CloudFormation stack if you used the template.
3. Disconnect the source in Quotable.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| `host_mismatch` on every record | `x-host-header` was selected instead of `cs-host`, or the field list entered in Quotable differs from the configuration | Recreate the configuration with the default field order. |
| `invalid_record` on every record | The field order doesn't match what the source expects | Use the default order, or set **Real-time log field order** to match. |
| Every event unverified | `c-ip` is missing or in the wrong position | Check the field order. |
| Records in the S3 backup bucket | Delivery failed for longer than the retry duration | Fix the cause in the Firehose error logs. |
| Firehose can't read the secret, or every delivery gets `401` | The Secrets Manager value is the bare token | Store it as JSON: `{"api_key":"aa_live_…"}`. |
| Nothing arrives | The configuration isn't attached to a cache behavior, or it writes to a stream outside `us-east-1` | Attach it to every behavior and use a stream in `us-east-1`. |

## Next steps

> [card] [Read the dashboard](https://docs.usequotable.com/agent-analytics/dashboard.md)
>
> What to look at once data arrives.

> [card] [Log file import](https://docs.usequotable.com/agent-analytics/connectors/log-file-import.md)
>
> Backfill the last seven days from a log export.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.