Monitoring Node.js Traces with ClickStack

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/observability/clickstack/ingesting-data/integration-examples/nodejs-traces.md)

TL;DR

Capture distributed traces from Node.js applications in ClickStack using OpenTelemetry automatic instrumentation. Includes a demo dataset and pre-built dashboard.

## Integration with existing Node.js application[​](#existing-nodejs "Direct link to Integration with existing Node.js application")

This section covers adding distributed tracing to your existing Node.js application using OpenTelemetry automatic instrumentation.

If you would like to test the integration before configuring your own existing setup, you can test with our preconfigured setup and sample data in the [demo dataset section](#demo-dataset).

##### Prerequisites[​](#prerequisites "Direct link to Prerequisites")

- ClickStack instance running with OTLP endpoints accessible (ports 4317/4318)
- Existing Node.js application (Node.js 14 or higher)
- npm or yarn package manager
- ClickStack hostname or IP address

Install and configure OpenTelemetry

#### Install and configure OpenTelemetry[​](#install-configure "Direct link to Install and configure OpenTelemetry")

Install the `@hyperdx/node-opentelemetry` package and initialize it at the start of your application. See the [Node.js SDK guide](/docs/use-cases/observability/clickstack/sdks/nodejs#getting-started) for detailed installation steps.

Get ClickStack API key

#### Get ClickStack API key[​](#get-api-key "Direct link to Get ClickStack API key")

An API key to send traces to ClickStack's OTLP endpoint.

1. Open HyperDX at your ClickStack URL (e.g., <http://localhost:8080>)
2. Create an account or log in if needed
3. Navigate to **Team Settings → API Keys**
4. Copy your **Ingestion API Key**

Run your application

#### Run your application[​](#run-application "Direct link to Run your application")

Start your Node.js application with the environment variables set:

```
export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
```

Generate some traffic

#### Generate some traffic[​](#generate-traffic "Direct link to Generate some traffic")

Make requests to your application to generate traces:

```
# Simple requests
curl http://localhost:3000/
curl http://localhost:3000/api/users
curl http://localhost:3000/api/products

# Simulate load
for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done
```

Verify traces in HyperDX

#### Verify traces in HyperDX[​](#verify-traces "Direct link to Verify traces in HyperDX")

Once configured, log into HyperDX and verify traces are flowing. You should see something like this. If you don't see traces, try adjusting your time range:

Click on any trace to see the detailed view with spans, timing, and attributes:

## Demo dataset[​](#demo-dataset "Direct link to Demo dataset")

For users who want to test Node.js tracing with ClickStack before instrumenting their production applications, we provide a sample dataset of pre-generated Node.js application traces with realistic traffic patterns.

Download the sample dataset

#### Download the sample dataset[​](#download-sample "Direct link to Download the sample dataset")

Download the sample traces file:

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

Start ClickStack

#### Start ClickStack[​](#start-clickstack "Direct link to Start ClickStack")

If you don't have ClickStack running yet, start it with:

```
docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD= \
  clickhouse/clickstack-all-in-one:latest
```

Get ClickStack API key

#### Get ClickStack API key[​](#get-api-key-demo "Direct link to Get ClickStack API key")

An API key to send traces to ClickStack's OTLP endpoint.

1. Open HyperDX at your ClickStack URL (e.g., <http://localhost:8080>)
2. Create an account or log in if needed
3. Navigate to **Team Settings → API Keys**
4. Copy your **Ingestion API Key**

Set your API key as an environment variable:

```
export CLICKSTACK_API_KEY=your-api-key-here
```

Send the traces to ClickStack

#### Send the traces to ClickStack[​](#send-traces "Direct link to Send the traces to ClickStack")

```
curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json
```

You should see a response like `{"partialSuccess":{}}` indicating the traces were successfully sent.

Verify traces in HyperDX

#### Verify traces in HyperDX[​](#verify-demo-traces "Direct link to Verify traces in HyperDX")

1. Open [HyperDX](http://localhost:8080/) and log in to your account (you may need to create an account first)
2. Navigate to the **Search** view and set the source to **Traces**
3. Set the time range to **2025-10-25 13:00:00 - 2025-10-28 13:00:00**

Timezone Display

HyperDX displays timestamps in your browser's local timezone. The demo data spans **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)**. The wide time range ensures you'll see the demo traces regardless of your location. Once you see the traces, you can narrow the range to a 24-hour period for clearer visualizations.

## Dashboards and visualization[​](#dashboards "Direct link to Dashboards and visualization")

To help you get started monitoring Node.js application performance, we provide a pre-built dashboard with essential trace visualizations.

Download the dashboard configuration

#### [Download](/docs/examples/nodejs-traces-dashboard.json) the dashboard configuration[​](#download-dashboard "Direct link to download-dashboard")

Import the pre-built dashboard

#### Import the pre-built dashboard[​](#import-dashboard "Direct link to Import the pre-built dashboard")

1. Open HyperDX and navigate to the **Dashboards** section
2. Click **Import Dashboard** in the upper right corner (under the ellipses)

3. Upload the `nodejs-traces-dashboard.json` file and click **Finish Import**

The dashboard will be created with all visualizations pre-configured

#### The dashboard will be created with all visualizations pre-configured[​](#created-dashboard "Direct link to The dashboard will be created with all visualizations pre-configured")

Note

For the demo dataset, set the time range to **2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC)** (adjust based on your local timezone). The imported dashboard won't have a time range specified by default.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Demo traces not appearing via curl[​](#demo-traces-not-appearing "Direct link to Demo traces not appearing via curl")

If you've sent traces via curl but don't see them in HyperDX, try sending the traces a second time:

```
curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nodejs-traces-sample.json
```

This is a known issue that occurs when using the demo approach via curl and doesn't affect instrumented production applications.

### No traces appearing in HyperDX[​](#no-traces "Direct link to No traces appearing in HyperDX")

**Verify environment variables are set:**

```
echo $CLICKSTACK_API_KEY
# Should output your API key

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# Should output http://localhost:4318 or your ClickStack host
```

**Verify network connectivity:**

```
curl -v http://localhost:4318/v1/traces
```

Should connect successfully to the OTLP endpoint.

**Check application logs:**
Look for OpenTelemetry initialization messages when your app starts. The HyperDX SDK should output confirmation that it's initialized.

## Next steps[​](#next-steps "Direct link to Next steps")

- Set up [alerts](/docs/use-cases/observability/clickstack/alerts) for critical metrics (error rates, latency thresholds)
- Create additional dashboards for specific use cases (API monitoring, security events)

## Going to production[​](#going-to-production "Direct link to Going to production")