---
title: "Configure profiles correlation | Grafana Cloud documentation"
description: "Configure how entity properties map to Pyroscope labels for automatic profile correlation"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

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

> Note
> 
> The Profiles tab only appears for Service entities because the profile drilldown view requires a service to be selected before applying other filters. When viewing a Service entity, the knowledge graph automatically applies an implicit filter `service_name=entity.name` in addition to any configured property mappings.

## 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:

Expand table

| Entity property | Pyroscope label | Purpose                                  |
|-----------------|-----------------|------------------------------------------|
| `otel_service`  | `service_name`  | Service identifier (implicitly filtered) |
| `namespace`     | `namespace`     | Service namespace                        |
| `cluster`       | `cluster`       | Kubernetes cluster                       |
| `pod`           | `pod`           | Pod name                                 |
| `container`     | `container`     | Container name                           |
| `version`       | `version`       | Application version                      |

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](../#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](../#priority-based-matching).

## 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](/docs/grafana-cloud/monitor-applications/profiles/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](../#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](/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/profile-configurations/).

## Next steps

- [Configure logs correlation](../logs/)
- [Configure traces correlation](../traces/)
- [Explore telemetry data](/docs/grafana-cloud/knowledge-graph/troubleshoot-infra-apps/explore-entity-catalog/telemetry-data/)
- [Send profile data](/docs/grafana-cloud/monitor-applications/profiles/send-profile-data/)