# Log delivery

> Send partitioned CloudFront standard logging v2 records to S3.

`CloudFrontLogDelivery` sends standard logging v2 records from a CloudFront distribution to a
`LogBucket`.

```typescript
import { CloudFrontLogDelivery, LogBucket } from "@kensio/rainlytics/cdk";

const logs = new LogBucket(this, "Logs");

const delivery = new CloudFrontLogDelivery(this, "Delivery", {
  distributionId: "E1EXAMPLE1234",
  logBucket: logs.bucket,
});
```

Pass `delivery` to `LogTable`.

## Deploy from `us-east-1`

AWS configures CloudFront standard logging v2 through the CloudWatch Logs API in `us-east-1`.
Rainlytics refuses to synthesize this construct in another region.

Set `env.region` on the stack. You can omit `env.account` and let `cdk deploy` resolve the account
from your AWS profile:

```typescript
const stack = new Stack(app, "DeliveryStack", {
  env: { region: "us-east-1" },
});
```

This allows the stack to synthesize without credentials or an account number in its source.

The distribution can be defined in another stack. The delivery only needs its ID:

```typescript
new CloudFrontLogDelivery(this, "Delivery", {
  distributionId: distribution.distributionId,
  logBucket: logs.bucket,
});
```

Using a string avoids a CDK cross-region reference when the distribution belongs to another stack.

A distribution can have one standard logging v2 delivery source. Remove an existing v2 source
before adding this construct. Legacy standard logging is separate and can continue at the same
time.

CloudFront may take up to 12 hours to apply a logging change.

## Output layout

The defaults use JSON, hourly partitions and the `rainlytics` prefix:

```text
s3://<bucket>/rainlytics/distributionid=E1EXAMPLE1234/year=2026/month=09/day=01/hour=14/
```

The partition path is Hive-compatible. `LogTable` projects these keys and needs no crawler.

Change the format or partition size when you create the delivery:

```typescript
const delivery = new CloudFrontLogDelivery(this, "Delivery", {
  distributionId: "E1EXAMPLE1234",
  logBucket: logs.bucket,
  outputFormat: "parquet",
  granularity: "daily",
  prefix: "analytics",
});
```

JSON is the default. Parquet can reduce Athena scan size on larger datasets, but CloudFront
charges for the conversion. Compare conversion and query costs for your traffic before switching.

Changing the prefix or format affects new logs only. Existing objects keep their original keys
and format. A table configured for the new delivery may no longer read those older objects.

## Delivered fields

Rainlytics requests the smallest field set used by its built-in questions. The fields include the
request path, query string, referrer, user agent, host, country, response status, content type,
cache result, timestamp and viewer address.

The viewer address supports visitor counts and the repeated-event cap. To omit it:

```typescript
import { logFieldNamesWithoutAddress } from "@kensio/rainlytics";

const delivery = new CloudFrontLogDelivery(this, "Delivery", {
  distributionId: "E1EXAMPLE1234",
  logBucket: logs.bucket,
  fields: logFieldNamesWithoutAddress,
});
```

`LogTable` follows the selected field set. `RollupSummaries` then disables visitor counts and does
not read the visitor salt. The other default questions continue to work.

The first day after a field change contains a mixture of old and new records. Wait for a full day
of the new field set before comparing visitor totals.

## Customer-managed encryption

When the log bucket uses a customer-managed KMS key, the delivery service needs permission to use
that key. Rainlytics adds the grant when the key belongs to the same CDK construct graph. An
imported key may need its owning stack updated.

Test delivery after deployment. An encryption-policy error prevents new objects from reaching S3,
and the destination bucket cannot log the failed write.

## Deployment permissions

The standard CDK bootstrap role has enough permission. A restricted CloudFormation execution role
needs:

- CloudWatch Logs delivery source, destination and delivery management actions
- `cloudfront:AllowVendedLogDeliveryForResource` on the distribution
- the S3 permissions required by `LogBucket`
- IAM tagging and read/delete counterparts used by CloudFormation

Include `Get` and `Delete` actions as well as creation actions. CloudFormation reads resources
before updates and needs delete permission during rollback. A role with create-only permissions can
leave the stack in `ROLLBACK_FAILED`.

<!-- card
```typescript
const delivery = new CloudFrontLogDelivery(this, "Delivery", {
  distributionId: "E1EXAMPLE1234",
  logBucket: logs.bucket,
});
```
-->

---

This page: https://rainlytics.com/log-delivery/
Index of every page: https://rainlytics.com/llms.txt