Menu

OpenTelemetry Instrumentation Attributes

This documentation outlines the partial OpenTelemetry support for our Go integration. If you're looking to send metrics to AppSignal directly via an OpenTelemetry package rather than an AppSignal integration please visit our OpenTelemetry beta documentation.

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 create a new span or fetch the current active one.

Go
// Create a new span
func httpHandler(w http.ResponseWriter, r *http.Request) {
	ctx, span := tracer.Start(r.Context(), "hello-span")
	defer span.End()
 
	// Do stuff
}
 
// Fetch current span
func httpHandler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()
    span := trace.SpanFromContext(ctx)
 
	// Do stuff
}

AppSignal attributes

Namespace

This attribute applies to the entire trace. It can be set on a child span, and does not need to be set on the uppermost parent span. This attribute can only be set once per trace. If it is set multiple times, only the attribute from one span in the trace is applied.

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

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

Go
span.SetAttributes(attribute.String("appsignal.namespace", "admin"))

Root name

This attribute applies to the entire trace. It can be set on a child span, and does not need to be set on the uppermost parent span. This attribute can only be set once per trace. If it is set multiple times, only the attribute from one span in the trace is applied.

  • 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.

Go
span.SetAttributes(attribute.String("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.

Go
span.SetAttributes(attribute.String("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.

Go
span.SetAttributes(attribute.String("appsignal.body", "Extra information about the span"))

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

Do not send Personal Identifiable Information (PII) to AppSignal. You must ensure that PII (such as personal names, email addresses, passwords, etc.) is filtered before data is sent to AppSignal. If you must identify a person, consider using a user ID, hash or pseudonymized identifier instead.

SQL body

Available since standalone agent version 0.0.29.
  • 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.

Go
span.SetAttributes(attribute.String("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.

Go
span.SetAttributes(attribute.String("appsignal.category", "span.group"))

Tag

Do not use tagging to send personal data such as names or email addresses to AppSignal. If you want to identify a person, consider using a user ID, hash, or pseudonymized identifier instead. You could also use Link Templates to link them back to them in your application.

  • 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.

Go
span.SetAttributes(attribute.String("appsignal.tag.<tag_name>", "string")) // Example format
span.SetAttributes(attribute.String("appsignal.tag.user_id", user.id))

Request parameters

This attribute applies to the entire trace. It can be set on a child span, and does not need to be set on the uppermost parent span. This attribute can only be set once per trace. If it is set multiple times, only the attribute from one span in the trace is applied.

Do not use tagging to send personal data such as names or email addresses to AppSignal. If you want to identify a person, consider using a user ID, hash, or pseudonymized identifier instead. You could also use Link Templates to link them back to them in your application.

This attribute's value needs to be serialized to a JSON string. It does not support a Hash or object from the integration language directly and will be silently ignored.

  • 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.

Go
params = ... // Convert parameters to JSON
span.SetAttributes(attribute.String("appsignal.request.parameters", parameters))

Request session data

This attribute applies to the entire trace. It can be set on a child span, and does not need to be set on the uppermost parent span. This attribute can only be set once per trace. If it is set multiple times, only the attribute from one span in the trace is applied.

Do not use tagging to send personal data such as names or email addresses to AppSignal. If you want to identify a person, consider using a user ID, hash, or pseudonymized identifier instead. You could also use Link Templates to link them back to them in your application.

This attribute's value needs to be serialized to a JSON string. It does not support a Hash or object from the integration language directly and will be silently ignored.

  • 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.

Go
session_data = ... // Convert session data to JSON
span.SetAttributes(attribute.String("appsignal.request.session_data", session_data))

Request headers

This attribute applies to the entire trace. It can be set on a child span, and does not need to be set on the uppermost parent span. This attribute can only be set once per trace. If it is set multiple times, only the attribute from one span in the trace is applied.

Do not use tagging to send personal data such as names or email addresses to AppSignal. If you want to identify a person, consider using a user ID, hash, or pseudonymized identifier instead. You could also use Link Templates to link them back to them in your application.

  • 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.

Go
span.SetAttributes(attribute.String("appsignal.request.headers.<header name>", "value")) // Example format
span.SetAttributes(attribute.String("appsignal.request.headers.content_type", "application/json"))

Custom data

This attribute applies to the entire trace. It can be set on a child span, and does not need to be set on the uppermost parent span. This attribute can only be set once per trace. If it is set multiple times, only the attribute from one span in the trace is applied.

Do not use tagging to send personal data such as names or email addresses to AppSignal. If you want to identify a person, consider using a user ID, hash, or pseudonymized identifier instead. You could also use Link Templates to link them back to them in your application.

This attribute's value needs to be serialized to a JSON string. It does not support a Hash or object from the integration language directly and will be silently ignored.

  • 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.

Go
custom_data = ... // Convert custom data to JSON
span.SetAttributes(attribute.String("appsignal.custom_data", custom_data))