@open-pulseboard/tracer

Auto-instrumenting OpenTelemetry tracer for Node.js, wired for PulseBoard. One install, one -r flag, no code change.

npm i @open-pulseboard/tracer
PULSE_API_KEY=sk_... node -r @open-pulseboard/tracer/register app.js

Within ~30s your service shows up in the PulseBoard service catalog with HTTP / DB / cache / queue spans flowing.

---

What you get

• Distributed traces for every popular Node library that has an upstream OpenTelemetry instrumentation: http, https, undici, express, fastify, koa, hapi, nestjs-core, graphql, grpc, pg, mysql, mysql2, mongodb, mongoose, redis, ioredis, kafkajs, amqplib, aws-sdk, and more.
• Resource attributes auto-detected for Docker, Kubernetes (downward API env vars), AWS (EC2, ECS, EKS, Lambda) and GCP Cloud Run.
• OTLP/HTTP exporter wired to your PulseBoard tenant with Authorization: Bearer $PULSE_API_KEY.
• Trace sampling, periodic metric export, batched span export — same defaults as the OpenTelemetry contrib distribution.
• Graceful shutdown on SIGTERM / SIGINT / beforeExit so traces flush before the process exits.

This package is a thin shell over upstream @opentelemetry/sdk-node and @opentelemetry/auto-instrumentations-node. We do not fork the SDK; you get every patch and instrumentation the upstream community ships.

---

Configuration

Every setting is environment-driven. Programmatic overrides are also supported via start({...}).

Variable	Default	Notes
PULSE_URL	https://api.pulseboard.cloud	OTLP/HTTP base URL. /v1/traces, /v1/metrics are appended.
PULSE_API_KEY	(none)	Sent as Authorization: Bearer …. Required in production.
PULSE_SERVICE_NAME	npm_package_name or detected	Falls back to OTEL_SERVICE_NAME, AWS_LAMBDA_FUNCTION_NAME, K_SERVICE.
PULSE_SERVICE_VERSION	npm_package_version	Falls back to OTEL_SERVICE_VERSION.
PULSE_ENVIRONMENT	NODE_ENV	Becomes deployment.environment.name.
PULSE_DISABLE_INSTRUMENTATION	(none)	CSV of short names — e.g. fs,dns. Full @opentelemetry/instrumentation-X ids ok.
PULSE_SAMPLE_RATIO	1	Float in [0, 1]. Applied with a ParentBased(TraceIdRatio) sampler.
PULSE_DISABLED	false	When 1/true, start() returns a no-op handle.
PULSE_DEBUG	false	When 1/true, lifecycle messages to stderr.

Programmatic use

const { start, shutdown } = require('@open-pulseboard/tracer');

const tracer = start({ serviceName: 'checkout', sampleRatio: 0.1 });

process.on('SIGTERM', () => shutdown());

---

Acceptance smoke

// smoke.js
require('http')
  .createServer((req, res) => res.end('ok'))
  .listen(3000, () => {
    require('http').get('http://localhost:3000', () => process.exit(0));
  });

PULSE_API_KEY=sk_... PULSE_DEBUG=1 \
  node -r @open-pulseboard/tracer/register smoke.js

You should see a [@open-pulseboard/tracer debug] tracer started → … line on stderr and the HTTP span in your PulseBoard tenant.

---

Scope (this release)

Shipped in 0.1:

• Traces (OTLP/HTTP, BatchSpanProcessor)
• Metrics export plumbing (no PulseBoard-specific exemplar wiring yet)
• All upstream @opentelemetry/auto-instrumentations-node libraries
• Container / k8s / AWS / GCP resource detection
• register.js entry for node -r
• Graceful shutdown

Explicitly not in 0.1:

• Continuous CPU/heap profiler hook (planned with the agent-side profiler service)
• Error / exception capture beyond what OTel spans already record
• LLM request shape capture (planned)
• Framework-specific extensions beyond the auto-instrumentations bundle (Next.js / tRPC / BullMQ extras land in a later slice)
• Source-map upload helper for browser/RN — this package is server-only

---

Development

nvm use 20
npm ci
npm run build
npm test

Tests use Node's built-in node:test runner via tsx, so no extra framework dependency is needed at install time.

License

MIT — see LICENSE.