Configure trace to profiles correlation

Trace to profiles lets you navigate from a span in a trace directly to profiling data in Grafana Pyroscope. When configured, a Profiles for this span button and an embedded flame graph appear in the span details view.

Before you begin

To configure trace to profiles, you need:

• A Tempo data source configured in Grafana
• A Grafana Pyroscope data source configured in Grafana
• An application instrumented with the OpenTelemetry span profiling bridge so that spans include the pyroscope.profile.id attribute
• Editor or Admin permissions in Grafana

{{< admonition type="note" >}} You can't modify a provisioned data source from the Grafana UI. If you're using Grafana Cloud Traces (the pre-configured tracing data source in Grafana Cloud), its settings are read-only. To configure trace to profiles, clone the data source to create an editable copy, or update the provisioning file for self-managed instances. Refer to the Provisioning section for details. {{< /admonition >}}

{{< docs/shared source="grafana" lookup="datasources/tempo-traces-to-profiles.md" leveloffset="+1" version="<GRAFANA_VERSION>" >}}

Provisioning

You can provision the trace to profiles configuration using the tracesToProfiles block in your data source YAML file. For the full provisioning YAML example including all Tempo settings, refer to Provision the Tempo data source.

Verify the integration

After configuring trace to profiles, verify the integration:

1. Open Explore and select your Tempo data source.
2. Run a query to load a trace.
3. Expand a span and confirm that the Profiles for this span button appears in the span details.
4. Click the button and verify that an embedded flame graph loads with profiling data.

Troubleshooting

If trace to profiles links aren't appearing or the flame graph is empty, refer to Trace to logs/metrics/profiles issues in the troubleshooting guide. For additional diagnosis steps, refer to Troubleshoot trace to profiles in the Pyroscope documentation.

If the configuration fields are greyed out, your data source is provisioned. Refer to the Provisioning section for how to update the configuration via YAML.

Next steps

• Configure trace to logs correlation: Navigate from spans to related logs in Loki.
• Configure trace to metrics correlation: Link spans to metrics queries in Prometheus.
• Provision the Tempo data source: Configure the Tempo data source using a YAML file.