Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions infrastructure/analytics-api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ strict dates, bounded UTM/surface tokens, and an exact query-free path. SQL is s
API named parameters; callers cannot provide SQL, object names, sort clauses,
or result limits.

Reports are limited to 366 inclusive days and 2,000 decoded rows. Query waits
Reports are limited to 366 inclusive days and 2,000 decoded rows, with an additional
allowance of four rows per selected day for SpaceTech’s daily source metrics. Query waits
leave time for a sanitized response. A failed or aborted statement is retried
once within the same deadline. Clients can opt into resumable requests with
`async=true`. If Redshift Serverless needs longer than one HTTP request, the API
Expand Down Expand Up @@ -171,7 +172,9 @@ parameter remains accepted for API compatibility, but content no longer splits
campaign rows or appears in the UI. Distinct visitors are recomputed across all
content values, rather than summing distinct counts. `filterOptions` contains
available source/medium/campaign values for the date range independently of
selected UTM filters. The SpaceTech tab defaults to 90 days.
selected UTM filters. The campaign starts on November 5, 2026 at 00:00 UTC.
Overlapping requests use that date as their earliest start. Requests ending
before launch return HTTP 400. The SpaceTech tab defaults to up to 90 days.

The API retains its JWT/analytics-role gate, parameterized queries, 60-second
cache and resumable-query protocol. `dataThrough` is now the UTC timestamp of
Expand Down Expand Up @@ -280,7 +283,7 @@ is not a promise that the visitor is still online. Simultaneous tabs cannot be
unambiguously distinguished without a future per-form-instance tracking ID.

Activity follows warehouse ingestion, while submitted lead details remain
immediate. The existing 2,000-row response limit still fails explicitly rather
immediate. The response row limit still fails explicitly rather
than silently truncating activity. Historical FAQ opens and form-section exposure
cannot be reconstructed without the corresponding website instrumentation.

Expand All @@ -290,8 +293,8 @@ procedure in place until no deployment uses them. No data deletion is needed.

### SpaceTech source dashboard (PM-6775)

The same endpoint now adds `personas` (full-period totals) and `personaSeries`
(weekly metrics), both for Topcoder, George, Anita and Tony. The persona is the
The endpoint returns `personas` (full-period totals), `dailyPersonaSeries` (daily metrics),
and `personaSeries` (weekly metrics) for Topcoder, George, Anita and Tony. The persona is the
fourth underscore-delimited token in `customer_spacetech_[period]_[persona]_…`,
matched case-insensitively from **utm_campaign only**. Source, medium and content
never assign a persona. Unknown names and unattributed traffic remain in the
Expand All @@ -303,9 +306,8 @@ multiple sources. Rates use aggregate numerators/denominators, never sums or
averages of daily/campaign rates. Submissions/visitors can exceed 100%; zero
denominators yield zero. Weekly buckets start Monday at 00:00 UTC, and first/last
weeks include only events inside the requested inclusive dates. Quiet weeks and
missing sources are zero-filled. At the maximum 366-day range, the new SQL adds
at most 220 aggregate rows (four totals plus four × 54 weeks), retaining the
existing 2,000-row result limit and bounded polling protocol.
missing sources are zero-filled. Daily buckets follow the same attribution and date filters. The SpaceTech query
allows four extra rows per selected day, up to 1,464 extra rows for a 366-day range.

Deploy the updated `handler.py` to the existing development analytics Lambda
using a versioned S3 zip and the stack's `CodeKey` parameter. No warehouse DDL,
Expand Down
57 changes: 33 additions & 24 deletions infrastructure/analytics-api/src/handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@


MAX_DATE_RANGE_DAYS = 366
SPACETECH_CAMPAIGN_START = "2026-11-05"
MAX_RESULT_ROWS = 2_000
MAX_QUERY_ATTEMPTS = 2
REPORT_CACHE_SECONDS = 60
Expand Down Expand Up @@ -377,7 +378,7 @@
"""


SPACETECH_SQL = """
SPACETECH_SQL = f"""
WITH form_events AS (
SELECT * FROM topcoder_web.spacetech_form_events_v1
WHERE event_timestamp >= CAST(:from_date AS timestamp)
Expand Down Expand Up @@ -422,11 +423,13 @@
AND LOWER(SPLIT_PART(campaign, '_', 2)) = 'spacetech'
AND LOWER(SPLIT_PART(campaign, '_', 4)) IN ('topcoder', 'george', 'anita', 'tony')
THEN LOWER(SPLIT_PART(campaign, '_', 4)) END AS persona,
event_timestamp::date AS event_day,
DATE_TRUNC('week', event_timestamp)::date AS week_start
FROM events
)
SELECT 'summary'::varchar AS row_type, NULL::varchar AS dimension_1, NULL::varchar AS dimension_2, NULL::varchar AS dimension_3,
(SELECT MAX(event_timestamp)::varchar FROM topcoder_web.spacetech_events_mv_v2) AS dimension_4,
(SELECT MAX(event_timestamp)::varchar FROM topcoder_web.spacetech_events_mv_v2
WHERE event_timestamp >= TIMESTAMP '{SPACETECH_CAMPAIGN_START}') AS dimension_4,

COUNT(CASE WHEN event_name = '_page_view' THEN 1 END)::bigint AS page_views,
COUNT(DISTINCT CASE WHEN event_name = '_page_view' THEN analytics_user_id END)::bigint AS visitors,
Expand Down Expand Up @@ -464,7 +467,10 @@
FROM events
GROUP BY 2, 3, 4
UNION ALL
SELECT 'persona'::varchar AS row_type, persona AS dimension_1, NULL::varchar AS dimension_2,
SELECT CASE WHEN GROUPING(event_day) = 0 THEN 'persona_daily'
WHEN GROUPING(week_start) = 0 THEN 'persona_weekly'
ELSE 'persona' END::varchar AS row_type,
persona AS dimension_1, COALESCE(event_day, week_start)::varchar AS dimension_2,
NULL::varchar AS dimension_3, NULL::varchar AS dimension_4,
COUNT(CASE WHEN event_name = '_page_view' THEN 1 END)::bigint AS page_views,
COUNT(DISTINCT CASE WHEN event_name = '_page_view' THEN analytics_user_id END)::bigint AS visitors,
Expand All @@ -475,20 +481,7 @@
COUNT(*)::bigint AS events,
COUNT(DISTINCT analytics_user_id)::bigint AS users
FROM persona_events WHERE persona IS NOT NULL
GROUP BY persona
UNION ALL
SELECT 'persona_weekly'::varchar AS row_type, persona AS dimension_1, week_start::varchar AS dimension_2,
NULL::varchar AS dimension_3, NULL::varchar AS dimension_4,
COUNT(CASE WHEN event_name = '_page_view' THEN 1 END)::bigint AS page_views,
COUNT(DISTINCT CASE WHEN event_name = '_page_view' THEN analytics_user_id END)::bigint AS visitors,
COUNT(CASE WHEN event_name = 'form_started' THEN 1 END)::bigint AS starts,
COUNT(CASE WHEN event_name = 'form_completed' THEN 1 END)::bigint AS submissions,
COUNT(DISTINCT CASE WHEN event_name = 'form_section_reached' THEN analytics_user_id END)::bigint AS reached,
COALESCE(SUM(CASE WHEN event_name = '_user_engagement' THEN user_engagement_time_msec ELSE 0 END), 0)::bigint AS engagement_ms,
COUNT(*)::bigint AS events,
COUNT(DISTINCT analytics_user_id)::bigint AS users
FROM persona_events WHERE persona IS NOT NULL
GROUP BY persona, week_start
GROUP BY GROUPING SETS ((persona), (persona, week_start), (persona, event_day))
UNION ALL
SELECT 'country'::varchar AS row_type, country AS dimension_1, NULL::varchar AS dimension_2, NULL::varchar AS dimension_3, NULL::varchar AS dimension_4,

Expand Down Expand Up @@ -941,6 +934,9 @@ def handler(event: dict[str, Any], context: Any) -> dict[str, Any]:
key: _safe_filter(query.get(key), key)
for key in ("source", "medium", "campaign", "content")
}}
if filters["to"] < SPACETECH_CAMPAIGN_START:
raise ValueError(f"SpaceTech reporting starts on {SPACETECH_CAMPAIGN_START}")
filters["from"] = max(filters["from"], SPACETECH_CAMPAIGN_START)
report = _cached_report(
f"spacetech:{json.dumps(filters, sort_keys=True)}",
REPORT_CACHE_SECONDS,
Expand Down Expand Up @@ -1662,6 +1658,7 @@ def _execute_query(
context: Any,
query_token: str | None = None,
maximum_wait_seconds: float = 24.0,
max_result_rows: int = MAX_RESULT_ROWS,
) -> list[dict[str, Any]]:
"""Execute a fixed parameterized query with resumable timeout handling.

Expand All @@ -1670,6 +1667,8 @@ def _execute_query(
parameters: Validated Data API named parameters.
context: Lambda context or null for the cached filter loader.
query_token: Optional server-issued token that resumes a pending statement.
maximum_wait_seconds: Upper bound on the query wait.
max_result_rows: Upper bound on decoded rows for this report.

Returns:
Query rows keyed by Redshift column name.
Expand Down Expand Up @@ -1706,7 +1705,7 @@ def _execute_query(
if status["Status"] == "FINISHED":
if status.get("HasResultSet") is False:
return []
return _statement_rows(statement_id)
return _statement_rows(statement_id, max_result_rows)
if status["Status"] in {"FAILED", "ABORTED"}:
if attempt + 1 < MAX_QUERY_ATTEMPTS:
break
Expand Down Expand Up @@ -1798,11 +1797,12 @@ def _query_wait_seconds(context: Any, maximum: float = 24.0) -> float:
return maximum


def _statement_rows(statement_id: str) -> list[dict[str, Any]]:
def _statement_rows(statement_id: str, max_result_rows: int) -> list[dict[str, Any]]:
"""Page through one Data API result without exceeding the response contract.

Args:
statement_id: Completed Data API statement identifier.
max_result_rows: Upper bound across all pages.

Returns:
Decoded query rows.
Expand All @@ -1821,7 +1821,7 @@ def _statement_rows(statement_id: str) -> list[dict[str, Any]]:
columns = [column["name"] for column in page.get("ColumnMetadata", [])]
rows.extend({name: _field_value(field) for name, field in zip(columns, record)}
for record in page.get("Records", []))
if len(rows) > MAX_RESULT_ROWS:
if len(rows) > max_result_rows:
raise QueryFailure("Analytics query exceeded the result row bound")
next_token = page.get("NextToken")
if not next_token:
Expand Down Expand Up @@ -2077,7 +2077,11 @@ def _now_iso() -> str:

def _spacetech_report(filters: dict[str, str], context: Any, query_token: str | None = None) -> dict[str, Any]:
"""Return aggregate SpaceTech traffic and form conversions; never expose lead answers or visitor IDs."""
rows = _execute_query(SPACETECH_SQL, _sql_parameters(filters), context, query_token)
start, end = date.fromisoformat(filters["from"]), date.fromisoformat(filters["to"])
personas = ("topcoder", "george", "anita", "tony")
days = (end - start).days + 1
rows = _execute_query(SPACETECH_SQL, _sql_parameters(filters), context, query_token,
max_result_rows=MAX_RESULT_ROWS + len(personas) * days)

def metrics(row: dict[str, Any]) -> dict[str, Any]:
"""Use visitors as the submission-rate denominator and page views for engaged time."""
Expand All @@ -2101,14 +2105,18 @@ def groups(kind: str, dimensions: list[str]) -> list[dict[str, Any]]:

daily = {row["date"]: row for row in groups("daily", ["date"])}
# Include quiet campaign days so a two-month chart does not collapse gaps.
start, end = date.fromisoformat(filters["from"]), date.fromisoformat(filters["to"])
persona_daily = {(row["dimension_2"], row["dimension_1"]): metrics(row)
for row in rows if row["row_type"] == "persona_daily"}
series = []
for offset in range((end - start).days + 1):
daily_persona_series = []
for offset in range(days):
day = (start + timedelta(days=offset)).isoformat()
series.append(daily.get(day, {"date": day, **metrics({})}))
daily_persona_series.append({"date": day, **{
persona: persona_daily.get((day, persona), metrics({})) for persona in personas
}})
# Compute distinct visitors over each whole persona/period in SQL; never
# sum daily or campaign-level uniques or average already-calculated rates.
personas = ("topcoder", "george", "anita", "tony")
persona_totals = {row["dimension_1"]: metrics(row)
for row in rows if row.get("row_type") == "persona"}
persona_weekly = {(row["dimension_1"], row["dimension_2"]): metrics(row)
Expand Down Expand Up @@ -2137,6 +2145,7 @@ def groups(kind: str, dimensions: list[str]) -> list[dict[str, Any]]:
"personas": [{"persona": persona, **persona_totals.get(persona, metrics({}))}
for persona in personas],
"personaSeries": persona_series,
"dailyPersonaSeries": daily_persona_series,
"campaigns": groups("campaign", ["source", "medium", "campaign"]),
"filterOptions": {
key: sorted({row["dimension_1"] for row in rows
Expand Down
28 changes: 20 additions & 8 deletions infrastructure/analytics-api/tests/test_handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
import sys
import types
import unittest
from datetime import datetime, timezone
from pathlib import Path
from unittest.mock import Mock, patch

Expand Down Expand Up @@ -119,7 +120,7 @@ def test_spacetech_report_attribution_rates_and_quiet_days(self) -> None:
rows = [
{"row_type": "summary", "page_views": 20, "visitors": 10, "starts": 5,
"submissions": 2, "reached": 7, "engagement_ms": 100000},
{"row_type": "daily", "dimension_1": "2026-09-01", "visitors": 10, "submissions": 2},
{"row_type": "daily", "dimension_1": "2026-11-05", "visitors": 10, "submissions": 2},
{"row_type": "campaign", "dimension_1": "linkedin", "dimension_2": "social",
"dimension_3": "customer_spacetech_nov26_george", "dimension_4": "post_1",
"visitors": 10, "submissions": 2},
Expand All @@ -128,7 +129,7 @@ def test_spacetech_report_attribution_rates_and_quiet_days(self) -> None:
{"row_type": "option_source", "dimension_1": "email"},
{"row_type": "option_source", "dimension_1": "linkedin"},
]
query = {"from": "2026-09-01", "to": "2026-09-03", "source": "linkedin", "content": "post_1"}
query = {"from": "2026-11-01", "to": "2026-11-07", "source": "linkedin", "content": "post_1"}
with patch.object(self.module, "_execute_query", return_value=rows) as execute:
response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], query), None)
self.assertEqual(response["statusCode"], 200)
Expand All @@ -143,23 +144,26 @@ def test_spacetech_report_attribution_rates_and_quiet_days(self) -> None:
self.assertEqual(report["countries"][0]["country"], "")
self.assertNotIn("analytics_user_id", response["body"])
params = {item["name"]: item["value"] for item in execute.call_args.args[1]}
self.assertEqual(params["from_date"], "2026-11-05")
self.assertEqual(report["filters"]["from"], "2026-11-05")
self.assertEqual(report["series"][0]["date"], "2026-11-05")
self.assertEqual(params["source"], "linkedin")
self.assertEqual(params["content"], "post_1")
self.assertIn(":content", execute.call_args.args[0])
self.assertNotIn("linkedin", execute.call_args.args[0])

def test_spacetech_form_activity_excludes_identifiers_and_answers(self) -> None:
rows = [{"row_type": kind, "dimension_1": "2026-11-04 12:00:00",
rows = [{"row_type": kind, "dimension_1": "2026-11-05 12:00:00",
"dimension_2": "linkedin", "dimension_3": "social", "dimension_4": "campaign",
"visitor_id": "private", "session_id": "private", "email": "private"}
for kind in ("form_started", "form_incomplete")]
with patch.object(self.module, "_execute_query", return_value=rows):
response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], {
"from": "2026-11-04", "to": "2026-11-04",
"from": "2026-11-05", "to": "2026-11-05",
}), None)
activity = json.loads(response["body"])["formActivity"]
self.assertEqual([row["status"] for row in activity], ["Started", "Incomplete"])
self.assertEqual(activity[0], {"startedAt": "2026-11-04T12:00:00.000Z", "source": "linkedin",
self.assertEqual(activity[0], {"startedAt": "2026-11-05T12:00:00.000Z", "source": "linkedin",
"medium": "social", "campaign": "campaign", "status": "Started"})
self.assertNotIn("private", response["body"])

Expand Down Expand Up @@ -193,13 +197,16 @@ def test_spacetech_persona_totals_and_weekly_rates(self) -> None:

def test_spacetech_empty_personas_cover_maximum_range(self) -> None:
"""All four sources and up to 54 Monday buckets remain bounded for 366 days."""
with patch.object(self.module, "_execute_query", return_value=[]):
with patch.object(self.module, "datetime", wraps=datetime) as clock, \
patch.object(self.module, "_execute_query", return_value=[]):
clock.now.return_value = datetime(2027, 11, 8, tzinfo=timezone.utc)
response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], {
"from": "2025-11-02", "to": "2026-11-02",
"from": "2026-11-08", "to": "2027-11-08",
}), None)
report = json.loads(response["body"])
self.assertEqual(len(report["personas"]), 4)
self.assertEqual(len(report["personaSeries"]), 54)
self.assertEqual(len(report["dailyPersonaSeries"]), 366)
for week in report["personaSeries"]:
for persona in ("topcoder", "george", "anita", "tony"):
self.assertEqual(week[persona]["submissionRate"], 0)
Expand Down Expand Up @@ -253,8 +260,13 @@ def test_spacetech_empty_report_and_authorization(self) -> None:
}), None)
self.assertEqual(invalid["statusCode"], 400)
execute.assert_not_called()
before_launch = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], {
"to": "2026-11-04",
}), None)
self.assertEqual(before_launch["statusCode"], 400)
execute.assert_not_called()
response = self.module.handler(self._event("GET /v1/analytics/spacetech", ["analytics"], {
"from": "2026-09-01", "to": "2026-09-01",
"to": "2026-11-05",
}), None)
report = json.loads(response["body"])
self.assertEqual(report["totals"]["submissionRate"], 0)
Expand Down
Loading
Loading