Skip to main content
Use the Siteline AWS CloudFront S3 Log Processor to track CloudFront traffic with Siteline. This integration processes CloudFront standard access logs from S3, triggers on S3 object-created events via EventBridge, and forwards pageview events to the Siteline API.

​
Prerequisites

  • A Siteline website key
  • An existing CloudFront distribution configured to write standard access logs to S3
  • AWS CLI v2 configured for the target account
  • jq and zip installed locally
  • Node.js 18+ and npm
  • IAM permissions for s3, lambda, iam, and events
CloudFront standard logs are delayed by design. Typical availability is 5-15 minutes after requests occur.

​
Setup

1

Clone and install

git clone https://github.com/siteline-ai/siteline-cloudfront.git
cd siteline-cloudfront
npm install
2

Configure environment variables

cp .env.example .env
Set at minimum:
  • SITELINE_WEBSITE_KEY
  • LOG_BUCKET_NAME
  • AWS_REGION
  • AWS_PROFILE (if using SSO or non-default profile)
3

Build and package Lambda

npm run package
4

Provision AWS resources

npm run setup:all
This runs:
  • npm run setup:s3
  • npm run setup:lambda
  • npm run setup:eventbridge
5

Point CloudFront logs to the configured bucket

In your CloudFront distribution settings, enable standard access logs and confirm logs are written to LOG_BUCKET_NAME.

​
How it works

This integration uses S3 log delivery, EventBridge, and Lambda: 
CloudFront (standard logs)
  -> S3 log bucket
  -> EventBridge (Object Created)
  -> Lambda s3-log-processor
  -> Siteline intake API
Processing flow:
  1. CloudFront writes gzipped log files to S3.
  2. S3 sends Object Created events to EventBridge.
  3. EventBridge invokes the Lambda processor.
  4. Lambda downloads and gunzips the log file.
  5. Lambda parses the #Fields header dynamically, maps each valid row, and sends events to Siteline.
Rows with invalid status codes or missing URI are skipped. Malformed rows are skipped without stopping the rest of the file.

​
Configuration

​
SITELINE_WEBSITE_KEY
string
required
Your Siteline website key. If missing, the Lambda exits without processing logs.
​
LOG_BUCKET_NAME
string
required
S3 bucket used for CloudFront standard logs. Lambda only reads objects from this bucket.
​
AWS_REGION
string
required
AWS region used by setup scripts and Lambda operations.
​
S3_BUCKET_REGION
string
Region override for S3 bucket operations. Defaults to AWS_REGION.
​
SITELINE_ENDPOINT
string
Siteline intake endpoint. Defaults to https://api.siteline.ai/v1/intake/pageview.
​
SITELINE_DEBUG
boolean
Enables debug mode in the Siteline SDK.
​
LAMBDA_FUNCTION_NAME
string
Lambda function name. Default is siteline-cloudfront-s3-processor.
​
EVENT_RULE_NAME
string
EventBridge rule name for S3 object-created events.

​
Required IAM policies

Lambda trust policy: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": ["lambda.amazonaws.com"]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
Lambda execution policy (bucket name is injected during setup): 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudWatchLogs",
      "Effect": "Allow",
      "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
      "Resource": "arn:aws:logs:*:*:*"
    },
    {
      "Sid": "AllowReadCloudFrontLogsFromS3",
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::<LOG_BUCKET_NAME>/*"
    }
  ]
}

​
Troubleshooting

Confirm CloudFront is writing standard logs to LOG_BUCKET_NAME, then verify S3 EventBridge notifications are enabled on that bucket.
Check targets with:
aws events list-targets-by-rule --name "${EVENT_RULE_NAME}" --region "${AWS_REGION}"
Ensure deployer permissions include S3, IAM, Lambda, and EventBridge management. Also confirm Lambda execution role has s3:GetObject on the log bucket.
Stream CloudWatch logs with:
aws logs tail "/aws/lambda/${LAMBDA_FUNCTION_NAME}" --follow --region "${AWS_REGION}"
Need help? Book a setup call and we’ll walk you through it.