Tracing

:::caution Planned — not yet available This page describes tracing capabilities that are not yet implemented in the public API. Today, request correlation is available via the request-id / correlation-id response headers, and traces are exported internally to our observability backend (OpenTelemetry). The trace-query endpoints (/api/v2/traces/*) shown below illustrate a planned feature and do not exist yet. :::

The Tourfold API supports distributed tracing to help you debug requests, monitor performance, and understand the flow of data through our systems. Tracing provides visibility into request execution across multiple services.

What is Tracing?

Tracing allows you to track a request as it flows through different services and components. Each request gets a unique trace ID that helps you correlate logs, metrics, and events across the entire request lifecycle.

How Tracing Works

Trace Headers

Every API request can include tracing headers:

curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Parent-Span-ID: span_111222333" \
     https://api.tourfold.com/api/v2/tours

Automatic Trace Generation

If you don't provide tracing headers, we'll automatically generate them:

{
  "trace_id": "trace_123456789",
  "span_id": "span_987654321",
  "parent_span_id": null
}

Trace Headers

Header	Description	Required
X-Trace-ID	Unique identifier for the entire trace	Yes
X-Span-ID	Unique identifier for the current span	Yes
X-Parent-Span-ID	ID of the parent span (for nested operations)	No
X-Sampled	Whether to sample this trace (true/false)	No

Using Tracing

Basic Tracing

# Example: Making a request with tracing headers
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Response headers include trace information:
# X-Trace-ID: trace_123456789
# X-Span-ID: span_987654321
# X-Request-ID: req_111222333

Nested Tracing

For complex operations that span multiple API calls:

# Example: Nested tracing for tour creation with stops
# First request - Create tour
curl -X POST https://api.tourfold.com/api/v2/tours \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_tour_001" \
  -H "X-Parent-Span-ID: span_main" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Vienna City Tour",
    "description": "Explore the historic center of Vienna"
  }'

# Response includes trace headers:
# X-Trace-ID: trace_123456789
# X-Span-ID: span_tour_001

# Second request - Add stop to tour
curl -X POST https://api.tourfold.com/api/v2/tours/tour_123/stops \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_stop_001" \
  -H "X-Parent-Span-ID: span_tour_001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vienna Opera House",
    "location": {
      "latitude": 48.2038,
      "longitude": 16.3698
    }
  }'

Trace Response Headers

API responses include tracing information:

X-Trace-ID: trace_123456789
X-Span-ID: span_987654321
X-Request-ID: req_111222333

Viewing Traces

Trace Dashboard

Access your traces through our trace dashboard:

# Get trace information
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/trace_123456789

Trace Response Example

{
  "trace_id": "trace_123456789",
  "spans": [
    {
      "span_id": "span_987654321",
      "parent_span_id": null,
      "operation_name": "GET /api/v2/tours",
      "start_time": "2024-01-15T10:30:00Z",
      "end_time": "2024-01-15T10:30:01Z",
      "duration_ms": 1000,
      "tags": {
        "http.method": "GET",
        "http.url": "/api/v2/tours",
        "http.status_code": 200
      }
    },
    {
      "span_id": "span_111222333",
      "parent_span_id": "span_987654321",
      "operation_name": "database.query",
      "start_time": "2024-01-15T10:30:00.100Z",
      "end_time": "2024-01-15T10:30:00.800Z",
      "duration_ms": 700,
      "tags": {
        "db.type": "postgresql",
        "db.statement": "SELECT * FROM tours"
      }
    }
  ],
  "total_duration_ms": 1000,
  "status": "completed"
}

Trace Sampling

Sampling Configuration

Control trace sampling to manage costs and performance:

# Example: Conditional tracing based on sampling
# For high-traffic scenarios, only trace 10% of requests

# Request with tracing (10% of requests)
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Sampled: true" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Request without tracing (90% of requests)
curl -H "X-Sampled: false" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

Adaptive Sampling

# Example: Adaptive sampling based on error rates
# When error rate is high (>5%), trace all requests
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Sampled: true" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# When error rate is moderate (1-5%), trace 50% of requests
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "X-Sampled: true" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# When error rate is low (<1%), trace 10% of requests
curl -H "X-Sampled: false" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

Trace Correlation

Correlating with Logs

# Example: Correlating logs with traces
# When making API requests, include trace context in logs

# API Request
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Log entry should include trace context:
# {
#   "timestamp": "2024-01-15T10:30:00Z",
#   "level": "INFO",
#   "message": "Making API request",
#   "trace_id": "trace_123456789",
#   "span_id": "span_987654321",
#   "url": "/api/v2/tours"
# }

Correlating with Metrics

# Example: Correlating metrics with traces
# Record metrics with trace context

# API Request
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Metrics should include trace context:
# {
#   "trace_id": "trace_123456789",
#   "span_id": "span_987654321",
#   "api_latency_ms": 150,
#   "database_queries": 3,
#   "timestamp": "2024-01-15T10:30:00Z"
# }

Debugging with Traces

Finding Slow Requests

# Example: Analyzing trace performance
# Get trace details and analyze performance

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/trace_123456789

# Response includes performance analysis:
# {
#   "trace_id": "trace_123456789",
#   "total_duration": 2500,
#   "slow_spans": [
#     {
#       "operation": "database.query",
#       "duration": 1800
#     }
#   ],
#   "bottlenecks": [
#     {
#       "operation": "database.query",
#       "duration": 1800,
#       "percentage": "72.00"
#     }
#   ]
# }

Error Analysis

# Example: Analyzing trace errors
# Get trace details and identify errors

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/trace_123456789

# Response includes error analysis:
# {
#   "trace_id": "trace_123456789",
#   "errors": [
#     {
#       "operation": "database.query",
#       "error_message": "Connection timeout",
#       "duration": 5000
#     }
#   ]
# }

Performance Monitoring

Trace Metrics

# Example: Collecting trace metrics
# Monitor trace performance over time

# Get trace metrics
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/traces/metrics

# Response includes aggregated metrics:
# {
#   "total_traces": 1000,
#   "total_duration": 2500000,
#   "error_count": 25,
#   "slow_traces": 50,
#   "average_duration": 2500,
#   "error_rate": 0.025,
#   "slow_trace_rate": 0.05
# }

Best Practices

Trace ID Generation

# Good: Use timestamp-based IDs with UUID
# trace_1642233600000_a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Bad: Use simple random numbers
# trace_abc123def

Span Management

# Example: Managing spans in a multi-step operation
# Start span for tour creation
curl -X POST https://api.tourfold.com/api/v2/tours \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_tour_001" \
  -H "X-Parent-Span-ID: span_main" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Vienna City Tour"}'

# Start child span for stop creation
curl -X POST https://api.tourfold.com/api/v2/tours/tour_123/stops \
  -H "X-Trace-ID: trace_123456789" \
  -H "X-Span-ID: span_stop_001" \
  -H "X-Parent-Span-ID: span_tour_001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vienna Opera House"}'

Trace Propagation

# Example: Extracting trace context from response headers
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Response headers include trace context:
# X-Trace-ID: trace_123456789
# X-Span-ID: span_987654321

# Use these values in subsequent requests:
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours/tour_123/stops

Testing Traces

Unit Testing

# Example: Testing trace header propagation
# Make a request and verify trace headers are included

curl -v -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Verify response includes trace headers:
# < X-Trace-ID: trace_123456789
# < X-Span-ID: span_987654321

Integration Testing

# Example: Testing trace correlation with logs
# Make a request and verify trace correlation

# Request with trace context
curl -H "X-Trace-ID: trace_123456789" \
     -H "X-Span-ID: span_987654321" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.tourfold.com/api/v2/tours

# Verify logs include trace context:
# {
#   "timestamp": "2024-01-15T10:30:00Z",
#   "level": "INFO",
#   "message": "Starting request",
#   "trace_id": "trace_123456789",
#   "span_id": "span_987654321"
# }

Next steps

• Learn about Error handling
• Understand Rate limiting