New Relic and Subtext: From a Signal to the Session

New Relic tells you that something crossed a line: an issue opened, an error group grew, rage clicks climbed on a dashboard. It can’t tell you why one specific person was blocked. Subtext can. Attach the Subtext session URL to your browser events and every New Relic signal becomes a jumping-off point — 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. New Relic detects; Subtext diagnoses.

This guide assumes the Subtext capture snippet is installed and the New Relic browser agent is running — either the copy-paste snippet or the @newrelic/browser-agent npm package. Both expose the same newrelic global, so every call below works unchanged.

Attach the session URL

Store the current Subtext session URL on your New Relic browser data so it travels with the signal. There are three places to attach it, depending on how precise the link needs to be.

On every browser event

setCustomAttribute adds a name/value pair to subsequent events on the page. Pass true as the third argument and the pair is also written to browser storage, so later same-origin page loads in the same session re-apply it automatically. Call it wherever your app already identifies the user — on auth resolution, not at module top level.

const subtextUrl = FS('getSession', { format: 'url.now' })
if (subtextUrl) {
  newrelic.setCustomAttribute('subtext_url', subtextUrl, true)
  newrelic.setUserId(user.id)
}

useEffect(() => {
  if (!user) return
  FS('setIdentity', { uid: user.id, properties: { email: user.email } })
  const subtextUrl = FS('getSession', { format: 'url.now' })
  if (subtextUrl) {
    newrelic.setCustomAttribute('subtext_url', subtextUrl, true)
    newrelic.setUserId(user.id)
  }
}, [user])

The attribute lands on AjaxRequest, BrowserInteraction, BrowserPerformance, JavaScriptError, Log, PageAction, PageView, PageViewTiming, and UserAction — so a single call makes the session URL queryable from almost anywhere in NRQL. setUserId is worth pairing with it. It writes enduser.id on every event, persists across page loads on its own, and is attached to JavaScriptError specifically so Errors Inbox can group by user.

On a specific action

When the exact moment matters, attach the URL to a PageAction. url.now carries a timestamp, so the link opens the replay at that instant — ideal for high-signal moments like checkout failures and conversion drop-offs.

newrelic.addPageAction('checkout_failed', {
  reason: error.message,
  subtext_url: FS('getSession', { format: 'url.now' }),
})

On a handled error

For an error you catch yourself, pass the URL as a custom attribute on noticeError. It lands on the JavaScriptError event alongside the stack trace.

try {
  await submitPayment(payload)
} catch (err) {
  newrelic.noticeError(err, { subtext_url: FS('getSession', { format: 'url.now' }) })
}

Don’t read FS('getSession') at module top level — it returns null until the session has started. Custom attribute values must be simple types: string, number, boolean, or null. A session URL is a string, so it fits, but passing an object silently fails. To land the attribute on the PageView event specifically, set it before the window load event fires; that’s when PageView is transmitted. Avoid reserved NRQL words for attribute names. The persist argument needs browser agent v1.230.0 or higher.

From signal to session

However you first hear about a problem in New Relic, the path is the same: get to the subtext_url, then hand it to your agent for a Detect-vs-Diagnose read. New Relic tells you a threshold broke or an error group grew; the session tells you whether a real person was actually blocked, what they saw, and the precise sequence behind it.

A page at 2am from an open issue

An alert condition trips, New Relic opens an issue, and your workflow pages the on-call engineer: “Browser JS error rate above threshold on /checkout.”Open the issue, jump to the correlated events, and copy subtext_url from a representative one. Or run it directly in the query builder:

FROM JavaScriptError
SELECT subtext_url, `enduser.id`, errorMessage, pageUrl
WHERE pageUrl LIKE '%/checkout%' AND subtext_url IS NOT NULL
SINCE 30 minutes ago LIMIT 10

A New Relic issue paged me: browser JS error rate spiking on /checkout. Here's a session from
an affected user: <paste subtext_url>

It's 2am — I need signal fast. Open the session, give me a Detect-vs-Diagnose read. Is this a
real user-facing outage or noisy telemetry? What broke, what did the user see, and is it isolated
or systemic? One paragraph, plus the single most important screenshot.

An error group in Errors Inbox

Errors Inbox groups a recurring Uncaught TypeError across dozens of sessions and assigns it to you.Open the group and read subtext_url off several events — because you set enduser.id, you can also see how many distinct people hit it, not just how many events fired.

FROM JavaScriptError
SELECT uniqueCount(`enduser.id`), latest(subtext_url)
WHERE errorMessage LIKE '%Cannot read properties%'
FACET errorMessage SINCE 1 hour ago

New Relic Errors Inbox flagged a recurring error across ~60 sessions. Here are subtext_urls from
a sample: <paste 3–4 subtext_urls>

Review them together. What's the common trigger — same component, same API failure, same device?
Which sessions show the user actually stuck vs. recovered? Give me one root-cause hypothesis and a
go/no-go on whether this needs a hotfix tonight.

A rage-click sweep with no alert attached

Nothing paged you. You want to find the friction New Relic noticed but nobody thresholded.The browser agent classifies user actions on its own. rageClick, deadClick, and errorClick are plain boolean attributes on UserAction, so the sweep is one query:

FROM UserAction
SELECT session, subtext_url, currentUrl, actionName, deviceType
WHERE (rageClick IS true OR deadClick IS true OR errorClick IS true)
  AND subtext_url IS NOT NULL
SINCE 1 day ago LIMIT 50

New Relic flagged rage and dead clicks across these sessions: <paste 3–4 subtext_urls>

Open each one and tell me what the user was trying to do at the moment they started
clicking repeatedly. Is the control broken, mislabeled, or just slow? Rank the findings by how
many people this would affect.

New Relic session replay and Subtext do different jobs. Filter on hasReplay IS true AND subtext_url IS NOT NULL and you get sessions with both: a New Relic replay a person can watch, and a Subtext session your agent can read. For a postmortem, ask your agent to assemble a proof document (doc-create) with the key screenshots and the session link, then drop it into the incident channel so the metrics chart gets a human-impact caption.

For agents

An autonomous agent can run the whole loop against New Relic directly: discover the friction, extract the subtext_url, and hand each session to the Subtext MCP. New Relic hosts a first-party MCP server over Streamable HTTP at https://mcp.newrelic.com/mcp/ (US), https://mcp.eu.newrelic.com/mcp/ (EU), and https://mcp.jp.newrelic.com/mcp/ (JP). Authenticate with a user API key in an api-key header (NRAK-… format) or with OAuth. Clients that need stdio can bridge with npx mcp-remote.

New Relic’s MCP server accepts an include-tags header that filters which tools the agent sees. The available tags are discovery, data-access, alerting, incident-response, performance-analytics, and advanced-analysis. For the Subtext loop, include-tags: data-access,incident-response is enough — it trims the tool corpus to the ones below and leaves more room for the review itself.

Discover who is affected

execute_nrql_query is the core discovery tool — everything in the section above is one NRQL string. For grouped errors, list_entity_error_groups pulls Errors Inbox groups for an entity within a time window. list_recent_issues and search_incident cover open issues and alert events. generate_user_impact_report produces an end-user impact analysis for a specific issue, which is a natural place to hand off. natural_language_to_nrql_query writes and runs the query for you when you’d rather describe the question than compose NRQL.Without the MCP, the same over NerdGraph:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      nrql(query: "FROM UserAction SELECT subtext_url WHERE rageClick IS true SINCE 1 day ago") {
        results
      }
    }
  }
}

POST https://api.newrelic.com/graphql
# API-Key: NRAK-...   (api.eu.newrelic.com / api.jp.newrelic.com for other regions)

Extract the session URL

Because setCustomAttribute writes to every browser event type, one SELECT subtext_url does the job on whichever event carries the signal — JavaScriptError for errors, UserAction for friction, PageAction for the moments you instrumented yourself. Add WHERE subtext_url IS NOT NULL to skip sessions captured before the attribute was attached; inverting it to IS NULL surfaces your capture gaps.

Hand off to Subtext

For each URL, call review-open(session_url=<subtext_url>) on the Subtext MCP. PageAction and noticeError links are moment-precise, so the review opens exactly when the signal fired. For an incident, scope the NRQL to the incident window first, then review a session from inside the spike.

subtext_url only round-trips if it was attached at capture time (see Attach the session URL). Links set through addPageAction or noticeError are moment-precise; the persisted custom attribute opens at the moment the user was identified. UserAction events and the rageClick / deadClick / errorClick attributes require the Pro or Pro+SPA browser agent at v1.268.0 or higher — they are not reported by the Lite agent. Match your New Relic region (US/EU/JP) for the MCP endpoint and the NerdGraph host.

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

New Relic and Subtext: From a Signal to the Session

Attach the session URL

On every browser event

On a specific action

On a handled error

From signal to session

For agents

​Attach the session URL

​On every browser event

​On a specific action

​On a handled error

​From signal to session

​For agents

​Related

Attach the session URL

On every browser event

On a specific action

On a handled error

From signal to session

For agents

Related