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 tracing data. It 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
  • Trace ID: 32 lowercase hex digits (16 bytes), not all zeros
  • Span ID: 16 lowercase hex digits (8 bytes), not all zeros
  • Trace Flags: 2 hex digits

The tracestate field must be a comma-separated list of key-value pairs, with at most 32 pairs and each key at most once:

  • Keys: up to 256 lowercase letters, digits, _, -, *, and /, starting with a letter, or a multi-tenant key of the form tenant@system
  • Values: 1 to 256 printable ASCII characters, excluding commas and equal signs, and not ending in a space
  • Spaces and tabs around a pair, as well as empty entries between commas, are allowed

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, the traceparent and tracestate values are returned in their canonical form: hex digits in lowercase, and the pairs of a tracestate separated by single commas, without the whitespace and empty entries around them. A value written in that form, as tracing libraries write it, comes back unchanged. 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.