Documentation Grafana Cloud Knowledge graph Configure Telemetry correlation Profiles

Configure profiles correlation

Profiles correlation configurations map entity properties to Pyroscope labels, enabling automatic profile filtering when you view an entity. The knowledge graph generates queries that show CPU and memory profiles specific to the selected entity and time range.

Before you begin

Ensure you have:

• Continuous profiling data flowing to Grafana Cloud Pyroscope
• A Pyroscope data source configured in Grafana
• Application instrumented for profiling (automatic for supported languages)

Create a profiles configuration

To create a profiles correlation configuration:

1. Navigate to Observability > Configuration > Profiles.
2. Click Add profile config.
3. Enter a descriptive name for the configuration.
4. Select the Pyroscope data source from the Data source dropdown.
5. (Optional) Filter by entity types to apply this configuration only to specific types (Service, Pod, Node).
6. Configure entity property to Pyroscope label mappings.
7. (Optional) Add property matchers to control when this configuration applies.
8. Click Save configuration.

The configuration is now available for matching entities.

Configure property mappings

Property mappings connect entity properties to Pyroscope labels. The knowledge graph uses these mappings to filter profile data.

Add a property mapping

1. In the Entity property to Pyroscope label section, click Add mapping.
2. Select the entity property from the first dropdown (for example, otel_namespace).
3. Select or enter the Pyroscope label from the second dropdown (for example, namespace).
4. Add additional mappings as needed.

Common property mappings

For OpenTelemetry instrumented applications with continuous profiling:

Pyroscope labels depend on your profiling instrumentation. The labels shown above are typical for applications instrumented with Grafana Alloy or OpenTelemetry auto-instrumentation.

Example configuration

A typical profiles configuration for Kubernetes services maps:

• otel_service → service_name
• namespace → namespace
• cluster → cluster
• version → version

When viewing a Service entity with otel_service=frontend and version=2.1.0, the knowledge graph automatically applies the implicit filter service_name=frontend and adds the configured mapping version=2.1.0 to show only CPU and memory profiles from that service version.

Configure property matchers

Property matchers control which entities use this profiles configuration. For example, you can create separate configurations for production services or specific application 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 profiles configurations, the knowledge graph selects the first matching configuration based on priority order. To change priority:

1. Navigate to Observability > Configuration > Profiles.
2. Click Change priority.
3. Drag configurations into the desired order.
4. 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 profiles

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

Pyroscope-specific issues

Property mappings don’t match Pyroscope labels:

• Verify the Pyroscope label names in your data source
• Update the configuration to use the correct label names
• Check that your profiling instrumentation includes the expected labels

No profile data available:

• Verify continuous profiling is enabled for the service
• Check that profile data is being sent to Grafana Cloud
• Confirm the Pyroscope data source is correctly configured
• Refer to Send profile data for instrumentation guidance

Profile availability

Not all services send profiling data. The Profiles tab gracefully handles missing data by:

• Showing a message when no profile data exists
• Providing links to profiling instrumentation documentation
• Suggesting configuration adjustments if the service should have profiles

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

Apply configuration for testing

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

1. Find the configuration you want to test in the Profiles configurations list.
2. Click Apply configuration.
3. The knowledge graph temporarily applies that configuration and shows profile results.
4. 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 profiles would look with different mappings.

Manage profiles configurations using Terraform

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

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

Next steps

• Configure logs correlation
• Configure traces correlation
• Explore telemetry data
• Send profile data