• /
  • Log in

Trace API: Decorate spans with attributes

This document will explain how to add attributes to trace data sent to the Trace API so that spans display specific properties in the UI.

Why decorate your spans?

When you send data to our Trace API, you can add custom attributes to spans. For example, you might decide to add attributes like customer.id or user.id in order to help you analyze your trace data.

Some expected attribute values cause our distributed tracing UI to display some specific trace properties and details. For example, if a span has an attribute with an error. prefix, the UI displays that span with an error. For another example, a span with an attribute that has a db. prefix will be displayed as a datastore span in the UI, and will have its datastore query highlighted.

Decorating your spans to show specific properties in our UI can help you:

How to decorate your spans with attributes

This table explains how to get spans sent to the Trace API to show up with specific properties in the UI. For property descriptions, see span properties.

Desired span property

UI indicator

How to add property


New Relic distributed tracing error icon

Use an attribute with an error. prefix. For example: error.message.


New Relic distributed tracing external span icon

Use an attribute with an http. prefix. For example: http.method. A span will also appear as an external if it has a child that comes from a different entity.


New Relic distributed tracing datastore span icon

Use an attribute with an db. prefix. For example: db.statement.


New Relic distributed tracing service icon

This cannot be done with an attribute. A span is classified as a service span if it's the root span, or if its parent is from a different entity. If a span has several properties, service span classification takes precedence in the UI.


New Relic distributed tracing in-process span icon

This cannot be done with an attribute. A span is classified as in-process if it hasn't been classified as a service span, datastore span, or external span.

For more on how these span properties are determined and stored, see Trace structure.

Tips for adding attributes:

  • You can add any attribute to a span. For example: you might add an attribute like customer.id so that you could search traces globally for traces containing a specific customer.
  • A span can be in multiple categories. For example, external is a more general category than is datastore, so if a span is classified as both external and datastore, it will be indicated as a datastore span in the UI.

JSON examples

Here are JSON examples showing how to use attributes to set span properties:

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.