tracebeam-sdk

A lightweight, non-blocking Node.js SDK for sending errors and events to the TraceBeam API Observability Platform.

Features

• 🚀 Non-blocking - Events queued and sent in background
• ⚡ Batching - Events batched for efficient transmission
• 🔄 Retry - Automatic retry with exponential backoff
• 🔒 Secure - API keys via environment variables
• 📦 Lightweight - Zero runtime dependencies (uses native fetch)
• 🎯 TypeScript - Full type support

Requirements

• Node.js 18+

Installation

npm install tracebeam-sdk

Quick Start

import { TraceBeamSDK } from 'tracebeam-sdk';

// Initialize from environment variables
const sdk = TraceBeamSDK.fromEnv();

// Capture an exception
try {
  await doSomething();
} catch (error) {
  sdk.captureException(error);
}

// Capture a message
sdk.captureMessage('User signed up', { level: 'info' });

// Graceful shutdown
await sdk.close();

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TRACEBEAM_API_KEY | Yes | - | Your API key | | TRACEBEAM_PROJECT_ID | Yes | - | Your project ID | | TRACEBEAM_ENVIRONMENT | No | development | Environment name | | TRACEBEAM_ENDPOINT | No | https://ingest.tracebeam.io | API endpoint | | TRACEBEAM_BATCH_SIZE | No | 100 | Events per batch | | TRACEBEAM_FLUSH_INTERVAL | No | 5000 | Flush interval (ms) | | TRACEBEAM_DEBUG | No | false | Enable debug logging |

Manual Configuration

const sdk = new TraceBeamSDK({
  apiKey: 'sk_xxx',
  projectId: 'proj_xxx',
  environment: 'production',
  batchSize: 50,
  flushInterval: 3000,
});

Context

// Set user context
sdk.setUser('user_123');

// Set tags (included in all events)
sdk.setTag('region', 'us-east-1');
sdk.setTags({ service: 'api', version: '1.0.0' });

// Set extra context
sdk.setExtra('account_type', 'premium');

Framework Integrations

Express

import express from 'express';
import { TraceBeamSDK } from 'tracebeam-sdk';
import { expressErrorHandler } from 'tracebeam-sdk/integrations/express';

const app = express();
const sdk = TraceBeamSDK.fromEnv();

// Your routes...

// Add error handler AFTER all routes
app.use(expressErrorHandler(sdk));

Fastify

import Fastify from 'fastify';
import { TraceBeamSDK } from 'tracebeam-sdk';
import { tracebeamPlugin } from 'tracebeam-sdk/integrations/fastify';

const fastify = Fastify();
const sdk = TraceBeamSDK.fromEnv();

fastify.register(tracebeamPlugin, { sdk });

Capture Options

sdk.captureException(error, {
  level: 'fatal',
  tags: { feature: 'auth' },
  extra: { userId: '123', endpoint: '/login' },
});

sdk.captureMessage('Important event', {
  level: 'warning',
  tags: { category: 'billing' },
});

Graceful Shutdown

process.on('SIGTERM', async () => {
  await sdk.close();
  process.exit(0);
});

License

MIT