OpenTelemetry Instrumentation Attributes

AppSignal is compatible with several OpenTelemetry language integrations. Not always does the data model match one-to-one to show the OpenTelemetry correctly in the AppSignal interface. Using the attributes listed on this page it's possible to customize how the trace and span data appears.

Accessing a span

When customizing the trace or span, first import the OpenTelemetry trace module in the file you want to customize the reported trace data.

# Python
from opentelemetry import trace

Using that trace module, create a new span or fetch the current active one.

# Python
# Create a new span
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("span.group") as span:
    # Do stuff
 
# Fetch current span
span = trace.get_current_span()

AppSignal attributes

Namespace

• Attribute name: appsignal.namespace
• Value type: String

Group traces by namespace for better organization in the AppSignal interface.

# Python
span.set_attribute("appsignal.namespace", "admin")

Root name

• Attribute name: appsignal.root_name
• Value type: String

Set the action name of the trace that will be used to create incidents on AppSignal.com. This will overwrite any automated mapping done by the AppSignal support for specific instrumentation. It is useful for traces that are not created by frameworks. If your trace is not showing up as an incident in the AppSignal interface, it may be missing this attribute.

# Python
span.set_attribute("appsignal.root_name", "ControllerName#action")

Name

• Attribute name: appsignal.name
• Value type: String

Set the name/title of the span as it appears in the performance event timeline in the incident sample detail view. This is the label shown on hover.

# Python
span.set_attribute("appsignal.name", "Fetch users")

Body

• Attribute name: appsignal.body
• Value type: String

Set the body of the span as it appears in the performance event timeline in the incident sample detail view. This is the content shown on hover. This attribute is used for things like the sanitized query that was performed, or the path of the template that was rendered.

# Python
span.set_attribute("appsignal.body", "Extra information about the span")

To store SQL queries in the span's body, please use the SQL body attribute instead.

SQL body

• Attribute name: appsignal.sql_body
• Value type: String

Set a SQL query as the body of the span, so it's available in the incident sample detail view's performance event timeline . This is similar to the body attribute, but is specialized for SQL queries. Any SQL query set as the body with this attribute will be sanitized to avoid sending sensitive data to our servers.

See the Body attribute for more details on how the body attribute works.

When both the appsignal.body and appsignal.sql_body attributes are set, the appsignal.sql_body attribute is leading and the appsignal.body attribute will be ignored.

# Python
span.set_attribute("appsignal.sql_body", "SELECT * FROM users")

Category

• Attribute name: appsignal.category
• Value type: String

To change the name of the span as it appears in the performance event timeline, you'll need to set the span category. If this is not set, the span will be reported as an "unknown" event. For the naming of the events, please refer to the event naming reference.

span.set_attribute("appsignal.category", "span.group")

Tag

• Attribute name: appsignal.tag.<tag_name>
• Value type: String

Tag traces to help filter samples in the AppSignal interface. Multiple tags can be set on spans in a trace. Tags can be added to any span in a trace on any level in the trace.

The tag attribute key is built up out of two parts, the appsignal.tag prefix, and the tag key. For the tag user_id, this becomes appsignal.tag.user_id as an attribute key.

# Python
span.set_attribute("appsignal.tag.<tag_name>", "string") # Example format
span.set_attribute("appsignal.tag.user_id", user.id)

Request parameters

• Attribute name: appsignal.request.parameters
• Value type: JSON serialized object

Report the request parameters or starting arguments for a trace using this attribute. The value stored on this attribute will be shown in the "Parameters" box in the AppSignal interface.

# Python
import json
 
span.set_attribute(
    "appsignal.request.parameters",
    json.dumps({ "GET": { "page": 1 } })
)

Request session data

• Attribute name: appsignal.request.session_data
• Value type: JSON serialized object

Report the request session data for a trace using this attribute. The value stored on this attribute will be shown in the "Session data" box in the AppSignal interface.

# Python
import json
 
span.set_attribute(
    "appsignal.request.session_data",
    json.dumps({ "accepted_cookies": true })
)

Request headers

• Attribute name: appsignal.request.headers.<header name>
• Value type: String

Before using this attribute, we recommend configuring the reported request headers in the OpenTelemetry instrumentation package for the HTTP library or web framework of your application. This attribute can be used to add a request header for specific traces. We do not recommend setting all headers this way.

The request header attribute key is built up out of two parts, the appsignal.request.headers. prefix, and the header key. For the header Content-Type, this becomes appsignal.request.headers.content_type as an attribute key.

# Python
span.set_attribute("appsignal.request.headers.<header name>", "string") # Example format
span.set_attribute("appsignal.request.headers.content_type", "application/json")

Custom data

• Attribute name: appsignal.custom_data
• Value type: JSON serialized object

Report the request parameters or starting arguments for a trace using this attribute. The value stored on this attribute will be shown in the "Custom data" box in the AppSignal interface.

# Python
import json
 
span.set_attribute(
    "appsignal.custom_data",
    json.dumps({ "stroopwaffle": True, "coffee": False })
)