Snowplow and Subtext: From a Signal to the Session

Snowplow tells you that something moved in your behavioral data: a step-completion rate slips below trend, an event fires at an implausible rate, a batch of events fails schema validation. It can’t show you what one specific person saw. Subtext can. Attach the Subtext session URL to every Snowplow event as a custom entity and it flows through the pipeline into your warehouse, so any event you model there deep-links back to the matching session — your agent reads the subtext_url, opens that person’s real session, and walks the decisive moments with screenshots, the component tree, network, and console. Snowplow detects; Subtext diagnoses.

This guide assumes the Subtext capture snippet is installed and capturing sessions, and a Snowplow web tracker is running — either the tag (window.snowplow(...)) or the npm @snowplow/browser-tracker. The examples query ClickHouse — which Snowplow feeds via its Snowbridge stream forwarder or via the Lake Loader’s Iceberg/Delta output, not a dedicated loader — but any of Snowplow’s supported loader targets (Snowflake, Databricks, BigQuery, Redshift) works the same way; only the entity-column syntax differs.

Attach the session URL

Snowplow attaches extra data to events as entities (custom contexts), each validated against a schema. The cleanest way to add one value to every event is a global context — define it once and the tracker sends it with every subsequent event, no per-call wiring.

Define the entity schema

Entities are schema-validated, so first add a self-describing schema to your Iglu registry. A minimal one holds a single URL:

{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "self": {
    "vendor": "com.yourco",
    "name": "subtext_session",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "type": "object",
  "properties": { "url": { "type": "string", "maxLength": 4096 } },
  "required": ["url"],
  "additionalProperties": false
}

Attach it as a dynamic global context

The session URL changes across sessions and carries a per-moment timestamp, so use a context generator (a function) rather than a static object. The tracker runs it for every event, reading the URL fresh, and skips the entity when there is no session yet by returning undefined. Register it once, after the tracker is initialized — every trackPageView, trackSelfDescribingEvent, and built-in event fired afterward carries the entity.

import { addGlobalContexts } from '@snowplow/browser-tracker'

addGlobalContexts([
  () => {
    const url = FS('getSession', { format: 'url.now' })
    if (!url) return undefined // no session yet — attach nothing
    return {
      schema: 'iglu:com.yourco/subtext_session/jsonschema/1-0-0',
      data: { url },
    }
  },
])

window.snowplow('addGlobalContexts', [
  function () {
    var url = FS('getSession', { format: 'url.now' })
    if (!url) return undefined
    return { schema: 'iglu:com.yourco/subtext_session/jsonschema/1-0-0', data: { url: url } }
  },
])

Where it lands in the warehouse

Snowplow shreds each entity into its own column or table named from the schema — for the schema above, a column like contexts_com_yourco_subtext_session_1, an array whose first element holds { "url": "..." }. Query the URL out of that path (ClickHouse example):

SELECT
    user_id,
    contexts_com_yourco_subtext_session_1[1].url AS subtext_url,
    event_name,
    collector_tstamp
FROM atomic.events
WHERE event_name = 'checkout_error'
  AND length(contexts_com_yourco_subtext_session_1) > 0
ORDER BY collector_tstamp DESC
LIMIT 20;

The exact column path depends on your loader; check your atomic schema for the shredded entity name.

Don’t read FS('getSession') at module top level — it returns null until the session has started; the generator runs per event, which is exactly when a session exists. Don’t attach the URL as a static global context object, which would freeze the value at registration time — use the generator so each event gets the current, moment-linked URL. Don’t skip the schema step — an entity that fails validation lands in your failed events stream, not your warehouse. And don’t put the signed URL anywhere untrusted readers can reach it; it grants replay access.

From signal to session

However you first hear about a problem in Snowplow — a modeled behavioral table, a Failed Events alert, a data-quality check — the path is the same: get to the subtext_url on the affected rows, then hand it to your agent for a Detect-vs-Diagnose read. The atomic events say a user errored or dropped; the session shows what they actually experienced.

A behavioral model flags a friction point

An analytics engineer or PM reviewing a dbt-modeled funnel built on Snowplow atomic events notices a step-completion rate falling below trend for a specific event.Query the modeled table (or atomic.events) for the affected users’ sessions and read subtext_url off the shredded entity column:

SELECT user_id, contexts_com_yourco_subtext_session_1[1].url AS subtext_url, collector_tstamp
FROM atomic.events
WHERE event_name = 'checkout_step_completed'
  AND length(contexts_com_yourco_subtext_session_1) > 0
  AND user_id IN (<dropped users>)
ORDER BY collector_tstamp DESC
LIMIT 20;

Grab a few, then hand them to your agent:

Our Snowplow-modeled checkout funnel shows a step converting below trend. Here are session URLs for
users who dropped at that step:
<PASTE 3-4 subtext_urls>

Review them and find the common failure point. Detect-vs-Diagnose: the data says they dropped — what
does each session actually show at that step? One synthesized hypothesis at the end.

A Failed Events alert

The data engineer who owns tracking quality sees Snowplow’s Failed Events stream spike — events failing schema validation, which usually means a broken client, not just bad instrumentation.Successful events from the same users still carry the entity, so find a recent good event for an affected user and read its subtext_url.

Snowplow Failed Events spiked for `checkout_step_completed` from the web client. Here's a session
from an affected user around that time: <PASTE subtext_url>

Open it and tell me whether the client is genuinely broken (bad state, JS error) or the payload is
just mis-shaped. Show me the UI and console at that moment so I can tell a real bug from a schema drift.

A self-describing event looks wrong

A product analyst investigating a custom event finds a self-describing event firing at an implausible rate or with odd properties.Filter atomic.events to that event schema and pull the session link.

This custom event is firing far more than expected. Here's a session where it happened:
<PASTE subtext_url>

Open it around that event. Is the user really doing this, or is the client double-firing? Walk me
through the relevant moments.

For a funnel investigation across several dropped users, ask your agent to consolidate the findings into one proof document (doc-create) — a screenshot per session and a single shareable link — then drop it into the model’s documentation or the data-quality ticket so the next person sees the human story behind the number.

For agents

An autonomous agent can run the whole loop, but not against Snowplow directly. Snowplow is a pipeline, not a query product: Snowplow’s official MCP server works against the Snowplow Console — tracking plans, pipeline health, and failed-event investigation — not your event data, and querying the collector or enrichment stack is not the path. Snowplow’s value is that it lands clean, modeled events in your warehouse, so the agent story runs through the warehouse’s MCP.

If that warehouse is ClickHouse, use the official mcp-clickhouse server (list_databases, list_tables, run_query, read-only by default).
For Snowflake, BigQuery, or Redshift, use that warehouse’s own MCP or SQL API. The query shape is identical; only the entity-column syntax differs.

Discover and extract in one query

The shredded entity column returns both the friction and the link on the same rows, so a single query does discovery and extraction together:

-- worst-converting checkout step in the last week, with a session per dropped user
SELECT
    user_id,
    contexts_com_yourco_subtext_session_1[1].url AS subtext_url,
    collector_tstamp
FROM atomic.events
WHERE event_name = 'checkout_step_completed'
  AND collector_tstamp > now() - INTERVAL 7 DAY
  AND length(contexts_com_yourco_subtext_session_1) > 0
ORDER BY collector_tstamp DESC
LIMIT 25;

Hand off to Subtext

For each URL, call review-open(session_url=<subtext_url>) on the Subtext MCP and get a Detect-vs-Diagnose read: the model says they dropped versus what the session actually shows.

The entity only round-trips if the tracker attached it at capture (see Attach the session URL); events fired before you registered the global context carry an empty array, so filter length(...) > 0. The shredded column name is derived from your schema’s vendor, name, and version — confirm it against your atomic schema before hard-coding it. Keep the warehouse MCP read-only; a review agent never needs write access.

Session Review overview — what your agent does once a session is open.
Install the capture snippet — required before any session URL exists to attach.

Get Started

Install by Framework

Session Review

Privacy

Integrations

Recipes

API reference

Snowplow and Subtext: From a Signal to the Session

Attach the session URL

Define the entity schema

Attach it as a dynamic global context

Where it lands in the warehouse

From signal to session

For agents

​Attach the session URL

​Define the entity schema

​Attach it as a dynamic global context

​Where it lands in the warehouse

​From signal to session

​For agents

​Related

Attach the session URL

Define the entity schema

Attach it as a dynamic global context

Where it lands in the warehouse

From signal to session

For agents

Related