Node.JS SDK API Reference

Node.js SDK

Highlight's Node.js SDK makes it easy to monitor errors and metrics on your Node.js backend.

Just getting started?

Check out our getting started guide to get up and running quickly.

H.init

H.init() initializes the Highlight backend SDK. If you are not using any of the provided handlers for Express, it is required to call this method before recording backend errors or metrics.

Method Parameters


  import { H } from "@highlight-run/node";

  if (!H.isInitialized()) {
    H.init({
      projectID: "<YOUR_PROJECT_ID>",
      serviceName: "my-node-app",
      serviceVersion: "git-sha",
    });
  }

H.isInitialized

H.isInitialized() returns true if the Highlight backend SDK has been initialized. This may be handy if your initialization code could be called multiple times, e.g. if it is called conditionally from a request handler when a backend error or metric needs to be recorded.


  import { H } from "@highlight-run/node";

  if (!H.isInitialized()) {
    H.init({
      projectID: "<YOUR_PROJECT_ID>",
      serviceName: "my-node-app",
      serviceVersion: "git-sha",
    });
  }

H.consumeError

H.consumeError() reports an error and its corresponding stack trace to Highlight. The secureSessionId and requestId properties are Highlight ids used to link an error to the session in which the error was thrown. These properties are sent via a header and included in every request to your backend once the Highlight client is initialized. They can be parsed using the H.parseHeaders() helper method.

Method Parameters

import * as http from 'http';
import { H } from "@highlight-run/node";

const onError = (request: http.IncomingMessage, error: Error): void => {
  const parsed = H.parseHeaders(request.headers);
  if (parsed !== undefined) {
    H.consumeError(error, parsed.secureSessionId, parsed.requestId, {"url": request.url})
  }
};

H.recordMetric

H.recordMetric() reports a metric to Highlight. Backend metrics can be used just like frontend metrics for creating custom dashboards.

Method Parameters


import { H } from "@highlight-run/node";

const handler = (request) => {
  const parsed = H.parseHeaders(request.headers);
  const start = Date.now();
  doInterestingWork();
  const elapsed = Date.now() - start;
  H.recordMetric(parsed.secureSessionId, "elapsedTimeMs", elapsed, parsed.requestId, ["user": "Zane"]);
};

H.parseHeaders

H.parseHeaders() is a helper function for extracting the Highlight secureSessionId and requestId from network requests. These fields are sent with network requests as the 'x-highlight-request' header, encoded as a slash-separated string: "{secureSessionId}/{requestId}"

Method Parameters

import * as http from "http";
import { H } from "@highlight-run/node";

const onError = (request: http.IncomingMessage, error: Error): void => {
  const parsed = H.parseHeaders(request.headers);
  if (parsed !== undefined) {
    H.consumeError(error, parsed.secureSessionId, parsed.requestId)
  }
};

H.runWithHeaders

H.runWithHeaders() wraps its callback with a span named highlight-ctx, and spreads Highlight's secureSessionId and requestId across all spans with matching a traceId.

Method Parameters

Method Return

import * as http from "http";
import { H } from "@highlight-run/node";

const onError = async (request: http.IncomingMessage, error: Error): void => {
const callbackResult = await H.runWithHeaders<ReturnType>(req.headers, async () => {
    const span = await H.startActiveSpan("custom-span-name", {});
    // do work
    span.end();
  });
};

H.startActiveSpan

H.startActiveSpan() returns a Promise, which resolves to a span that carries all of the current Open Telemetry context as its parent span.

Method Parameters

Method Return

import * as http from "http";
import { H } from "@highlight-run/node";

const span = await H.startActiveSpan("custom-span-name", {});
    // do work
    span.end();
});

H.waitForFlush

H.waitForFlush() waits for spans to be added to the queue and for the queue to empty.

Method Parameters

Method Return

import * as http from "http";
import { H } from "@highlight-run/node";

const span = await H.startActiveSpan('my-custom-span-name');

// do work

span.end();

await H.waitForFlush(['my-custom-span-name']);