Automatic instrumentation

View Markdown

Honeybadger Insights can capture inbound HTTP requests from your Node.js and serverless applications and make them available for querying, visualization, and dashboards.

Insights instrumentation is off by default. Enable it in your Honeybadger configuration:

Honeybadger.configure({
  apiKey: process.env.HONEYBADGER_API_KEY,
  insights: {
    enabled: true,
    http: true,
    console: false,
  },
});

insights.enabled is the master switch. Without it, http and console are ignored.
insights.http records a request.handled event for each inbound request when your framework integration is installed.
insights.console forwards console logs to Insights. See Capturing logs.

You can also tune how events are delivered:

Honeybadger.configure({
  events: {
    // How often to flush buffered events (default: 10)
    dispatchIntervalSeconds: 10,
    // Flush when this many events are buffered (default: 500)
    bulkThreshold: 500,
    // Percentage of events to send (default: 100)
    sampleRatePercentage: 100,
  },
});

See Sampling events for details on sampleRatePercentage.

The `request.handled` event

When HTTP instrumentation is enabled, each completed request emits a request.handled event with these fields (when available):

Field	Description
`method`	HTTP method (for example, `GET`, `POST`)
`path`	Request path
`route`	Matched route pattern, when the framework provides one
`status`	Response status code
`duration`	Request duration in milliseconds
`request_id`	Unique ID for this request
`correlation_id`	ID that may span related requests

See the JavaScript event reference for every event type and field schema.

On Node.js runtimes, request_id and correlation_id are stored on the request’s event context and merged onto every event emitted during that request, including programmatic Honeybadger.event() calls.

Request and correlation ID precedence

Request ID: x-request-id header → request-id header → generated UUID
Correlation ID: x-correlation-id header → x-amzn-trace-id header → falls back to the request ID

Both fields are always populated. When no headers are present, request_id and correlation_id are the same generated value.

For AWS Lambda non-HTTP triggers (SQS, S3, EventBridge, and similar), request_id is the Lambda awsRequestId, and correlation_id is _X_AMZN_TRACE_ID when set, otherwise the request ID.

Framework setup

Express

Use the existing Honeybadger.requestHandler middleware. It seeds request context on every request and emits request.handled when insights.http is enabled:

const Honeybadger = require("@honeybadger-io/js");

Honeybadger.configure({
  apiKey: process.env.HONEYBADGER_API_KEY,
  insights: {
    enabled: true,
    http: true,
  },
});

const app = express();

app.use(Honeybadger.requestHandler);
// ... your routes ...
app.use(Honeybadger.errorHandler);

Fastify

Install the optional peer packages, then register the Fastify plugin from its deep import path (it is not exported from the main @honeybadger-io/js entry):

npm install fastify-plugin

fastify (>= 4) and fastify-plugin (>= 4) are optional peer dependencies of @honeybadger-io/js.

const Honeybadger = require("@honeybadger-io/js");
const { fastifyPlugin } = require("@honeybadger-io/js/dist/server/fastify");

Honeybadger.configure({
  apiKey: process.env.HONEYBADGER_API_KEY,
  insights: {
    enabled: true,
    http: true,
  },
});

fastify.register(fastifyPlugin(Honeybadger));

AWS Lambda

Instrumentation is automatic when you wrap your handler with Honeybadger.lambdaHandler. HTTP-shaped events (API Gateway v1/v2 and ALB) emit request.handled when insights.http is enabled. The wrapper flushes buffered events before the Lambda execution environment freezes:

const Honeybadger = require("@honeybadger-io/js");

Honeybadger.configure({
  apiKey: process.env.HONEYBADGER_API_KEY,
  insights: {
    enabled: true,
    http: true,
  },
});

exports.handler = Honeybadger.lambdaHandler(async (event, context) => {
  return { statusCode: 200, body: "OK" };
});

Next.js

For App Router route handlers, Pages Router API routes, middleware, and edge handlers, wrap with withHoneybadger from @honeybadger-io/nextjs. See the Next.js integration guide for configuration details, including the requirement to pass config explicitly to API and edge handlers.

Managing event volume

If some events are noisy or you’d like to reduce quota consumption:

Filtering events: inspect, modify, or drop events with a callback.
Sampling events: send only a percentage of events.

Sending your own events

Automatic instrumentation covers HTTP requests the client knows about. To send your own application events, see Sending custom events.