Monitoring with Highlight.io
Relevant source files
The following files were used as context for generating this wiki page:
The Heyme application integrates Highlight.io for comprehensive monitoring, session replay, and error tracking. This integration covers both the client-side Next.js application and the server-side API endpoints, providing full-stack visibility into application performance and user sessions. The implementation relies on the @highlight-run/next package.
The primary goal of this integration is to capture runtime errors, monitor API health, and understand user interactions to improve the reliability and user experience of the "message your future self" service.
Sources: README.md, package.json:10, highlight.config.ts, pages/_app.tsx, pages/api/dispatch.ts
Core Configuration
The monitoring setup is centered around a dedicated configuration file and a specific dependency in the project.
Sources: highlight.config.ts, package.json
Dependency
The project includes the official Highlight.io package for Next.js applications.
| Dependency | Version | Purpose |
|---|---|---|
@highlight-run/next | ^2.2.2 | Enables Highlight.io in a Next.js app |
Sources: package.json:10
Project Initialization
A specific project ID from Highlight.io is used to associate the application's monitoring data with the correct account. This is configured in highlight.config.ts, which exports a withHighlight higher-order component (HOC).
// highlight.config.ts:1-3
import { Highlight } from '@highlight-run/next'
export const withHighlight = Highlight({ projectID: '4d7zk0eo' })
This withHighlight HOC is the primary mechanism for wrapping API routes to enable backend monitoring.
Sources: highlight.config.ts:1-3
Frontend Integration
Client-side monitoring is initialized in the main application component, _app.tsx. This ensures that Highlight's tracking script is loaded for all pages.
Sources: pages/_app.tsx
Initialization in _app.tsx
The H.init() function is called with the project ID, which starts the process of session recording and error capture on the user's browser.
// pages/_app.tsx:5,14
import { H } from 'highlight.run'
// ...
H.init('4d7zk0eo')
The following diagram illustrates the client-side initialization sequence.
This diagram shows how the main App component triggers Highlight.io initialization.
Sources: pages/_app.tsx:5,14
Backend API Integration
Server-side monitoring is achieved by wrapping API route handlers with the withHighlight HOC imported from the configuration file.
Sources: pages/api/dispatch.ts, highlight.config.ts
Wrapping API Routes
The /api/dispatch endpoint, which is responsible for sending scheduled emails, is wrapped to monitor its execution, capture any errors, and log relevant data. The handler function handleDispatchEmails is passed to withHighlight.
// pages/api/dispatch.ts:6,76
import { withHighlight } from '../../highlight.config'
// ... function handleDispatchEmails ...
export default withHighlight(handleDispatchEmails)
This integration ensures that any issues during the email dispatch process, such as database connection failures or errors with the Zeptomail API, are captured by Highlight.io.
The data flow for a request to a monitored API endpoint is shown below.
This flowchart depicts how the withHighlight wrapper intercepts the request flow to send monitoring data.
Sources: pages/api/dispatch.ts:6,35,76
Summary
The Heyme application uses Highlight.io as a full-stack monitoring solution. On the frontend, it is initialized in _app.tsx to capture user sessions and client-side errors. On the backend, the withHighlight HOC wraps API routes like /api/dispatch to provide server-side error tracking and performance monitoring. This dual approach gives developers a complete picture of the application's health and user experience.
Sources: pages/_app.tsx, pages/api/dispatch.ts, highlight.config.ts