> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitoring Node.js traces with ClickStack
> Monitoring Node.js application traces with ClickStack
export const TrackedLink = ({href, eventName, children, ...rest}) => {
const handleClick = () => {
try {
if (typeof window !== "undefined" && window.galaxy && eventName) {
window.galaxy.track(eventName, {
interaction: "click"
});
}
} catch (e) {}
};
return
{children}
;
};
export const Image = ({img, alt, size}) => {
return
;
};
**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](#demo-dataset).
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 the `@hyperdx/node-opentelemetry` package and initialize it at the start of your application. See the [Node.js SDK guide](/clickstack/ingesting-data/sdks/nodejs#getting-started) for detailed installation steps.
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](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
Start your Node.js application with the environment variables set:
```bash theme={null}
export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
```
Generate some traffic
Make requests to your application to generate traces:
```bash theme={null}
# 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
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.
Download the sample dataset
Download the sample traces file:
```bash theme={null}
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json
```
Start ClickStack
If you don't have ClickStack running yet, start it with:
```bash theme={null}
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
An API key to send traces to ClickStack's OTLP endpoint.
1. Open HyperDX at your ClickStack URL (e.g., [http://localhost:8080](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:
```bash theme={null}
export CLICKSTACK_API_KEY=your-api-key-here
```
Send the traces to ClickStack
```bash theme={null}
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
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
To help you get started monitoring Node.js application performance, we provide a pre-built dashboard with essential trace visualizations.
Download the dashboard configuration
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
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:
```bash theme={null}
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:**
```bash theme={null}
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:**
```bash theme={null}
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](/clickstack/features/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](/clickstack/ingesting-data/opentelemetry) for production deployment patterns and collector configuration examples.