Amazon CloudFront

Amazon CloudFront can write a record of every request it answers, with standard logging (v2). Log Hero gives you a CloudFormation stack that turns this logging on for one distribution. The stack sends each record through an Amazon Data Firehose stream in your AWS account to Log Hero. You do not install code on your site, and the stack does not change your distribution.

Time: about 10 minutes · Access needed: AWS account that owns the distribution, Log Hero account

Before you start

Make sure that you have:

The AWS account that owns the distribution. You must be able to create a CloudFormation stack and IAM roles in it.
The distribution ID. It is the value that starts with E on the Distributions page of the CloudFront console.
The domain added in Log Hero. If it is not, do the Quickstart first.

The stack must be created in N. Virginia (us-east-1). CloudFront delivers logs to Firehose only from that region, and the stack refuses to deploy anywhere else.

The stack creates a Firehose stream, an S3 bucket, and a CloudWatch log group in your account. AWS bills you for these resources.

1. Open the CloudFront option in Log Hero

In your Keyword Hero account, open Log Hero → Bot Activity for the domain.
Choose Log Hero token. The setup page opens.
Under How to start?, choose Amazon CloudFront.

2. Create the stack

Sign in to the AWS account that owns the distribution.
In Log Hero, choose Launch the stack in AWS CloudFormation. The CloudFormation console opens in us-east-1 with your Log Hero API key filled in.
Paste your distribution ID into CloudFront Distribution ID.
Select I acknowledge that AWS CloudFormation might create IAM resources.
Choose Create stack.
Wait until the stack status is CREATE_COMPLETE.

The stack is named LogHero-CloudFront. Leave the Advanced parameters alone unless the distribution already has standard logging.

If the distribution already has standard logging

Find the name of the existing delivery source:

aws logs describe-delivery-sources --region us-east-1 \
  --query "deliverySources[?contains(resourceArns[0], 'EXXXXXXXXXXXXX')].name"

Replace EXXXXXXXXXXXXX with your distribution ID.
On the stack’s review page, enter the returned name under Existing Delivery Source Name.

The stack then adds Log Hero as a second delivery from that source.

If you prefer to deploy without the launch link

Choose Download the template in Log Hero, or use the published URL https://lh-handler-integrations.s3.us-east-1.amazonaws.com/lh-handler-cloudfront.yaml. Then deploy it with the AWS CLI:

aws cloudformation deploy \
  --region us-east-1 \
  --template-file lh-handler-cloudfront.yaml \
  --stack-name loghero-cloudfront \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
      ApiKey=<your-loghero-api-key> \
      CloudFrontDistributionId=EXXXXXXXXXXXXX

If the distribution already has standard logging, add ExistingDeliverySourceName=<name> to the parameters. Your API key is shown on the Log Hero setup page.

3. Make sure that hits arrive

In the CloudFormation console, make sure that the stack status is CREATE_COMPLETE.
Wait up to one hour. Firehose collects records for up to one minute before it sends them, and CloudFront delivers logs with a delay.
Open Log Hero → Bot Activity. Make sure that the status line reads Log Hero is receiving bot traffic for this domain.
Make sure that Bot hits is not zero.

You do not need to make traffic yourself. Bots arrive on their own, and on most sites the first bot request lands within the hour.

If the stack does not complete

Symptom	Cause	What to do
The console refuses the template before creation.	The region is not us-east-1.	Switch the console to N. Virginia (us-east-1) and start again.
The parameter CloudFront Distribution ID is rejected.	The value does not start with `E` followed by uppercase letters and digits.	Copy the ID from the Distributions page of the CloudFront console.
Creation fails on the delivery source.	The distribution already has a standard logging (v2) source.	Delete the failed stack. Create it again with Existing Delivery Source Name filled in.
Creation fails on an IAM role.	The acknowledgement was not selected, or your user cannot create IAM roles.	Select the acknowledgement, or ask an AWS administrator to create the stack.

If the stack completes but no hits arrive

The stack’s Outputs tab names two places to look:

FirehoseLogGroupName is a CloudWatch log group. It holds the HTTP response that Log Hero returned for each failed delivery. Start here. A rejected API key appears as an error message in this group.
BackupBucketName is an S3 bucket. Firehose writes a record there only after it has retried the delivery for two hours. Objects expire after 30 days.

If both are empty, CloudFront has not delivered logs yet, or the stack is attached to a different distribution than the one that serves your domain. Then work through No data arriving.

What the stack creates

All resources live in your AWS account, in us-east-1:

A CloudFront standard logging (v2) delivery source for the distribution, unless you gave the name of an existing one.
A delivery destination and a delivery that bind the source to the stream.
An Amazon Data Firehose stream that sends each batch to https://in.app.log-hero.com/cloudfront-logs, with your API key in the access-key header.
An S3 bucket for records that Log Hero did not accept. The bucket is kept when you delete the stack.
A CloudWatch log group for Firehose delivery errors, kept for 14 days.
An IAM role that lets Firehose write to the bucket and the log group.

The stack does not change your distribution, its cache settings, or its origins.

What the connector sends

The stack turns on logging with a fixed list of 14 fields. You cannot change the list in Log Hero.

date
time
timestamp(ms)
c-ip
cs-method
cs(Host)
x-host-header
cs-uri-stem
cs-uri-query
cs(User-Agent)
cs(Referer)
cs-protocol
sc-status
time-taken

Four facts about these fields matter for your reports:

c-ip is required. When the record arrives, Log Hero hashes the address and does not store the raw address. The hash identifies the visitor. A record without c-ip is dropped.
The hostname comes from x-host-header. This is the Host header that the visitor sent, so hits land on your domain and not on the cloudfront.net name. If the field is empty, Log Hero uses cs(Host) instead.
Timing is measured by CloudFront. time-taken is the time CloudFront needed to answer, not the time the visitor waited. The origin integrations measure the time inside your server, so the two values are not comparable.
Every request is logged. Standard logging (v2) has no sampling, so the bot counts are complete.

What CloudFront does not send

Requests that CloudFront never sees. Traffic that goes to your origin directly is invisible here. If your DNS has a bare origin hostname, bots will find it.

Disconnect the distribution

In the CloudFormation console, in us-east-1, select the stack LogHero-CloudFront.
Choose Delete.

The distribution keeps running unchanged, and other deliveries that you configured for it stay in place. The S3 bucket is kept, so delete it yourself if you do not need its contents.

If it does not work

Work through No data arriving. Two places are specific to CloudFront. The stack’s Outputs tab is described in If the stack completes but no hits arrive. The stack’s Events tab shows why a resource failed.