Monitoring Node.js traces with ClickHouse Observability

Capture traces from your Node.js application with OpenTelemetry automatic instrumentation and send them to ClickHouse Observability. Use the demo dataset to try the integration without instrumenting an application.

Prerequisites

A ClickHouse Observability service
For your application, Node.js 22 or newer and npm
For the demo, Docker and curl

Connection details

Fully managed
Self-managed

Open ClickHouse Observability and go to Team Settings → Data → Managed Telemetry. Copy your OTLP HTTP endpoint and API key. You can use Copy connection details to copy the configuration, or Reveal key to view the masked key.Set these connection variables in the terminal where you will run your application or demo collector:

export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
export OTEL_EXPORTER_OTLP_AUTHORIZATION='Bearer YOUR_API_KEY'

Replace the placeholders with the exact endpoint, including its port, and API key from your service. Use the base HTTP endpoint without a /v1/traces suffix; the exporter appends the signal path.

Use your collector’s reachable OTLP HTTP endpoint (for example, http://YOUR_COLLECTOR_HOST:4318) and authentication settings. If your collector does not require authentication, omit the exporter’s headers block from the configurations below. See the self-managed getting-started guide for setup guidance.

export OTEL_EXPORTER_OTLP_ENDPOINT='http://YOUR_COLLECTOR_HOST:4318'
export OTEL_EXPORTER_OTLP_AUTHORIZATION='YOUR_INGESTION_KEY'

Integration with an existing Node.js application

Install OpenTelemetry

From your application’s directory, install the instrumentation packages:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node@0.81.0

These steps use OpenTelemetry automatic instrumentation for CommonJS applications. Native ES modules require the ESM setup. Use one instrumentation setup per application to avoid duplicate spans.

Configure tracing and start your application

In the terminal where you set the connection variables, run:

export OTEL_SERVICE_NAME='nodejs-service'
export OTEL_TRACES_EXPORTER='otlp'
export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=${OTEL_EXPORTER_OTLP_AUTHORIZATION}"
export OTEL_METRICS_EXPORTER='none'
export OTEL_LOGS_EXPORTER='none'

node --require @opentelemetry/auto-instrumentations-node/register app.js

Replace app.js with your application entry point. The preload initializes instrumentation before your application imports its libraries. For a self-managed endpoint without authentication, omit the headers export and run unset OTEL_EXPORTER_OTLP_HEADERS.The endpoint must be reachable from the application. If it runs in a container, localhost refers to that container.

Generate traffic

Make requests to an endpoint your application serves. For an application listening on port 3000:

curl http://localhost:3000/

Allow a few seconds for the exporter to send the spans.

Verify traces

Open Search, select Traces, filter for ServiceName:nodejs-service, and select Last 15 minutes. Open a trace to inspect its spans, timing, and attributes.

Demo dataset

The sample contains 822 spans from nodejs-demo-api. You do not need a running Node.js application.

Download the sample dataset

curl -fLO https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json

Configure the demo collector

Save the following as nodejs-traces-demo.yaml in the download directory:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 256
    spike_limit_mib: 64
  transform/demo_timestamps:
    error_mode: propagate
    trace_statements:
      - context: span
        statements:
          - set(cache["duration_ns"], end_time_unix_nano - start_time_unix_nano)
          - >-
            set(start_time,
              Now() - Duration("2m") -
              (Time("2025-10-27T17:59:15Z", "%Y-%m-%dT%H:%M:%SZ") - start_time)
            )
          - set(end_time_unix_nano, start_time_unix_nano + cache["duration_ns"])
  batch:
    timeout: 5s
    send_batch_size: 1024

exporters:
  otlp_http/observability:
    endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT}
    headers:
      authorization: "${env:OTEL_EXPORTER_OTLP_AUTHORIZATION}"

service:
  pipelines:
    traces/nodejs-demo:
      receivers: [otlp]
      processors: [memory_limiter, transform/demo_timestamps, batch]
      exporters: [otlp_http/observability]

The demo-only transform/demo_timestamps processor shifts this sample into roughly the past 24 hours, ending two minutes before ingestion, while preserving span durations and the traffic pattern. Omit this processor for your own Node.js traces so their original timestamps are preserved. Sending the sample again can produce duplicate spans.

Run the demo collector

For a destination collector running on this computer, set OTEL_EXPORTER_OTLP_ENDPOINT to http://host.docker.internal:4318. The command below includes the Docker host mapping.

Run OpenTelemetry Collector Contrib 0.161.0 from the directory containing the configuration, in the terminal where you set the connection variables. Keep this terminal open:

docker run --rm --name nodejs-traces-demo-collector \
  --add-host=host.docker.internal:host-gateway \
  --memory=512m \
  -p 127.0.0.1:14318:4318 \
  -e OTEL_EXPORTER_OTLP_ENDPOINT \
  -e OTEL_EXPORTER_OTLP_AUTHORIZATION \
  -v "$(pwd)/nodejs-traces-demo.yaml:/etc/otelcol-contrib/config.yaml:ro" \
  otel/opentelemetry-collector-contrib:0.161.0 \
  --config=/etc/otelcol-contrib/config.yaml

The local receiver uses port 14318 to avoid conflicting with an existing collector on port 4318. The collector forwards the traces to your configured endpoint using the authentication settings above.

Send the traces

In another terminal, from the download directory, send the original sample to the local collector:

curl --fail-with-body -sS http://localhost:14318/v1/traces \
  -H "Content-Type: application/json" \
  --data-binary @nodejs-traces-sample.json

An empty success response such as {} or {"partialSuccess":{}} indicates the local collector accepted the request. Check the collector’s output for export errors and allow a few seconds for the batch to reach your service. Stop the demo collector with Ctrl+C when finished.

Verify the demo traces

Open Search, select Traces, filter for ServiceName:nodejs-demo-api, and select Last 2 days to include the full shifted dataset. Open a trace to inspect the HTTP attributes.

Dashboards and visualization

Import the dashboard

Open Dashboards and click Import in the upper-right corner.
Upload nodejs-traces-dashboard.json.
Map the charts to your Traces source and click Finish Import.

View the dashboard

For the sample, select Last 2 days and optionally filter for ServiceName:nodejs-demo-api. For your application, select its service name and a time range covering your requests.The dashboard uses the sample’s HTTP span attributes. Instrumentation versions can use different attribute names; adjust chart fields if your application’s spans differ.

Troubleshooting

No application traces appear

Check application output for export errors. Verify the endpoint, protocol, and authentication settings. Load instrumentation before application libraries, generate requests, and check the service-name filter and time range. For native ES modules, follow the linked ESM setup.

Demo traces do not appear

Check the demo collector output for authentication or export errors. A successful curl response confirms local acceptance; allow a few seconds for forwarding to your service. Include transform/demo_timestamps in the pipeline and select Last 2 days. Resending the sample can create duplicates.

Next steps

Set up alerts for errors and latency.
Create additional dashboards.

Introduction

Features

Administration

Guides

Integration partners

Self-managed

Monitoring Node.js traces with ClickHouse Observability

Prerequisites

Connection details

Integration with an existing Node.js application

Demo dataset

Dashboards and visualization

Troubleshooting

No application traces appear

Demo traces do not appear

Next steps

​Prerequisites

​Connection details

​Integration with an existing Node.js application

​Demo dataset

​Dashboards and visualization

​Troubleshooting

​No application traces appear

​Demo traces do not appear

​Next steps

Prerequisites

Connection details

Integration with an existing Node.js application

Demo dataset

Dashboards and visualization

Troubleshooting

No application traces appear

Demo traces do not appear

Next steps