Distributed Tracing 101: A Full‑Stack Guide with Sentry (Part 1)

Welcome to the first part of a series on distributed tracing for full‑stack developers. The series will explore how tracing links operations across multiple services, enabling end‑to‑end visibility of requests.

Distributed tracing records the flow of work between services. A Span represents a single operation (e.g., an HTTP request or function call), while a trace is a collection of one or more spans that together form an end‑to‑end journey.

Each trace is uniquely identified by a trace identifier (a UUID generated in the root span). Every span also receives a unique span_id. The relationship between spans is expressed through a parent_id that points to the span that created the current one.

To connect spans across services, the trace context—comprising the trace_id and parent_id —must be propagated in outgoing requests. The following diagram illustrates a trace that starts in a React front‑end, calls an API web server, and then triggers a background worker.

Below is a minimal JavaScript implementation that generates a traceId and spanId in the browser, attaches them as custom HTTP headers, and sends a POST request to /inviteUser:

// browser app (JavaScript)
import uuid from 'uuid';

const traceId = uuid.v4();
const spanId = uuid.v4();

console.log('Initiate inviteUser POST request', `traceId: ${traceId}`);

fetch('/api/v1/inviteUser?email=' + encodeURIComponent(email), {
  method: 'POST',
  headers: {
    'trace-id': traceId,
    'parent-id': spanId,
  }
}).then(data => {
  console.log('Success!');
}).catch(err => {
  console.log('Something bad happened', `traceId: ${traceId}`);
});

The API server extracts the trace metadata, enqueues an email job, and returns a 200 response. The background worker later processes the job, again extracting the trace information to log the email‑sending step:

// API Web Server
const Queue = require('bull');
const emailQueue = new Queue('email');
const uuid = require('uuid');

app.post('/api/v1/inviteUser', (req, res) => {
  const spanId = uuid.v4(),
        traceId = req.headers['trace-id'],
        parentId = req.headers['parent-id'];

  console.log('Adding job to email queue', `[traceId: ${traceId},`, `parentId: ${parentId},`, `spanId: ${spanId}]`);

  emailQueue.add({
    title: "Welcome to our product",
    to: req.params.email,
    meta: { traceId, parentId: spanId }
  });

  res.status(200).send('ok');
});

// Background Task Worker
emailQueue.process((job, done) => {
  const spanId = uuid.v4();
  const { traceId, parentId } = job.data.meta;

  console.log('Sending email', `[traceId: ${traceId},`, `parentId: ${parentId},`, `spanId: ${spanId}]`);
  // actually send the email …
  done();
});

In realistic distributed systems, logs from multiple concurrent services interleave, making it hard to reconstruct the exact execution order. By attaching trace metadata (traceId, spanId, parentId) to each log entry, developers can filter by traceId and rebuild the parent‑child relationships to understand the true sequence of events.

OpenTelemetry provides open‑source APIs and SDKs for generating and exporting telemetry data in many languages, including JavaScript and Node.js. Sentry consumes this telemetry to produce waterfall charts for performance monitoring and to enrich error monitoring with trace context, helping teams pinpoint where failures propagate across services.