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