Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Knowledge graphbreadcrumb arrow Configurebreadcrumb arrow Telemetry correlationbreadcrumb arrow Logs
Grafana Cloud

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:

Entity propertyLoki labelPurpose
otel_namespaceservice_namespaceService namespace
otel_serviceservice_nameService identifier
clusterk8s_cluster_nameKubernetes cluster
containercontainerContainer name
podpodPod 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 
{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 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.

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

Next steps