Class DatadogIds

java.lang.Object
codes.grow.packages.datadogapm.DatadogIds

public final class DatadogIds extends Object
Datadog <-> OpenTelemetry id conversion (API.md section 3, DECISIONS.md #3).

Datadog stores a trace id as the low 64 bits in unsigned decimal plus, for 128-bit ids, the high 64 bits as 16 lower-case hex characters (_dd.p.tid). OpenTelemetry uses 32 hex characters. Span ids are unsigned 64-bit decimals in Datadog and 16 hex characters in OpenTelemetry. Invalid ids are ValidationExceptions.

  • Method Details

    • toDatadogTraceId

      public static DatadogIds.DatadogTraceId toDatadogTraceId(String traceIdHex)
      Splits an OpenTelemetry trace id (up to 32 hex characters, left-padded) into Datadog's form.
      
       DatadogIds.toDatadogTraceId("a3ce929d0e0e47364bf92f3577b34da6");
       // DatadogTraceId[low64Decimal=5474458728733560230, high64Hex=a3ce929d0e0e4736, is128Bit=true]
       
      Parameters:
      traceIdHex - OpenTelemetry trace id
      Returns:
      the Datadog form
      Throws:
      ValidationException - for an invalid or all-zero id
    • fromDatadogTraceId

      public static String fromDatadogTraceId(String low64Decimal, String high64Hex)
      Joins a Datadog trace id (low 64 bits in decimal, optional _dd.p.tid high half in hex) into a 32-character OpenTelemetry trace id.
      
       DatadogIds.fromDatadogTraceId("1", "ffffffffffffffff"); // "ffffffffffffffff0000000000000001"
       DatadogIds.fromDatadogTraceId("42", null);              // "0000000000000000000000000000002a"
       
      Parameters:
      low64Decimal - low 64 bits, unsigned decimal
      high64Hex - high 64 bits as 16 hex characters; null or empty means zero
      Returns:
      32 lower-case hex characters
      Throws:
      ValidationException - for invalid parts or an all-zero id
    • fromDatadogTraceId

      public static String fromDatadogTraceId(String low64Decimal)
      fromDatadogTraceId(String, String) for a 64-bit id (zero high half).
      Parameters:
      low64Decimal - unsigned decimal
      Returns:
      32 lower-case hex characters
    • toDatadogSpanId

      public static String toDatadogSpanId(String spanIdHex)
      Converts an OpenTelemetry span id (up to 16 hex characters) to Datadog's unsigned decimal.
      Parameters:
      spanIdHex - span id
      Returns:
      unsigned decimal
      Throws:
      ValidationException - for an invalid id
    • fromDatadogSpanId

      public static String fromDatadogSpanId(String decimal)
      Converts a Datadog unsigned decimal span id to 16 lower-case hex characters.
      Parameters:
      decimal - unsigned decimal
      Returns:
      16 lower-case hex characters
      Throws:
      ValidationException - for an invalid id
    • datadogTraceIdString

      public static String datadogTraceIdString(String traceIdHex)
      The trace id in the format Datadog's log correlation (dd.trace_id) and its search API use: 32 lower-case hex characters for a 128-bit id, the low 64 bits in decimal for a 64-bit id.
      Parameters:
      traceIdHex - OpenTelemetry trace id
      Returns:
      the Datadog string form
      Throws:
      ValidationException - for an invalid id
    • normalizeDatadogTraceId

      public static String normalizeDatadogTraceId(String value)
      Normalizes any trace id Datadog returns to 32 lower-case hex characters: a 32-character value is hex, a shorter all-digit value (at most 20 digits) is the 64-bit decimal form, anything else is hex.
      Parameters:
      value - Datadog trace id
      Returns:
      32 lower-case hex characters
      Throws:
      ValidationException - for an invalid id
    • normalizeDatadogSpanId

      public static String normalizeDatadogSpanId(String value)
      Normalizes a Datadog decimal span id to 16 hex characters.
      Parameters:
      value - decimal span id
      Returns:
      16 lower-case hex characters, or "" for an empty or zero id
      Throws:
      ValidationException - for an invalid id
    • traceIdForPath

      public static String traceIdForPath(String traceIdHex)
      The id to put in a GET /api/v2/trace/{id} path. Datadog reads an all-digit id as decimal, so a hex id without a letter is sent as its full decimal value; otherwise lower-case hex.
      Parameters:
      traceIdHex - OpenTelemetry trace id
      Returns:
      path id
      Throws:
      ValidationException - for an invalid id