OpenTelemetry Integration
Distributed tracing for SoliDB with W3C Trace Context propagation
SoliDB supports OpenTelemetry trace context propagation across HTTP requests and cluster communication. This enables end-to-end distributed tracing across services, databases, and cluster nodes.
W3C Trace Context Propagation
SoliDB uses the W3C Trace Context standard for propagating trace information across services.
How Trace Context Works
Incoming Requests
SoliDB extracts the traceparent header from incoming HTTP requests and stores the trace context for the request lifetime.
Span Creation
Each HTTP request creates a child span with the trace context, capturing method, URL, and traceparent header information in structured logs.
Outgoing Requests
When SoliDB makes HTTP calls to other cluster nodes (for replication or sharding), it automatically injects the trace context into the traceparent header.
Traceparent Header Format
The W3C traceparent header follows this format:
Example Request with Trace Context
POST /_api/database/mydb/document/users HTTP/1.1
Host: solidb.example.com
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
Content-Type: application/json
{"data": {"name": "test", "age": 30}}
Cluster Trace Propagation
Trace context is propagated across cluster operations for end-to-end visibility.
Blob Replication
When replicating blobs between cluster nodes, the trace context is automatically included in the replication HTTP requests.
Shard Forwarding
Cross-shard operations propagate trace context when forwarding blob uploads to the appropriate shard owner.
Note: TCP Sync
Binary TCP-based synchronization does not currently propagate trace context (W3C headers are HTTP-specific).
Trace Context in Logs
When trace context is present, it is included in structured log output.
Server logs include traceparent when present on incoming requests:
2026-03-23T11:30:15.123456Z INFO solidb: http_request: method=POST uri=/_api/database/mydb/document/users traceparent=00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
Tip: Use Trace IDs for Debugging
Search your logs for the trace ID to correlate all operations related to a single request across your infrastructure.
Configuration
OpenTelemetry integration is built-in and requires no additional configuration.
Built-in Features
- W3C Trace Context extraction from HTTP headers
- Automatic span creation for HTTP requests
- Trace context injection into outgoing HTTP requests
- Trace context propagation in cluster replication
Future: Full OTLP Export
Full OTLP (OpenTelemetry Protocol) export to tracing backends like Jaeger, Zipkin, and cloud providers is planned for a future release.
Use Cases
Distributed Debugging
Trace requests across multiple services and database operations to identify bottlenecks in complex microservice architectures.
Performance Analysis
Correlate latency spans across cluster nodes to understand end-to-end request performance.
Error Tracking
Link error traces across cluster boundaries to quickly identify the root cause of distributed failures.
Audit Logging
Maintain trace IDs in application logs for complete audit trails of database operations.