Siteline Documentation - AI Search Analytics

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

If you use Fastly, the recommended setup is the direct Fastly HTTPS logging integration. It avoids the AWS S3/EventBridge/Lambda path.

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

Clone and install

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

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)

Build and package Lambda

npm run package

Provision AWS resources

npm run setup:all

This runs:

npm run setup:s3
npm run setup:lambda
npm run setup:eventbridge

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:

CloudFront writes gzipped log files to S3.
S3 sends Object Created events to EventBridge.
EventBridge invokes the Lambda processor.
Lambda downloads and gunzips the log file.
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

string

required

Your Siteline website key. If missing, the Lambda exits without processing logs.

string

required

S3 bucket used for CloudFront standard logs. Lambda only reads objects from this bucket.

string

required

AWS region used by setup scripts and Lambda operations.

string

Region override for S3 bucket operations. Defaults to AWS_REGION.

string

Siteline intake endpoint. Defaults to https://api.siteline.ai/v1/intake/pageview.

boolean

Enables debug mode in the Siteline SDK.

string

Lambda function name. Default is siteline-cloudfront-s3-processor.

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

No Lambda invocations

Confirm CloudFront is writing standard logs to LOG_BUCKET_NAME, then verify S3 EventBridge notifications are enabled on that bucket.

No EventBridge to Lambda delivery

Check targets with:

aws events list-targets-by-rule --name "${EVENT_RULE_NAME}" --region "${AWS_REGION}"

AccessDenied errors during setup or runtime

Ensure deployer permissions include S3, IAM, Lambda, and EventBridge management. Also confirm Lambda execution role has s3:GetObject on the log bucket.

How do I inspect processor logs?

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.

Getting Started

Agent Analytics Integrations

Reporting

Reference

Guides

AWS CloudFront

Prerequisites

Setup

How it works

Configuration

Required IAM policies

Troubleshooting

​Prerequisites

​Setup

​How it works

​Configuration

​Required IAM policies

​Troubleshooting

Prerequisites

Setup

How it works

Configuration

Required IAM policies

Troubleshooting