---
title: "Configure logs correlation | Grafana Cloud documentation"
description: "Configure how entity properties map to Loki labels for automatic log correlation"
---

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

# Configure logs correlation

Logs correlation configurations map entity properties to Loki labels, enabling automatic log filtering when you view an entity. The knowledge graph generates LogQL queries that show only the logs relevant to the selected entity and time range.

## Before you begin

Ensure you have:

- Logs flowing to Grafana Cloud Loki
- A Loki data source configured in Grafana
- OpenTelemetry or structured logging with consistent labels

## Create a logs configuration

To create a logs correlation configuration:

1. Navigate to **Observability > Configuration > Logs**.
2. Click **Add logs config**.
3. Enter a descriptive name for the configuration.
4. Select the Loki 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 Loki 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 Loki labels. The knowledge graph uses these mappings to generate LogQL queries.

### Add a property mapping

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

### Common property mappings

For OpenTelemetry instrumented applications:

Expand table

| Entity property  | Loki label          | Purpose            |
|------------------|---------------------|--------------------|
| `otel_namespace` | `service_namespace` | Service namespace  |
| `otel_service`   | `service_name`      | Service identifier |
| `cluster`        | `k8s_cluster_name`  | Kubernetes cluster |
| `container`      | `container`         | Container name     |
| `pod`            | `pod`               | Pod name           |

The specific labels depend on your logging instrumentation. Check your Loki data source to confirm available labels.

### Example configuration

A typical logs configuration for production services maps:

- `otel_namespace` → `service_namespace`
- `otel_service` → `service_name`
- `cluster` → `k8s_cluster_name`

When viewing a service with `otel_service=checkout-service` and `otel_namespace=production`, the knowledge graph generates:

logql ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```logql
{service_name="checkout-service", service_namespace="production", k8s_cluster_name="..."}
```

## Configure property matchers

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

1. Navigate to **Observability > Configuration > Logs**.
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 logs

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

### Loki-specific issues

**Property mappings don’t match Loki labels:**

- Verify the Loki label names in your data source.
- Update the configuration to use the correct label names.
- Check that your logs include the expected labels.

**No logs with correct labels:**

- Confirm logs are flowing to the Loki data source.
- Verify the entity’s time range overlaps with available log data.
- Check Loki query performance and limits.

For general troubleshooting guidance, refer to [Troubleshoot missing data](../#troubleshoot-missing-data) in the overview.

## Apply configuration for testing

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

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

## Manage logs configurations using Terraform

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

For information about managing log configurations with Terraform, refer to [Configure log correlation using Terraform](/docs/grafana-cloud/as-code/infrastructure-as-code/terraform/terraform-knowledge-graph/log-configurations/).

## Next steps

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