Monitoring Node.js traces with ClickStack

Monitoring Node.js application traces with ClickStack

Monitoring Node.js Traces with ClickStack

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

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.

• 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

1. 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 for detailed installation steps.

2. 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
3. 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
   
4. 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
   
5. 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

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.

1. 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
   
2. 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
   
3. 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
   
4. 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.

5. Verify traces in HyperDX

   1. Open HyperDX 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

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

1. the dashboard configuration

2. 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
3. The dashboard will be created with all visualizations pre-configured

   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

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

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

• Set up alerts for critical metrics (error rates, latency thresholds)
• Create additional dashboards for specific use cases (API monitoring, security events)

Going to production

This guide uses the HyperDX SDK which sends traces directly to ClickStack’s OTLP endpoint. This works well for development, testing, and small-to-medium production deployments. For larger production environments or if you need additional control over telemetry data, consider deploying your own OpenTelemetry Collector as an agent. See Ingesting with OpenTelemetry for production deployment patterns and collector configuration examples.