Node

<!-- status: ga language: node -->

Node.js

Send traces from a Node.js service to Watchtower over OTLP/HTTP with the standard OpenTelemetry SDK. Nothing Watchtower-specific is installed: the SDK reads the standard OTEL_* variables.

1. Create a project, then an ingestion key (wti_...) with the ingest:traces scope (add ingest:logs and ingest:metrics to send logs and metrics with the same key). The key is shown once.

2. Point the SDK at the gateway and pass the key in the x-watchtower-key header (Authorization: Bearer wti_... works too):

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.example.com
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS=x-watchtower-key=wti_YOUR_KEY
export OTEL_SERVICE_NAME=my-service

1. Add the SDK and run this once. The endpoint above is the gateway's base URL; the SDK appends /v1/traces.

npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/api

// tracing.js, loaded first: node --require ./tracing.js app.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { trace } = require('@opentelemetry/api');

const sdk = new NodeSDK({ traceExporter: new OTLPTraceExporter() }); // reads OTEL_EXPORTER_OTLP_*
sdk.start();

trace.getTracer('onboarding').startSpan('hello-watchtower').end();
process.on('beforeExit', () => sdk.shutdown());

For an ES module app ("type": "module" or .mjs), preload with --import instead; --require runs too late to patch ESM imports:

// tracing.mjs, loaded first: node --import ./tracing.mjs app.js
import { register } from 'node:module';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { trace } from '@opentelemetry/api';

// import-in-the-middle hooks, so instrumentations can patch ES modules loaded after this file.
register('@opentelemetry/instrumentation/hook.mjs', import.meta.url);

const sdk = new NodeSDK({ traceExporter: new OTLPTraceExporter() }); // reads OTEL_EXPORTER_OTLP_*
sdk.start();

trace.getTracer('onboarding').startSpan('hello-watchtower').end();
process.on('beforeExit', () => sdk.shutdown());

1. Open the project's onboarding screen. It polls GET /v1/projects/{prj}/onboarding/first-event and turns green when the first span arrives. Then open the trace in the trace explorer.