Distributed Tracing

import { Aside } from ‘@astrojs/starlight/components’;

What’s a trace ID?

A trace ID is a string that links related log entries together. You generate one at the start of an operation and pass it to every log in that operation.

const traceId = `checkout-${orderId}-${Date.now()}`;

gun.info({
  bucket: "api",
  message: "Checkout started",
  traceId,
  tags: { step: "start" },
});

// ... later
gun.info({
  bucket: "payment",
  message: "Payment processed",
  traceId,
  tags: { step: "payment" },
});

// ... later
gun.info({
  bucket: "api",
  message: "Checkout completed",
  traceId,
  tags: { step: "complete" },
});

In the desktop app, you can search or filter by trace ID to see the entire flow of an operation across buckets.

Generating trace IDs

Use whatever format makes sense for your app. Some patterns:

// UUID-based
const traceId = crypto.randomUUID();

// Operation-based
const traceId = `checkout:${orderId}`;

// Timestamp-based
const traceId = `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;

The only requirement is that it’s a string. Make it descriptive enough that you can identify the operation when you see it in the log viewer.

Cross-service tracing

If your frontend calls your backend, pass the trace ID in a header:

// Frontend
const traceId = crypto.randomUUID();

gun.info({
  bucket: "ui",
  message: "Fetching order",
  traceId,
});

const res = await fetch("/api/orders", {
  headers: { "x-trace-id": traceId },
});

// Backend
app.post("/api/orders", (req, res) => {
  const traceId = req.headers["x-trace-id"];

  gun.info({
    bucket: "api",
    message: "Processing order",
    traceId,
  });
});

Both logs — frontend and backend — share the same trace ID. Filter by it in the desktop app to see the full request lifecycle.