traceparent-malformed

• Route: write-events
• Description: one of these texts, which names the first part that is wrong:
  • traceparent is malformed: expected four parts separated by '-', when the value does not have four parts
  • traceparent is malformed: the version must be two hexadecimal digits
  • traceparent is malformed: the trace ID must be 32 lowercase hexadecimal digits, not all zero
  • traceparent is malformed: the parent ID must be 16 lowercase hexadecimal digits, not all zero
  • traceparent is malformed: the trace flags must be two hexadecimal digits
• Details: event, the place of the event in its list, counting from 0, and value, the traceparent as the request gave it.

Why It Happens#

A traceparent links an event to a distributed trace, see Integrating OpenTelemetry. It has four parts separated by hyphens: a version of two hexadecimal digits, a trace ID of 32 and a parent ID of 16 lowercase hexadecimal digits, neither of them all zeros, and trace flags of two hexadecimal digits, such as 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. The parts are checked in this order. A trace ID or a parent ID with uppercase digits is refused as well, with the text about its part.

A typical cause is a value in another format, such as a trace ID alone, or an empty string where a client sets the field without having a trace.

How to Fix It#

Send the traceparent as W3C Trace Context writes it, which tracing libraries such as OpenTelemetry do, or leave it out where an event has no trace. Sending the same request again fails the same way, since the error depends on the request alone.

Example#

For a write whose first event has a trace ID alone as its traceparent, EventSourcingDB answers with this error, as a line of the stream, and then ends the stream with its end item:

{
  "type": "error",
  "data": {
    "code": "https://docs.eventsourcingdb.io/errors/traceparent-malformed",
    "description": "traceparent is malformed: expected four parts separated by '-'",
    "details": {
      "event": 0,
      "value": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  }
}