grafana/docs/sources/shared/datasources/tempo-traces-to-profiles.md

headless	labels
true	products enterprise oss

{{< docs/experimental product="Trace to profiles" featureFlag="traceToProfiles" >}}

Using Trace to profiles, you can use Grafana’s ability to correlate different signals by adding the functionality to link between traces and profiles.

Trace to profiles lets you link your Grafana Pyroscope data source to tracing data. When configured, this connection lets you run queries from a trace span into the profile data.

There are two ways to configure the trace to profiles feature:

• Use a simplified configuration with default query, or
• Configure a custom query where you can use a template language to interpolate variables from the trace or span.

To use trace to profiles, navigate to Explore and query a trace. Each span now links to your queries. Clicking a link runs the query in a split panel. If tags are configured, Grafana dynamically inserts the span attribute values into the query. The query runs over the time range of the (span start time - 60) to (span end time + 60 seconds).

To use trace to profiles, you must have a configured Grafana Pyroscope data source. For more information, refer to the Grafana Pyroscope data source documentation.

Use a simple configuration

To use a simple configuration, follow these steps:

1. Select a Pyroscope data source from the Data source drop-down.

2. Optional: Choose any tags to use in the query. If left blank, the default values of service.name and service.namespace are used.

   The tags you configure must be present in the spans attributes or resources for a trace to profiles span link to appear. You can optionally configure a new name for the tag. This is useful for example if the tag has dots in the name and the target data source doesn't allow using dots in labels. In that case you can for example remap service.name to service_name.

3. Select one or more profile types to use in the query. Select the drop-down and choose options from the menu.

   The profile type or app must be selected for the query to be valid. Grafana doesn't show any data if the profile type or app isn’t selected when a query runs.

4. Do not select Use custom query.

5. Select Save and Test.

Configure a custom query

To use a custom query with the configuration, follow these steps:

1. Select a Pyroscope data source from the Data source drop-down.

2. Optional: Choose any tags that will be used in the query. If left blank, the default values of service.name and service.namespace are used.

   These tags can be used in the custom query with ${__tags} variable. This variable interpolates the mapped tags as list in an appropriate syntax for the data source and will only include the tags that were present in the span omitting those that weren’t present. You can optionally configure a new name for the tag. This is useful in cases where the tag has dots in the name and the target data source doesn't allow using dots in labels. For example, you can remap service.name to service_name in such a case. If you don’t map any tags here, you can still use any tag in the query like this method="${__span.tags.method}".

3. Select one or more profile types to use in the query. Select the drop-down and choose options from the menu.

4. Switch on Use custom query to enter a custom query.

5. Specify a custom query to be used to query profile data. You can use various variables to make that query relevant for current span. The link is shown only if all the variables are interpolated with non-empty values to prevent creating an invalid query. You can interpolate the configured tags using the $__tags keyword.

6. Select Save and Test.

Variables that can be used in a custom query

To use a variable you need to wrap it in ${}. For example, ${__span.name}.

Variable name	Description
__tags	This variable uses the tag mapping from the UI to create a label matcher string in the specific data source syntax. The variable only uses tags that are present in the span. The link is still created even if only one of those tags is present in the span. You can use this if all tags are not required for the query to be useful.
__span.spanId	The ID of the span.
__span.traceId	The ID of the trace.
__span.duration	The duration of the span.
__span.name	Name of the span.
__span.tags	Namespace for the tags in the span. To access a specific tag named version, you would use ${__span.tags.version}. In case the tag contains dot, you have to access it as ${__span.tags["http.status"]}.
__trace.traceId	The ID of the trace.
__trace.duration	The duration of the trace.
__trace.name	The name of the trace.