Configure traces correlation

Traces correlation configurations map entity properties to Tempo labels, enabling automatic trace filtering when you view an entity. The knowledge graph generates TraceQL queries that show only the traces relevant to the selected entity and time range.

Before you begin

Ensure you have:

Traces flowing to Grafana Cloud Tempo
A Tempo data source configured in Grafana
OpenTelemetry instrumentation with resource attributes

Create a traces configuration

To create a traces correlation configuration:

Navigate to Observability > Configuration > Traces.
Click Add trace config.
Enter a descriptive name for the configuration.
Select the Tempo data source from the Data source dropdown.
(Optional) Filter by entity types to apply this configuration only to specific types (Service, Pod, Node).
Configure entity property to Tempo label mappings.
(Optional) Add property matchers to control when this configuration applies.
Click Save configuration.

The configuration is now available for matching entities.

Configure property mappings

Property mappings connect entity properties to Tempo resource attributes and span labels. The knowledge graph uses these mappings to generate TraceQL queries.

Add a property mapping

In the Entity property to Tempo label section, click Add mapping.
Select the entity property from the first dropdown (for example, cluster).
Select or enter the Tempo label from the second dropdown (for example, resource.k8s.cluster.name).
Add additional mappings as needed.

Common property mappings

For OpenTelemetry instrumented applications:

Entity property	Tempo label	Purpose
`cluster`	`resource.k8s.cluster.name`	Kubernetes cluster
`container`	`resource.container`	Container name
`namespace`	`resource.k8s.namespace.name`	Kubernetes namespace
`otel_namespace`	`resource.service.namespace`	Service namespace
`otel_service`	`resource.service.name`	Service identifier

Tempo uses OpenTelemetry semantic conventions with the resource. prefix for resource attributes. Check your Tempo data source to confirm available labels.

Example configuration

A typical traces configuration for Kubernetes services maps:

cluster → resource.k8s.cluster.name
namespace → resource.k8s.namespace.name
otel_namespace → resource.service.namespace
otel_service → resource.service.name

When viewing a service with otel_service=payment-service and cluster=prod-us-east, the knowledge graph generates a TraceQL query filtering by those resource attributes.

Configure property matchers

Property matchers control which entities use this traces configuration. For example, you can create separate configurations for different regions or service types.

To add property matchers, use the Entity property matchers section in the configuration form. You can match on any entity property using operations like equals, contains, or is not null.

For complete information about property matchers and available operations, refer to Entity property matchers in the overview.

Manage priority and defaults

When you have multiple traces configurations, the knowledge graph selects the first matching configuration based on priority order. To change priority:

Navigate to Observability > Configuration > Traces.
Click Change priority.
Drag configurations into the desired order.
Click Save priority.

A default configuration always exists as a fallback when no custom configuration matches.

For complete information about priority-based matching and default configurations, refer to the overview.

Troubleshoot missing traces

If traces don’t appear when viewing an entity, the Traces tab displays diagnostic information showing which configuration was evaluated and why it didn’t match.

Tempo-specific issues

Property mappings don’t match Tempo resource attributes:

Verify the resource attribute names in your Tempo data source
Update the configuration to use the correct attribute names (remember the resource. or span. prefix)
Check that your traces include the expected resource attributes

No traces with correct attributes:

Confirm traces are flowing to the Tempo data source
Verify the entity’s time range overlaps with available trace data
Check that your OpenTelemetry instrumentation includes the mapped attributes

For general troubleshooting guidance, refer to Troubleshoot missing data in the overview.

Apply configuration for testing

In the Traces tab diagnostic panel, you can test a configuration without making it permanent:

Find the configuration you want to test in the Traces configurations list.
Click Apply configuration.
The knowledge graph temporarily applies that configuration and shows trace results.
If the results are correct, edit the configuration’s property matchers to make it apply automatically.

This workflow helps troubleshoot why a specific configuration isn’t matching or to preview how traces would look with different mappings.

Manage traces configurations using Terraform

You can also manage traces configurations using Terraform for infrastructure as code workflows. This enables version control, automated deployments, and consistent trace correlation across environments.

For information about managing trace configurations with Terraform, refer to Configure trace correlation using Terraform.