Package com.babelqueue.otel

Class Tracing

java.lang.Object
com.babelqueue.otel.Tracing
public final class Tracing extends Object
Optional OpenTelemetry tracing for a babelqueue producer or consumer (ADR-0025) — the Java mirror of the Go babelqueue-go/otel, Python babelqueue.otel and Node @babelqueue/core/otel helpers.

Produce/consume spans are correlated across every hop and SDK through the envelope's trace_id — a UUID, which maps 1:1 to a 32-hex OpenTelemetry trace id (traceIdOf(java.lang.String) / uuidOf(java.lang.String)). A non-UUID trace_id is hashed deterministically (SHA-256).

Every hop that shares a trace_id shares one OTel trace. Exact cross-hop span parent-child linkage (W3C traceparent as a transport header) is a documented follow-up.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    publish(io.opentelemetry.api.trace.Tracer tracer, String urn, Map<String,Object> data, Sender send)
    Publishes (urn, data) to the "default" queue under a PRODUCER span.
    static String
    publish(io.opentelemetry.api.trace.Tracer tracer, String urn, Map<String,Object> data, String queue, Sender send)
    Emits a PRODUCER span publish <urn>, carrying the active trace's id into the built envelope's trace_id so the downstream consumer recovers the same trace, then writes the envelope via send.
    static String
    traceIdOf(String traceId)
    Maps an envelope trace_id to a deterministic 32-hex OTel trace id: a UUID maps to its hex bytes; any other string is hashed (SHA-256, first 16 bytes).
    static String
    uuidOf(String traceIdHex)
    Formats a 32-hex OTel trace id as a canonical UUID string — the form a producer stamps into the message's trace_id so a consumer can recover the same trace id via traceIdOf(java.lang.String).
    static Handler
    wrapHandler(io.opentelemetry.api.trace.Tracer tracer, Handler handler)
    Wraps a consume handler to emit a CONSUMER span per message, in the OTel trace derived from the envelope's trace_id, recording the handler's error/status.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • traceIdOf

      public static String traceIdOf(String traceId)
      Maps an envelope trace_id to a deterministic 32-hex OTel trace id: a UUID maps to its hex bytes; any other string is hashed (SHA-256, first 16 bytes). Never the all-zero (invalid) trace id. The inverse of uuidOf(java.lang.String) for the UUID case.
      Parameters:
      traceId - the envelope trace_id
      Returns:
      a valid 32-hex OTel trace id

    • uuidOf

      public static String uuidOf(String traceIdHex)
      Formats a 32-hex OTel trace id as a canonical UUID string — the form a producer stamps into the message's trace_id so a consumer can recover the same trace id via traceIdOf(java.lang.String).
      Parameters:
      traceIdHex - a 32-hex OTel trace id
      Returns:
      the canonical UUID string

    • wrapHandler

      public static Handler wrapHandler(io.opentelemetry.api.trace.Tracer tracer, Handler handler)
      Wraps a consume handler to emit a CONSUMER span per message, in the OTel trace derived from the envelope's trace_id, recording the handler's error/status. The handler receives the full Envelope as before.
      Parameters:
      tracer - the OTel tracer
      handler - the handler to instrument
      Returns:
      the wrapped handler

    • publish

      public static String publish(io.opentelemetry.api.trace.Tracer tracer, String urn, Map<String,Object> data, Sender send) throws Exception
      Publishes (urn, data) to the "default" queue under a PRODUCER span. See publish(Tracer, String, Map, String, Sender).
      Parameters:
      tracer - the OTel tracer
      urn - the message URN
      data - the message data
      send - the transport write
      Returns:
      the published message id (meta.id)
      Throws:
      Exception - if send fails (recorded on the span and re-thrown)

    • publish

      public static String publish(io.opentelemetry.api.trace.Tracer tracer, String urn, Map<String,Object> data, String queue, Sender send) throws Exception
      Emits a PRODUCER span publish <urn>, carrying the active trace's id into the built envelope's trace_id so the downstream consumer recovers the same trace, then writes the envelope via send.
      Parameters:
      tracer - the OTel tracer
      urn - the message URN
      data - the message data
      queue - the destination queue
      send - the transport write
      Returns:
      the published message id (meta.id)
      Throws:
      Exception - if send fails (recorded on the span and re-thrown)