Skip to main content
Distributed tracing helps you understand the full journey of requests through your system.

​
How Tracing Works

  1. Beacon generates a trace ID for each user session
  2. This ID is passed in headers to your backend
  3. Your backend logs include the same trace ID
  4. You can follow a request from frontend to backend

​
Enabling Tracing

const beacon = new Beacon({
  key: 'bpk_your_key',
  tracing: {
    enabled: true,
    sampleRate: 0.1  // Trace 10% of requests
  }
});

​
Trace Context

The SDK automatically adds trace headers to fetch requests: 
// Headers added automatically:
// x-trace-id: abc123
// x-span-id: def456
// x-parent-span-id: ghi789

​
Manual Spans

Create spans for important operations: 
const span = beacon.startSpan('checkout');

try {
  await processCheckout();
  span.finish('ok');
} catch (error) {
  span.finish('error', { error: error.message });
}

​
Backend Integration

Pass trace context to your backend: 
// Frontend
const response = await fetch('/api/order', {
  headers: beacon.getTraceHeaders()
});

// Backend (Node.js)
app.post('/api/order', (req, res) => {
  const traceId = req.headers['x-trace-id'];
  logger.info('Processing order', { traceId });
});

​
Viewing Traces

In Dashboard > Beacon > Traces:
  • See the full request timeline
  • Identify slow spans
  • Find errors in the trace
  • View span details and metadata

​
Trace Structure

Trace: abc123
├── Span: page_load (250ms)
│   ├── Span: fetch_user (80ms)
│   └── Span: fetch_products (120ms)
└── Span: checkout (500ms)
    ├── Span: validate_cart (20ms)
    ├── Span: process_payment (350ms) [ERROR]
    └── Span: send_confirmation (50ms)

​
Sampling

Tracing adds overhead. Use sampling in production: 
const beacon = new Beacon({
  key: 'bpk_your_key',
  tracing: {
    enabled: true,
    sampleRate: 0.1  // 10% of sessions
  }
});
For debugging, temporarily increase the rate or force tracing: 
// Force tracing for this session
beacon.forceTrace();