Node.js

The ClickStack Node.js SDK builds on the upstream OpenTelemetry SDK and auto-instrumentations. It adds console capture, uncaught exception capture, and telemetry flushing during shutdown. Applications that already configure OpenTelemetry can continue using their existing SDK and configure OTLP export.

Install

Use Node.js 22.15 or later. Install the SDK in your application:

npm install @clickhouse/clickstack-node

The package supports ES modules and CommonJS. npm installs its @opentelemetry/api peer dependency automatically. If your application imports that package directly, install @opentelemetry/api@~1.9.1; version 1.10 is outside this SDK’s supported range.

Configure your destination

Set the environment variables before starting your application. Use a base OTLP HTTP endpoint without /v1/traces, /v1/logs, or /v1/metrics; exporters append those paths.

Fully managed
Self-managed

Open Team Settings → Data → Managed Telemetry and copy the OTLP HTTP endpoint and API key. Use the exact HTTPS endpoint and port shown for your service:

export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer%20YOUR_INGESTION_API_KEY'
export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
export OTEL_SERVICE_NAME='my-node-app'

Use your collector’s OTLP HTTP endpoint and the ingestion key configured for its OTLP receiver. For collector setup, see Ingesting with OpenTelemetry.

export OTEL_EXPORTER_OTLP_ENDPOINT='http://localhost:4318'
export OTEL_EXPORTER_OTLP_HEADERS='authorization=YOUR_INGESTION_API_KEY'
export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
export OTEL_SERVICE_NAME='my-node-app'

This endpoint assumes the application and collector run on the same host. Replace it with an address reachable from your application when the collector runs elsewhere.

Start your application

Preload the SDK before your application imports the libraries it instruments:

node --import @clickhouse/clickstack-node/register server.js

Replace server.js with your application’s entry file. This command loads the SDK before your application starts and uses the environment variables configured above. It supports CommonJS and ES module applications. You can now verify ingestion. The alternatives below are only needed if you want to start through an npm script or configure the SDK in code.

Alternative startup methods

--require is also supported. If you use NODE_OPTIONS, scope it to the application command so build tools do not start their own telemetry pipelines:

NODE_OPTIONS='--import @clickhouse/clickstack-node/register' npm start

Alternatively, create an instrumentation module and preload it. The environment variables from the previous section still configure export:

// instrumentation.mjs
import { isMainThread } from 'node:worker_threads';
import { init } from '@clickhouse/clickstack-node';

if (isMainThread) {
  init();
}

node --import ./instrumentation.mjs server.mjs

The guard prevents worker threads, such as Pino transport workers, from starting additional SDK instances.Use either the package’s registration entry point or your own instrumentation module. Do not initialize a second SDK in the application. Static ES module imports run before the module body, so calling init above static imports in the same file does not guarantee initialization order.

Verify ingestion

Start your application, make requests to an instrumented route, and emit a console message. In ClickHouse Observability, select a recent time range and search Logs or Traces for my-node-app. Allow time for the metrics export interval before checking metrics. If data is missing, check SDK diagnostics on stderr, the endpoint and authentication, and network connectivity. Ensure instrumentation loads before application dependencies. Bundled libraries cannot be automatically instrumented if the bundler inlines them; keep the SDK and instrumented dependencies external. Consult SDK compatibility for TypeScript, ES module, framework, and bundler requirements.

Configure instrumentation

Standard OpenTelemetry environment variables retain their upstream meaning, including sampling, batching, exporters, and resource attributes. For example:

export OTEL_RESOURCE_ATTRIBUTES='deployment.environment.name=production'

Console output is captured by default. HTTP body capture is disabled by default; enable it only when appropriate for the data your application handles:

export CLICKSTACK_CAPTURE_HTTP_BODY='true'

Captured bodies can contain personal data and credentials. SDK redaction is best effort; retain collector-side redaction where needed. See the SDK privacy options for header capture, body limits, and sanitization.

Initialization options

Pass these options to init in your instrumentation module:

Option	Default	Purpose
`endpoint`	`http://localhost:4318`	Base OTLP HTTP URL; overridden by `OTEL_EXPORTER_OTLP_ENDPOINT`
`serviceName`	`unknown_service:` followed by the executable name	Service name; overridden by `OTEL_SERVICE_NAME` or `service.name` in `OTEL_RESOURCE_ATTRIBUTES`
`environment`	Unset	Set `deployment.environment.name`; the same key in `OTEL_RESOURCE_ATTRIBUTES` takes precedence
`apiKey`	Unset	Authorization header value; ignored if `OTEL_EXPORTER_OTLP_HEADERS` is already nonblank, even if it contains only unrelated headers
`httpBodyCapture`	`false`	Capture HTTP bodies; overridden by `CLICKSTACK_CAPTURE_HTTP_BODY`
`instrumentations`	Upstream configuration defaults	Configuration map for `getNodeAutoInstrumentations`; explicit `enabled` values override instrumentation enable/disable environment variables
`additionalInstrumentations`	`[]`	Additional instrumentation instances for libraries outside the default bundle

Unset or blank environment variables allow the corresponding option to take effect. To disable console capture, include console in OTEL_NODE_DISABLED_INSTRUMENTATIONS. See the Node.js SDK reference for all defaults. For explicit process exits or AWS Lambda handlers, see the SDK lifecycle documentation.

Using the upstream SDK

If your application already configures OpenTelemetry, or needs custom processors or behavior outside the ClickStack SDK’s options, use the upstream NodeSDK and configure OTLP export for the destination above. Follow the upstream SDK setup example, which explains the additional loader and lifecycle configuration. Do not initialize both SDKs in the same process.

Migrating from the HyperDX Node.js SDK

Replace @hyperdx/node-opentelemetry with @clickhouse/clickstack-node and use the new registration entry point. Replace HYPERDX_API_KEY with OTEL_EXPORTER_OTLP_HEADERS, using the authorization format for your destination above. The new SDK does not preserve every HyperDX helper or option. Review the SDK migration guide before replacing logger integrations, error handlers, custom trace attributes, or sampling settings.

Introduction

Features

Administration

Guides

Integration partners

Self-managed

Install

Configure your destination

Start your application

Verify ingestion

Configure instrumentation

Initialization options

Using the upstream SDK

Migrating from the HyperDX Node.js SDK

​Install

​Configure your destination

​Start your application

​Verify ingestion

​Configure instrumentation

​Initialization options

​Using the upstream SDK

​Migrating from the HyperDX Node.js SDK

Install

Configure your destination

Start your application

Verify ingestion

Configure instrumentation

Initialization options

Using the upstream SDK

Migrating from the HyperDX Node.js SDK