Skip to main content

Node.js SDK

The Syntropy Node.js SDK captures errors from server-side applications.

npm install @eclosion-tech/syntropy-node

Basic Setup​

Initialize at the very start of your application:

// First line of your entry file
import { Syntropy } from '@eclosion-tech/syntropy-node';

Syntropy.init({
  projectId: 'your-project-id',
  release: process.env.npm_package_version,
  environment: process.env.NODE_ENV,
});

// Rest of your app
import express from 'express';
// ...

Configuration Options​

Syntropy.init({
  // Required
  projectId: 'your-project-id',
  dsn: 'https://syntropy.chat/api/ingest', // Optional endpoint override
  
  // Release tracking
  release: '1.0.0',
  dist: '42',
  environment: 'production',
  
  // Behavior
  enabled: true,
  autoCapture: true,            // Capture uncaught exceptions
  
  // Performance
  flushInterval: 5000,          // Flush interval (ms)
  maxBatchSize: 50,             // Max events per batch
  sampleRate: 1.0,              // Sample rate (0.0 - 1.0)
  
  // Filtering
  beforeSend: (event) => event, // Return null to drop
  
  // Debugging
  debug: false,
});

Automatic Error Capture​

With autoCapture: true, the SDK captures:

  • uncaughtException - Unhandled exceptions
  • unhandledRejection - Unhandled Promise rejections
// These are automatically captured:
throw new Error('Uncaught error');
Promise.reject(new Error('Unhandled rejection'));

Manual Error Capture​

import { Syntropy } from '@eclosion-tech/syntropy-node';

try {
  await riskyOperation();
} catch (error) {
  Syntropy.captureError(error, {
    tags: { service: 'payment-processor' },
    extra: { transactionId: 'txn_123' },
  });
}

Request Context​

Use async context to attach request information to errors:

import { Syntropy, runWithContext } from '@eclosion-tech/syntropy-node';

app.use((req, res, next) => {
  runWithContext(
    {
      user: req.user,
      requestId: req.headers['x-request-id'],
    },
    () => next()
  );
});

// Errors captured in this request will include the context

User Identification​

// Set user for current async context
Syntropy.setUser({
  id: user.id,
  email: user.email,
});

// Or pass directly when capturing
Syntropy.captureError(error, {
  user: { id: 'user-123', email: 'user@example.com' },
});

Custom Events​

Syntropy.captureEvent('email_sent', {
  to: 'user@example.com',
  template: 'welcome',
});

Syntropy.captureEvent('payment_processed', {
  amount: 99.99,
  currency: 'USD',
});

Syntropy.captureConversation('message_received', {
  conversationId: 'conv_123',
  role: 'assistant',
});

Graceful Shutdown​

Flush pending events before exiting:

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

Tags and Extra Data​

// Set global tags
Syntropy.setTag('service', 'api');
Syntropy.setTag('region', 'us-east-1');

// Set global extra data
Syntropy.setExtra('hostname', os.hostname());

Express Integration​

For Express apps, use the dedicated Express SDK:

import {
  Syntropy,
  syntropyMiddleware,
  syntropyErrorHandler,
} from '@eclosion-tech/syntropy-express';

Syntropy.init({ projectId: 'your-project-id' });

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

// Routes...

app.use(syntropyErrorHandler());

See Express SDK for full documentation.

Typed Project APIs​

import { createSyntropyApiClient } from '@eclosion-tech/syntropy-node';

const api = createSyntropyApiClient({
  baseUrl: 'https://syntropy.chat/api',
  apiKey: process.env.SYNTROPY_API_KEY,
});

await api.customers.upsert(
  { organizationId: 'org_uuid', projectId: 'project_uuid' },
  { externalId: 'user_123', email: 'user@example.com' }
);

See SDK API Client for all available methods.