traceapm

A focused SDK to enable distributed tracing and custom metrics for your Node.js applications with minimal configuration. Works out-of-the-box for both JavaScript and TypeScript projects.

Features

• Auto-instrumentation for supported Node.js libraries
• Exports traces and metrics to your OpenTelemetry collector
• Express middleware for custom HTTP duration metrics (with trace/span IDs)
• TypeScript type definitions included
• Clear warnings if collector URL or service name are not provided

Installation

npm install traceapm

Quick Start

1. Initialize Traceapm (at the top of your entry file)

const { init } = require('traceapm');

init({
  serviceName: 'my-service', // Name of your service (recommended)
  endpoint: 'http://localhost:4318', // Collector endpoint (recommended)
  attributes: { 'deployment.environment': 'dev' }, // Optional extra attributes
});

If you do not provide serviceName or endpoint, a warning will be logged and a default will be used.

2. Add Express Middleware

const express = require('express');
const { apmHttpMetricsMiddleware } = require('traceapm');

const app = express();
app.use(apmHttpMetricsMiddleware);

3. (Optional) Record Custom Metrics Manually

const { recordHttpRequestDuration } = require('traceapm');
recordHttpRequestDuration(123, {
  route: '/custom',
  status_code: 200,
  method: 'GET',
});

Configuration

• serviceName (string): Name of your service (default: default)
• endpoint (string): Collector endpoint (default: http://localhost:4318)
• attributes (object): Additional resource attributes (default: {})

TypeScript Support

Type definitions are included. You can import the middleware and helpers with full type safety:

import { apmHttpMetricsMiddleware, recordHttpRequestDuration, init } from 'traceapm';

Troubleshooting

• No collector endpoint provided:
  • [traceapm] Warning: No collector endpoint provided. Using default.
• No service name provided:
  • [traceapm] Warning: No service name provided. Using default.

Example: Full Express App

const express = require('express');
const { init, apmHttpMetricsMiddleware } = require('traceapm');

init({
  serviceName: 'my-service',
  endpoint: 'http://localhost:4318',
});

const app = express();
app.use(apmHttpMetricsMiddleware);

app.get('/', (req, res) => res.send('Hello World!'));
app.listen(3000);

License

MIT