trace

Distributed tracing system for monitoring request flows, performance bottlenecks, and errors across services with real-time visualization.

Overview

The trace primitive provides comprehensive observability for distributed systems, tracking requests as they flow through services, functions, and agents with detailed timing and context information.

Parent Primitive: analytics - Analytics and metrics platform

SDK Object Mapping

This primitive maps to the send SDK object and context for distributed tracing:

import { send, context, trace } from 'sdk.do'

// Start span with context propagation
const span = trace.startSpan('process-order', {
  attributes: {
    orderId: '123',
    userId: 'user-456',
  },
})

try {
  // Operations are automatically traced
  await validateOrder(order)
  await processPayment(order)

  // Send trace event
  await send('analytics.track', {
    event: 'trace.span',
    traceId: span.traceId,
    spanId: span.spanId,
    duration: span.duration,
  })

  span.setStatus({ code: 'OK' })
} catch (error) {
  span.setStatus({ code: 'ERROR', message: error.message })
  span.recordException(error)
  throw error
} finally {
  span.end()
}

Quick Example

import { trace } from 'sdk.do'

// Create span
const span = trace.startSpan('process-order', {
  attributes: {
    orderId: '123',
    userId: 'user-456',
  },
})

try {
  // Traced operations
  await validateOrder(order)
  await processPayment(order)
  await createShipment(order)

  span.setStatus({ code: 'OK' })
} catch (error) {
  span.setStatus({ code: 'ERROR', message: error.message })
  span.recordException(error)
  throw error
} finally {
  span.end()
}

Core Capabilities

Distributed Tracing - Track requests across service boundaries
Performance Monitoring - Identify slow operations and bottlenecks
Error Tracking - Capture and analyze errors with context
Custom Attributes - Add metadata to spans for filtering
Real-Time Visualization - View traces in dashboards

Access Methods

SDK

TypeScript/JavaScript library for tracing

const span = trace.startSpan('operation', { attributes: { userId: '123' } })

→ SDK Documentation

CLI

Command-line tool for trace queries

do trace query --operation process-order --time-range last-1h

→ CLI Documentation

API

REST/RPC endpoints for trace data

curl -X GET https://api.do/v1/traces?operation=process-order

→ API Documentation

MCP

Model Context Protocol for AI-driven trace analysis

Query traces for process-order operations in the last hour

→ MCP Documentation

Parent Primitive

analytics - Analytics and metrics platform

Sibling Primitives

kpis - KPI tracking
performance - Performance monitoring
experiments - A/B testing

context - Request context propagation
events - Event tracking
send - Event emission

trace

On this page