Skip to content

Integrating OpenTelemetry

This guide explains how to use EventSourcingDB with OpenTelemetry tracing. It covers how to propagate trace context via CloudEvents, how EventSourcingDB handles that context, and what constraints apply.

Overview

EventSourcingDB supports OpenTelemetry trace context propagation using the CloudEvents Distributed Tracing extension. This allows events to carry trace information for distributed tracing across systems.

EventSourcingDB does not generate or modify tracing data. It simply validates, stores, and returns the trace context provided by the client.

Using Trace Context

To associate trace context with an event, add the traceparent field at the top level of the event. You may also include the optional tracestate field. Both fields must appear at the top level of the event, not inside data:

{
  // ...
  "data": {
    // ...
  },
  "traceparent": "00-eb0e08452e7ee4b0d3b8b30987c37951-c31bc0a7013beab8-00",
  "tracestate": "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE"
}

Trace context is entirely optional. If traceparent is omitted, the event is accepted without tracing metadata. However, if tracestate is included, traceparent must also be set. Both fields are strictly validated for correct syntax before an event is accepted.

Trace Context Format

The traceparent field must conform to the W3C Trace Context specification:

<version>-<trace-id>-<span-id>-<trace-flags>
  • Version: 2 hex digits (must be 00)
  • Trace ID: 32 hex digits (16 bytes)
  • Span ID: 16 hex digits (8 bytes)
  • Trace Flags: 2 hex digits

The tracestate field must be a comma-separated list of key-value pairs:

  • Keys: lowercase letters and digits only
  • Values: printable ASCII characters, excluding commas and equal signs
  • Max total length: 512 characters

What Do rojo and congo Mean?

These are example vendor keys from the W3C spec, demonstrating how multiple telemetry systems can share trace metadata. In real applications, you'd use identifiers relevant to your tracing backend (e.g., datadog=..., vendorX=...).

Reading and Observing Trace Context

When events are read or observed, any traceparent and tracestate values are returned exactly as stored – unmodified and in their original form. This allows downstream systems or analysis tools to follow the trace across service boundaries.

{
  // ...
  "data": {
    // ...
  },
  "traceparent": "00-eb0e08452e7ee4b0d3b8b30987c37951-c31bc0a7013beab8-00",
  "tracestate": "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE"
}

Best Practices

  • Always set traceparent when emitting events from a traced operation
  • Use tracestate only if needed by your telemetry backend
  • Validate trace context before writing events
  • Use tools like Jaeger or Grafana Tempo to visualize traces across services

Propagating trace context through events enables end-to-end observability — even in asynchronous, decoupled architectures.