• EnglishEspañol日本語한국어Português
  • Log inStart now

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


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


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. In order to be indexed on the External services page, either http.url or net.peer.name must be provided.


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


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.


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:

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.