Class DatadogMapping

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

public final class DatadogMapping extends Object
Datadog span formats to the SPEC section 5 trace model (API.md sections 2.1 and 4).

Two Datadog shapes are mapped:

  • a trace span as the Agent forwards it and as GET /api/v2/trace/{id} returns it (meta, metrics, nanosecond start/startTime, decimal ids; camelCase or snake_case keys): traceSpanToSpan(JsonNode);
  • a span event of the spans search API (attributes.trace_id, start_timestamp, ...): searchSpanToSpan(JsonNode).

For spans that came in over OTLP the Datadog resource is the OpenTelemetry span name and the Datadog name is the operation (Internal, server.request, ...), so the normalized name is the resource; the Datadog operation is kept as attribute operation_name. Parse JSON with Jackson (as Json.tree(byte[]) does) so ids above 2^53 stay exact.

  • Method Details

    • datadogKind

      public static Span.Kind datadogKind(String value)
      Converts a Datadog span.kind (or OpenTelemetry kind name) to a span kind.
      Parameters:
      value - kind text
      Returns:
      kind (UNSPECIFIED when unknown)
    • traceSpanToSpan

      public static Span traceSpanToSpan(com.fasterxml.jackson.databind.JsonNode raw)
      Maps a Datadog trace span to a span: the Agent's format (trace_id, span_id, parent_id, start, duration, meta, metrics) or the trace-by-id API format (traceID, traceIDFull, spanID, parentID, startTime, endTime, duration).

      The full trace id comes from traceIDFull / trace_id_hex / meta otel.trace_id, else the decimal low 64 bits plus meta _dd.p.tid. Name = Datadog resource, kind = meta span.kind, status = error flag (message from error.message, error.msg or otel.status_description) or meta otel.status_code. Events come from meta events and span_events, links from meta _dd.span_links and span_links. Attributes are the remaining meta (strings) and metrics (numbers), plus operation_name, resource_name and span.type.

      Parameters:
      raw - span object
      Returns:
      span
      Throws:
      ValidationException - for invalid ids
    • traceSpanToSpan

      public static Span traceSpanToSpan(Map<String,?> raw)
      traceSpanToSpan(JsonNode) for a decoded map.
      Parameters:
      raw - span map
      Returns:
      span
    • searchSpanToSpan

      public static Span searchSpanToSpan(com.fasterxml.jackson.databind.JsonNode item)
      Maps one span of the spans search API (data[i] of POST /api/v2/spans/events/search, or its attributes) to a span. Nested span attributes (attributes, custom) are flattened to dotted keys; tags (key:value) are added as attributes. Name = resource_name, kind from span.kind, status error when status is error or error is set; duration from the duration attribute (nanoseconds) when present, else end - start.
      Parameters:
      item - span event
      Returns:
      span
      Throws:
      ValidationException - for invalid ids