Every production issue starts the same way.
Someone reports that something is broken.
The first thirty minutes aren't spent fixing it. They're spent figuring out what actually happened.
Which users were affected?
When did it start?
Was it the latest deployment?
Can anyone reproduce it?
Monitoring shouldn't stop at telling you something is wrong. It should help you understand why it's happening and give you enough context to fix it.
In this guide, we'll set up HeronSignal from scratch and walk through the features that help you move from detecting an issue to actually resolving it.
Step 1: Connect Your Domain
Before your application can send data, tell HeronSignal which domains belong to your project.
Open Domains from your dashboard and add every origin where your application runs. Most teams will at least add their production and staging environments.
Keeping environments separate makes it much easier to test new releases without mixing test traffic with production data.
Step 2: Install the Tracker
Install the Web SDK.
Create a provider.
"use client";
import { useEffect } from "react";
import { initHeronSignal } from "@heronsignal/web";
export function HeronSignalProvider() {
useEffect(() => {
void initHeronSignal({
publicKey: "YOUR_PUBLIC_KEY",
service: "storefront",
environment: "production",
});
}, []);
return null;
}
Mount it inside your root layout.
That's it.
From this point, HeronSignal starts collecting production signals automatically.
Step 3: Verify Everything Is Working
Open your website.
Browse a few pages.
Click buttons.
Fill in a form.
Use the application exactly like one of your users would.
Return to the dashboard.
Within a few moments you should start seeing activity.
What You Can Do Next
Installing the SDK unlocks the platform, but each feature solves a different problem.
Here's a quick tour.
Insights
Need a quick overview of your application's health?
Insights shows visitor activity, page views, and performance trends, with breakdowns by browser, country, and device.
Instead of guessing whether an issue affects everyone or just a subset of users, you can immediately see where the impact is happening.
Sessions
Sometimes a stack trace isn't enough.
Sessions let you replay exactly what a user experienced before an issue occurred.
Instead of asking users how they reproduced a bug, you can watch the journey yourself.
Logger
Logs become much more useful when they're searchable.
Attach structured attributes to your logs.
log("warn", "Checkout retry", {
step: "payment",
plan: "pro"
});
Later, search directly for:
@step:payment
@plan:pro
instead of scrolling through hundreds of plain-text messages.
Health Checks
Some pages are too important to fail silently.
Health Checks continuously monitor critical endpoints like your homepage, login page, or checkout.
If something goes down, HeronSignal alerts you.
When it recovers, you'll know that too.
Funnels
Monitoring tells you when something breaks.
Funnels tell you where users stop progressing.
Build journeys such as:
Landing Page
↓
Signup Started
↓
Signup Completed
event("landing_page_viewed");
event("signup_started");
event("signup_completed", {
plan: "pro"
});
You'll immediately see conversion rates, drop-off points, and trends over time.
AI Analysis
Once production data starts flowing, AI Analysis helps prioritize what deserves attention first.
Instead of looking through every dashboard yourself, AI reviews the available signals and surfaces the issues with the greatest impact.
For example, it might highlight:
LCP regression on the pricing page
Checkout failures
Slow cart API responses
Helping you decide where to begin instead of where to click next.
Connect Your Coding Agent
When you're debugging a production issue, one of the biggest frustrations is giving your AI assistant enough context.
You copy an error message, paste a stack trace, explain what the user experienced, attach screenshots, and hope it has enough information to help.
With HeronSignal's MCP integration, your coding agent can access live production context directly.
Instead of working from code alone, tools like Cursor, Claude, or Codex can understand what's happening in your application while helping you investigate an issue.
Connecting your coding agent only takes a few minutes. Create an MCP token from your HeronSignal dashboard, then add it to your AI client.
{
"HeronSignal": {
"url": "https://api.heronsignal.com/mcp?workspaceId=YOUR_WORKSPACE_ID",
"headers": {
"Authorization": "Bearer paste-token-shown-once"
}
}
}
By default, MCP tokens are read-only, allowing your coding agent to safely inspect production context without modifying anything.
If you want your agent to help create Funnels, you can enable Funnel write permissions when generating the token.
Complete the Setup
Before you finish, make sure you've completed these final steps:
Add every production and staging domain from Domains.
Visit your website and interact with it like a real user.
Return to the dashboard and verify that data is appearing in Insights, Sessions, Logger, Funnels, and AI Analysis.
At this point, your HeronSignal setup is complete.
Imagine a customer reports that checkout feels slower than usual.
You open Insights and notice a performance regression.
A Session Replay shows exactly what the customer experienced.
Logger helps you search related logs using structured attributes.
AI Analysis highlights the issue affecting the most users, and your coding agent already has the production context needed to investigate further.
That's the workflow you've just built.
From installation to investigation, HeronSignal gives your team the visibility and context needed to understand production faster and spend more time solving problems.
Top comments (1)
Great article! I like the way you described the problem at the beginning of it