NerdGraph distributed trace data tutorial

You can use New Relic's NerdGraph GraphiQL explorer to query your distributed tracing data. This document explains:

  • Trace metadata that's only available with NerdGraph
  • Example queries of trace data

Trace metadata

In addition to span event and transaction event data, we calculate additional metadata about the trace and its span relationships. To query this metadata, go to the NerdGraph GraphiQL explorer at https://api.newrelic.com/graphiql.

Additional trace-level data:

Trace-level metadata Description
durationMs The duration of this trace in milliseconds.
entities All entities that are part of this trace.
entityCount The number of entities that are part of this trace.
spanConnections Parent/child IDs that represent all of the span relationships within this trace.
timestamp Epoch milliseconds timestamp representing the trace's start time.

Additional span-level data:

Span-level metadata Description
clientType For a client span, this indicates the type of entity called: DATASTORE or EXTERNAL.
entityGuid The New Relic identifier for the entity that sent the span.
processBoundary The position of a span with respect to the boundaries between processes: ENTRY, EXIT, or IN_PROCESS.
spanAnomalies Anomalies detected for a span, compared to similar spans that occurred over the previous hours before this span occurred. Anomalous spans appear in the trace UI.

For more about trace structure and span relationships, see Trace structure.

Trace data query examples

Here are example NerdGraph queries of distributed tracing data:

Query by trace ID

This NerdGraph query example shows how to return all data for a trace by using a trace's traceId. Note that attributes is used to return Span event attributes.

{
  actor {
    distributedTracing {
      trace(traceId: "YOUR_TRACE_ID") {
        spans {
          attributes
          clientType
          durationMs
          entityGuid
          id
          name
          parentId
          processBoundary
          timestamp
          traceId
                spanAnomalies {
                      anomalousValue
                      anomalyType
                      averageMeasure
                }
        }
      }
    }
  }
}

For more about trace structure and span relationships, see Trace structure.

Query span relationship data

This NerdGraph query example shows how to return trace-level metadata about the relationships between spans:

{
  actor {
    distributedTracing {
      trace(traceId: "YOUR_TRACE_ID") {
        id
	timestamp
        durationMs
        spanConnections {
          parent
          child
        }
      }
    }
  }
}

For more about trace structure and span relationships, see Trace structure.

Query data of the entities in a trace

This NerdGraph query example returns the entities associated with a trace and some data about those entities.

{
  actor {
    distributedTracing {
      trace(traceId: "YOUR_TRACE_ID") {
        entities {
          name
          tags {
            key
          }
          account {
            name
          }
        }
      }
    }
  }
}

For more help

Recommendations for learning more: