Technology & EngineeringError Tracking Services258 lines

Highlight

Integrating Highlight.io for open-source session replay, error monitoring, and log management with full-stack observability

Quick Summary28 lines

You are an expert in integrating Highlight.io for error tracking and session replay.

## Key Points

- DOM mutations with pixel-perfect fidelity
- Console output
- Network requests with headers and bodies
- User interactions (clicks, scrolls, inputs)
- Errors with full stack traces
- Error count exceeds a threshold in a time window.
- New error types appear for the first time.
- Log patterns match specific queries.
- Session count drops (potential outage indicator).
- Configure `tracingOrigins` to match your API domains so frontend sessions are linked to backend logs and errors.
- Use `privacySetting: "strict"` for applications handling sensitive data, then selectively allow specific elements.
- Apply `highlight-mask` and `highlight-block` CSS classes to all forms handling PII, payment data, or health information.

## Quick Example

```bash
npm install highlight.run
```

```bash
npm install @highlight-run/react highlight.run
```

skilldb get error-tracking-services-skills/HighlightFull skill: 258 lines

Paste into your CLAUDE.md or agent config

Highlight.io — Error Tracking

You are an expert in integrating Highlight.io for error tracking and session replay.

Core Philosophy

Overview

Highlight.io is an open-source observability platform that combines session replay, error monitoring, and log management. It provides full-stack visibility by connecting frontend sessions to backend logs and errors. Being open-source, it can be self-hosted or used as a managed cloud service. Use Highlight.io when you want an open-source alternative to LogRocket/Sentry with unified session replay, errors, and logs.

Setup & Configuration

JavaScript Browser

npm install highlight.run

import { H } from "highlight.run";

H.init("YOUR_PROJECT_ID", {
  environment: "production",
  version: "1.2.0",
  networkRecording: {
    enabled: true,
    recordHeadersAndBody: true,
    urlBlocklist: [/\/health/],
  },
  tracingOrigins: ["api.example.com"],
});

React

npm install @highlight-run/react highlight.run

import { H } from "highlight.run";
import { ErrorBoundary } from "@highlight-run/react";

H.init("YOUR_PROJECT_ID", {
  environment: "production",
  version: "1.2.0",
});

const App = () => (
  <ErrorBoundary>
    <MyApp />
  </ErrorBoundary>
);

Next.js

npm install @highlight-run/next highlight.run

// next.config.js
const { withHighlightConfig } = require("@highlight-run/next/config");

module.exports = withHighlightConfig({
  // your next.js config
});

// app/layout.tsx
import { HighlightInit } from "@highlight-run/next/client";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <HighlightInit
          projectId="YOUR_PROJECT_ID"
          environment="production"
          tracingOrigins={["api.example.com"]}
        />
        {children}
      </body>
    </html>
  );
}

Node.js Backend

npm install @highlight-run/node

const { H } = require("@highlight-run/node");

H.init({ projectID: "YOUR_PROJECT_ID" });

// Consume errors
app.use((err, req, res, next) => {
  const { secureSessionId, requestId } = H.parseHeaders(req.headers);
  H.consumeError(err, secureSessionId, requestId);
  next(err);
});

Core Patterns

Error Capturing

// Errors are captured automatically (uncaught exceptions, unhandled rejections)

// Capture a caught error manually
try {
  riskyOperation();
} catch (error) {
  H.consumeError(error);
}

// Capture with a message
H.consumeError(error, "Payment processing failed");

Context and Breadcrumbs

// Track custom events (serves as breadcrumbs)
H.track("checkout_started", {
  cartItems: 3,
  cartTotal: 49.99,
});

// Add session metadata
H.getSessionURL().then((url) => {
  console.log("Session URL:", url);
});

User Identification

H.identify("user@example.com", {
  id: "user-42",
  name: "Jane Doe",
  plan: "enterprise",
});

Release Tracking

Set the version parameter in H.init(). Highlight correlates errors with versions automatically.

Source Maps

Highlight automatically fetches source maps from your deployed assets. For private source maps, upload them via the Highlight dashboard or use the CLI.

Advanced Features

Session Replay

Session replay is a core feature. Highlight records:

DOM mutations with pixel-perfect fidelity
Console output
Network requests with headers and bodies
User interactions (clicks, scrolls, inputs)
Errors with full stack traces

Sessions are searchable by user, error, URL, or custom property.

Privacy Controls

H.init("YOUR_PROJECT_ID", {
  privacySetting: "default", // "default", "strict", or "none"
});

<!-- Obfuscate specific elements -->
<div class="highlight-mask">Sensitive content</div>

<!-- Block recording entirely for an element -->
<div class="highlight-block">Credit card form</div>

Log Management

Highlight collects backend logs and correlates them with frontend sessions.

const { H } = require("@highlight-run/node");

// Logs are automatically associated with the active session
H.log("Order processed", "info", {
  orderId: "abc-123",
  total: 49.99,
});

Backend Tracing

const { H } = require("@highlight-run/node");

// Parse Highlight headers from incoming requests to link backend
// errors and logs to the frontend session
app.use((req, res, next) => {
  const { secureSessionId, requestId } = H.parseHeaders(req.headers);
  // secureSessionId links back to the frontend session
  next();
});

Alerting

Configure alerts in the Highlight dashboard:

Error count exceeds a threshold in a time window.
New error types appear for the first time.
Log patterns match specific queries.
Session count drops (potential outage indicator).

Best Practices

Configure tracingOrigins to match your API domains so frontend sessions are linked to backend logs and errors.
Use privacySetting: "strict" for applications handling sensitive data, then selectively allow specific elements.
Apply highlight-mask and highlight-block CSS classes to all forms handling PII, payment data, or health information.
Set version to your git SHA or semantic version for release-correlated error tracking.
Use the log management feature to centralize backend logs alongside frontend errors for unified debugging.

Common Pitfalls

Not configuring tracingOrigins, losing the connection between frontend sessions and backend errors/logs.
Setting privacySetting: "none" in production, recording all user input including sensitive data.
Forgetting to call H.identify() after login, making it hard to find sessions for specific users.
Not using H.parseHeaders() in backend middleware, breaking the frontend-to-backend session correlation.
Recording networkRecording.recordHeadersAndBody without sanitizing auth tokens from request headers.

Anti-Patterns

Over-engineering for hypothetical scale. Building for millions of users when you have hundreds adds complexity without value. Solve today's problems first.

Ignoring the existing ecosystem. Reinventing functionality that mature libraries already provide well wastes time and introduces unnecessary risk.

Premature abstraction. Creating elaborate frameworks and utilities before you have enough concrete cases to know what the abstraction should look like produces the wrong abstraction.

Neglecting error handling at boundaries. Internal code can trust its inputs, but system boundaries (user input, APIs, file I/O) require defensive validation.

Skipping documentation for obvious code. What is obvious to you today will not be obvious to your colleague next month or to you next year.

Install this skill directly: skilldb add error-tracking-services-skills

Get CLI access →