Learn Gatsby - Observability & Monitoring

#Introduction

Building the site is only half the job; keeping it healthy is the other half. Observability answers three questions: is the site fast, did the build succeed, and are users hitting errors.

Episode 22 covers performance monitoring with analytics, tracking build metrics and deployment status, error reporting for client-side interactions, and user behavior and performance monitoring.

#Monitoring Performance with Analytics

#Web Analytics

Analytics tools like Google Analytics 4 record visits, traffic sources, and user behavior. Integration in Gatsby uses the official plugin:

npm install gatsby-plugin-google-gtag

Add the plugin with a measurement ID:

Configure gatsby-plugin-google-gtag

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-google-gtag",
      options: {
        trackingIds: ["G-XXXXXXXXXX"],
        pluginConfig: { head: true },
      },
    },
  ],
}

A measurement ID like G-XXXXXXXXXX comes from the Google Analytics dashboard; never write a real value into code.

#Real User Monitoring

Traditional analytics records pages, not the actual experience. The web-vitals library measures LCP, INP, and CLS on real user devices, then sends the values to analytics:

Send Core Web Vitals

import { onCLS, onINP, onLCP } from "web-vitals"
 
const report = (metric) => {
  console.log(metric.name, metric.value)
}
 
onCLS(report)
onINP(report)
onLCP(report)

onLCP, onINP, and onCLS call the callback every time a metric is computed in the user's browser, giving you a picture of real performance rather than just an audit result.

#Build Metrics and Deployment Status

#Monitoring the Pipeline

Failed builds need to be known as soon as possible. GitHub Actions shows the status of every workflow, and platforms like Gatsby Cloud record build duration, bundle size, and the number of rebuilt pages.

#Lighthouse CI in the Pipeline

Run Lighthouse in CI to make sure performance metrics don't regress before merging:

npx lhci autorun --config=./lighthouserc.js

lhci autorun builds the site, runs Lighthouse, and compares the scores against the budget defined in lighthouserc.js. Regressions immediately block the pull request.

#Client-Side Error Reporting

#Sentry for JavaScript

Errors that happen in the user's browser never show up in server logs. Sentry captures them and sends full details — stack trace, browser, and the steps before the error:

npm install @sentry/gatsby

Initialize it in gatsby-browser:

Initialize Sentry

import * as Sentry from "@sentry/gatsby"
 
export const onClientEntry = () => {
  Sentry.init({
    dsn: process.env.GATSBY_SENTRY_DSN,
  })
}

onClientEntry runs once when the client app loads, making it the right place to initialize an error tracker.

#Error Boundaries

Beyond a global tracker, install an error boundary on the main components so the UI shows a clear message when a render fails, instead of a confusing white page.

#User Behavior and Performance Monitoring

#Event Tracking

Track important actions like button clicks or form submissions with event tracking. This data answers product questions, such as which page starts the most user journeys.

#Dashboards and Alerts

Gather all the metrics into a single dashboard: performance, builds, and errors. Set alerts for deviating values — rising LCP, slowing builds, or increasing error rates — so issues are handled before users complain.

#Conclusion

Key takeaways:

• Analytics records visits and user behavior.
• web-vitals measures performance on real user devices.
• Build status and duration are monitored in CI.
• Lighthouse CI prevents performance regressions from reaching production.
• Sentry captures client-side errors with full details.
• An integrated dashboard and alerts make early detection easier.

In the next episode, episode 23 — the final episode of this series — we'll discuss stable modern features and future trends, summarizing strategies to keep your Gatsby skills relevant in a constantly changing ecosystem.