Transactional

Quickstart

Get error tracking running in your application in 5 minutes.

Prerequisites

Before you begin, you'll need:

  1. An Observability project (create one in Dashboard > Observability)
  2. Your project DSN (found in project settings)

Installation

Install the SDK in your project:

npm install @transactional/observability

Basic Setup

JavaScript / TypeScript

import { initObservability, getObservability } from '@transactional/observability';
 
// Initialize with your DSN
initObservability({
  dsn: 'https://your-dsn@observability.transactional.dev/project-id',
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION,
 
  // Enable error tracking
  enableErrorTracking: true,
 
  // Capture unhandled errors automatically
  autoCapture: {
    uncaughtExceptions: true,
    unhandledRejections: true,
  },
});

Node.js

import { initObservability } from '@transactional/observability';
 
initObservability({
  dsn: 'https://your-dsn@observability.transactional.dev/project-id',
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION,
  enableErrorTracking: true,
  platform: 'node',
 
  autoCapture: {
    uncaughtExceptions: true,
    unhandledRejections: true,
  },
});

React

import { initObservability, ErrorBoundary } from '@transactional/observability/react';
 
// Initialize
initObservability({
  dsn: 'your-dsn',
  environment: process.env.NODE_ENV,
  enableErrorTracking: true,
  platform: 'react',
});
 
// Wrap your app with ErrorBoundary
function App() {
  return (
    <ErrorBoundary fallback={<ErrorPage />}>
      <YourApp />
    </ErrorBoundary>
  );
}

Next.js

// instrumentation.ts (App Router)
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { initObservability } = await import('@transactional/observability');
 
    initObservability({
      dsn: process.env.OBSERVABILITY_DSN,
      environment: process.env.NODE_ENV,
      enableErrorTracking: true,
      platform: 'nextjs',
    });
  }
}
// app/error.tsx (Error boundary)
'use client';
 
import { useEffect } from 'react';
import { getObservability } from '@transactional/observability';
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    const obs = getObservability();
    obs.captureException(error);
  }, [error]);
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

Python

from transactional_observability import init_observability, capture_exception
 
# Initialize
init_observability(
    dsn="your-dsn",
    environment="production",
    enable_error_tracking=True,
    platform="python",
)
 
# Errors are captured automatically, or manually:
try:
    risky_operation()
except Exception as e:
    capture_exception(e)
    raise

Test Your Integration

Trigger a test error to verify everything is working:

import { getObservability } from '@transactional/observability';
 
// Trigger a test error
function testErrorTracking() {
  const obs = getObservability();
 
  try {
    throw new Error('Test error from Observability setup');
  } catch (error) {
    obs.captureException(error as Error, {
      tags: { test: 'true' },
    });
  }
}
 
// Call this in development
testErrorTracking();

View Your First Error

  1. Go to Dashboard > Observability
  2. Select your project
  3. Click Issues in the sidebar
  4. You should see your test error

Add User Context

Track which users are affected by errors:

const obs = getObservability();
 
// Set user context after authentication
obs.setUser({
  id: user.id,
  email: user.email,
  username: user.name,
});
 
// Clear on logout
obs.setUser(null);

Set Up Alerts

Don't miss critical errors. Set up alerts:

  1. Go to your project settings
  2. Click Alert Rules
  3. Create a rule:
    • Trigger: New Issue
    • Channel: Email or Slack
    • Recipients: Your team

Next Steps

Now that error tracking is set up:

Troubleshooting

Errors Not Appearing

  1. Check DSN - Verify the DSN is correct in your config
  2. Check Network - Ensure your app can reach the API
  3. Check Console - Look for SDK initialization errors
  4. Flush on Shutdown - Call obs.shutdown() before process exit

Source Maps Not Working

  1. Upload Source Maps - Ensure source maps are uploaded for your release
  2. Match Release - The release config must match uploaded source maps
  3. Check Paths - Source map paths must match deployed file paths

Missing Context

  1. Set User Early - Call setUser() after authentication
  2. Add Tags - Use setTags() for environment-specific data
  3. Enable Breadcrumbs - Ensure breadcrumb capture is enabled