What Rainlytics is

Rainlytics is a self-hosted web analytics package for sites served by Amazon CloudFront. Install it in an existing CDK app to deploy the analytics resources into your AWS account. Read the results with the rainlytics command.

The pipeline

The data passes through four stages:

1. CloudFront standard logging v2 writes access logs to your S3 bucket. The object paths identify the distribution and time period.
2. A Glue table describes the log files. Partition projection lets Athena calculate the S3 paths to read from the query’s time filters, without a crawler.
3. EventBridge Scheduler starts Lambda jobs after each hour and day ends. The jobs run analytics queries, called rollups, in Athena.
4. Each rollup result is saved as a small JSON summary in a second S3 bucket.

The command line reads those stored summaries:

rainlytics pageviews --last 7d

The deployment also writes calendar reports for completed days, weeks, months and years. Each report combines several analytics sections. Optional report notifications email selected results through SNS.

Use rainlytics query for ad-hoc SQL over the raw logs. The Athena workgroup limits how many bytes one query can scan.

Frontend JavaScript is optional

Access logs provide pageviews, referrers and other request measurements without adding Rainlytics JavaScript to your pages.

CloudFront cannot see a route change that stays inside a single-page app. It also cannot measure Web Vitals or JavaScript errors. The optional browser module records those events.

The module goes into the site’s existing bundle. It sends a GET to a path on the same domain. A CloudFront Function returns 204 before the request reaches the cache or origin, and the access log stores the event beside normal requests.

Browser events are stored and queried alongside ordinary access-log requests.

Data ownership and privacy

Raw logs, query results, summaries and reports stay in buckets owned by your AWS account. Rainlytics has no hosted service and receives no copy.

The default log fields include the viewer’s IP address. Visitor counts and repeated-event limits use that address together with the user agent. Athena hashes visitor identifiers using a salt derived from a secret in SSM Parameter Store. Summaries contain the final counts only.

You can omit the viewer address from delivery. Pageviews and the other access-log questions keep working, while visitor counts and the beacon-event cap become unavailable.

Browser error messages require separate care because application text can contain personal data. The error module provides a redact function that runs before a message reaches the log.

Cost model

The analytics pipeline uses services priced by requests, bytes or execution time. It requires no server or reserved capacity.

Athena applies a minimum billed scan to every query, even when the site received no traffic. Scheduled queries therefore cost tens of cents per month on a quiet site. More traffic and additional rollups increase the cost. See Summary schedule for the default query count and estimate.

Stored answers keep repeated reads cheap. A named command reads S3 objects and never runs Athena unless you add --query.

Interface and authentication

The CLI uses the AWS SDK credential chain for authentication and region settings. Use your existing IAM Identity Center profile, assumed role or workload credentials. IAM policies control access to stored results and raw queries.

Commands print a table for a person at a terminal and JSON for a pipe. CSV is available when a spreadsheet or another tool needs it.

Continue with Getting started to deploy the first pipeline.