Skip to main content

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โ€‹

HeaderDescriptionRequired
X-Trace-IDUnique identifier for the entire traceYes
X-Span-IDUnique identifier for the current spanYes
X-Parent-Span-IDID of the parent span (for nested operations)No
X-SampledWhether 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โ€‹