Skip to main content

Transaction ID (Txid)

Overview​

The TXID Policy is designed to assign a unique transaction ID to each incoming request. This ID allows tracking of requests across different services, facilitating debugging, monitoring, and logging in distributed systems. The policy ensures that each request is tagged with a x-txid header, which can later be used for tracing and analysis.

Why use TXID?​

  • Helps in troubleshooting and identifying issues in API transactions.
  • Improves observability in distributed systems.
  • Enables logging consistency across different API layers.

Configuration Details​

Transaction ID Header (x-txid)​

  • The policy automatically generates a unique x-txid header for every incoming request.
  • This ID remains consistent throughout the lifecycle of the request, ensuring traceability across different services.
  • Example:
x-txid: 550e8400-e29b-41d4-a716-446655440000
  • If the service does not already include an x-txid header, the system generates one automatically.

W3C Activation​

The policy provides an optional W3C activation setting. When enabled, the system follows the W3C Trace Context Specification instead of using the x-txid header.

  • When W3C is disabled (default):
    • The system assigns a transaction ID to the x-txid header.
  • When W3C is enabled:
    • Instead of x-txid, an HTTP header called traceparent is passed.
    • The traceparent header is formatted according to the W3C Trace Context standard.
    • This allows interoperability with external logging and tracing tools that support the W3C standard.
    • Example:
traceparent: 00-3fcf0fea8f014021927305eb2842715b-59ee61718d864a72-01
  • When combined with stdout-log, the trace information is stored as log data.

Configuration Fields​

FieldDescriptionDefault ValueNotes
x-txid HeaderAutomatically assigns a unique transaction ID for each request.EnabledCannot be changed.
W3C ActivationEnables traceparent header instead of x-txid.DisabledCan be enabled if interoperability with W3C trace tools is required.
Choosing between x-txid and W3C traceparent:
  • If the system relies on standard API tracing mechanisms, x-txid should be used.
  • If interoperability with external observability tools like OpenTelemetry is required, enable W3C traceparent.