Node.js

Node.js SDK for ClickStack - The ClickHouse Observability Stack

ClickStack uses the OpenTelemetry standard for collecting telemetry data (logs, metrics, traces and exceptions). Traces are auto-generated with automatic instrumentation, so manual instrumentation isn’t required to get value out of tracing.

This guide integrates:

• Logs
• Metrics
• Traces
• Exceptions

Getting started

Install HyperDX OpenTelemetry instrumentation package

Use the following command to install the ClickStack OpenTelemetry package.

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

Initializing the SDK

To initialize the SDK, you’ll need to call the init function at the top of the entry point of your application.

require

const HyperDX = require('@hyperdx/node-opentelemetry');

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omit for Managed ClickStack
    service: 'my-service'
});

import

import * as HyperDX from '@hyperdx/node-opentelemetry';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omit for Managed ClickStack
    service: 'my-service'
});

This will automatically capture tracing, metrics, and logs from your Node.js application.

Setup log collection

By default, console.* logs are collected by default. If you’re using a logger such as winston or pino, you’ll need to add a transport to your logger to send logs to ClickStack. If you’re using another type of logger, reach out or explore one of our platform integrations if applicable (such as Kubernetes).

Winston

If you’re using winston as your logger, you’ll need to add the following transport to your logger.

    import winston from 'winston';
    import * as HyperDX from '@hyperdx/node-opentelemetry';

    const logger = winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      transports: [
        new winston.transports.Console(),
        HyperDX.getWinstonTransport('info', { // Send logs info and above
          detectResources: true,
        }),
      ],
    });

    export default logger;

Pino

If you’re using pino as your logger, you’ll need to add the following transport to your logger and specify a mixin to correlate logs with traces.

import pino from 'pino';
import * as HyperDX from '@hyperdx/node-opentelemetry';

const logger = pino(
    pino.transport({
    mixin: HyperDX.getPinoMixinFunction,
    targets: [
        HyperDX.getPinoTransport('info', { // Send logs info and above
        detectResources: true,
        }),
    ],
    }),
);

export default logger;

console.log

By default, console.* methods are supported out of the box. No additional configuration is required.

You can disable this by setting the HDX_NODE_CONSOLE_CAPTURE environment variable to 0 or by passing consoleCapture: false to the init function.

Setup error collection

The ClickStack SDK can automatically capture uncaught exceptions and errors in your application with full stack trace and code context.

To enable this, you’ll need to add the following code to the end of your application’s error handling middleware, or manually capture exceptions using the recordException function.

Express

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omit for Managed ClickStack
    service: 'my-service'
});
const app = express();

// Add your routes, etc.

// Add this after all routes,
// but before any and other error-handling middlewares are defined
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

Koa

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omit for Managed ClickStack
    service: 'my-service'
});

const router = new Router();
const app = new Koa();

HyperDX.setupKoaErrorHandler(app);

// Add your routes, etc.

app.listen(3030);

Manual

const HyperDX = require('@hyperdx/node-opentelemetry');

function myErrorHandler(error, req, res, next) {
    // This can be used anywhere in your application
    HyperDX.recordException(error);
}

Troubleshooting

If you’re having trouble with the SDK, you can enable verbose logging by setting the OTEL_LOG_LEVEL environment variable to debug.

export OTEL_LOG_LEVEL=debug

Advanced instrumentation configuration

Capture console logs

By default, the ClickStack SDK will capture console logs. You can disable it by setting HDX_NODE_CONSOLE_CAPTURE environment variable to 0.

copy

export HDX_NODE_CONSOLE_CAPTURE=0

Attach user information or metadata

To easily tag all events related to a given attribute or identifier (ex. user id or email), you can call the setTraceAttributes function which will tag every log/span associated with the current trace after the call with the declared attributes. It’s recommended to call this function as early as possible within a given request/trace (ex. as early in an Express middleware stack as possible).

This is a convenient way to ensure all logs/spans are automatically tagged with the right identifiers to be searched on later, instead of needing to manually tag and propagate identifiers yourself.

userId, userEmail, userName, and teamName will populate the sessions UI with the corresponding values, but can be omitted. Any other additional values can be specified and used to search for events.

import * as HyperDX from '@hyperdx/node-opentelemetry';

app.use((req, res, next) => {
  // Get user information from the request...

  // Attach user information to the current trace
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

Make sure to enable beta mode by setting HDX_NODE_BETA_MODE environment variable to 1 or by passing betaMode: true to the init function to enable trace attributes.

export HDX_NODE_BETA_MODE=1

Google Cloud Run

If you’re running your application on Google Cloud Run, Cloud Trace automatically injects sampling headers into incoming requests, currently restricting traces to be sampled at 0.1 requests per second for each instance.

The @hyperdx/node-opentelemetry package overwrites the sample rate to 1.0 by default.

To change this behavior, or to configure other OpenTelemetry installations, you can manually configure the environment variables OTEL_TRACES_SAMPLER=parentbased_always_on and OTEL_TRACES_SAMPLER_ARG=1 to achieve the same result.

To learn more, and to force tracing of specific requests, please refer to the Google Cloud Run documentation.

Auto-instrumented libraries

The following libraries will be automatically instrumented (traced) by the SDK:

• dns
• express
• graphql
• hapi
• http
• ioredis
• knex
• koa
• mongodb
• mongoose
• mysql
• mysql2
• net
• pg
• pino
• redis
• winston

Alternative installation

Run the Application with ClickStack OpenTelemetry CLI

Alternatively, you can auto-instrument your application without any code changes by using the opentelemetry-instrument CLI or using the Node.js --require flag. The CLI installation exposes a wider range of auto-instrumented libraries and frameworks.

Using NPX

Managed ClickStack

The HYPERDX_API_KEY can be omitted for Managed ClickStack.

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

Custom Entry Point (ex. Nodemon, ts-node, etc.)

Managed ClickStack

The HYPERDX_API_KEY can be omitted for Managed ClickStack.

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js

Code Import

// Import this at the very top of the first file loaded in your application
// You'll still specify your API key via the `HYPERDX_API_KEY` environment variable
import { initSDK } from '@hyperdx/node-opentelemetry';

initSDK({
    consoleCapture: true, // optional, default: true
    additionalInstrumentations: [], // optional, default: []
});

The OTEL_SERVICE_NAME environment variable is used to identify your service in the HyperDX app, it can be any name you want.

Enabling exception capturing

To enable uncaught exception capturing, you’ll need to set the HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE environment variable to 1.

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

Afterwards, to automatically capture exceptions from Express, Koa, or to manually catch exceptions, follow the instructions in the Setup Error Collection section above.

Auto-instrumented libraries

The following libraries will be automatically instrumented (traced) via the above installation methods:

• amqplib
• AWS Lambda Functions
• aws-sdk
• bunyan
• cassandra-driver
• connect
• cucumber
• dataloader
• dns
• express
• fastify
• generic-pool
• graphql
• grpc
• hapi
• http
• ioredis
• knex
• koa
• lru-memoizer
• memcached
• mongodb
• mongoose
• mysql
• mysql2
• nestjs-core
• net
• pg
• pino
• redis
• restify
• socket.io
• winston