Correlations: link data sources

1. What is a correlation? #

Linking signals across data sources.

The principle #

Available in: ✓ OSS ✓ Enterprise ✓ Cloud Grafana 10 and later; used in Explore

A correlation defines a link between a source data source and a target: a query in another data source, or an external URL. Grafana then adds a link on the values of a result field: from a Loki log line, a click on the traceID opens the trace in Tempo; from a host name, a click opens its metrics in Prometheus.

Unlike derived fields or data links, configured per data source or per panel, correlations are managed centrally by the administrator, in a single screen.

The two types #

• Query: the target is a query in a data source (Tempo, Prometheus, Elasticsearch…), opened in Explore next to the source.
• External: the target is a URL (ticketing tool, CMDB, runbook) into which result values are injected.

2. Creating a correlation #

In the UI or through provisioning.

In the UI #

1. Open Administration › Plugins and data › Correlations then Add new.
2. Give a label (the link text) and a description.
3. Pick the type and target: data source and query (with variables such as ${traceId}), or URL.
4. Pick the source data source and the result field that carries the link (for example traceID).
5. Add transformations if needed to extract a value, then save.

You can also create a correlation from Explore, in correlation editor mode, starting from a real result.

Through provisioning #

Correlations are declared in the source data source provisioning file, under the correlations key. They are then versioned and read-only in the UI.

# provisioning/datasources/correlations.yaml
apiVersion: 1
datasources:
  - name: Loki
    type: loki
    uid: loki
    url: http://loki:3100
    correlations:
      - targetUID: tempo
        label: "Open trace"
        description: "Tempo trace for this log line"
        type: query
        config:
          field: traceID
          target:
            query: "${traceId}"
          transformations:
            - type: regex
              field: Line
              expression: 'traceID=(\w+)'
              mapValue: traceId

Good to know: in older versions the type key goes inside config; check the format expected by your version.

3. Variables and transformations #

Building the target query.

Variables #

In the target query or URL, ${name} is replaced by the value of the field with the same name in the clicked row. Transformations create new variables from a field.

Target Prometheus query: rate(http_requests_total{instance="${host}"}[5m])
External URL: https://tickets.example.com/new?service=${service}&trace=${traceId}

Transformations #

Line: level=error service=api traceID=4bf92f3577b34da6 duration=812ms
logfmt → ${level}, ${service}, ${traceID}, ${duration}

Common mistake: a variable missing from the clicked row: the link does not appear. Check the exact field name (case-sensitive) in the row details.

4. Permissions, limits and best practices #

What to know before rolling out.

Permissions and limits #

• Managing correlations is restricted to organization administrators (or roles granted through role-based access control).
• Links appear in Explore (log details, table cells); in dashboards, use data links or derived fields.
• Users need access to the target data source to follow a query link.

Best practices #

• Start with the most frequent investigation paths: log → trace, trace → service metrics, alert → runbook.
• Use explicit action labels (« Open trace », « Show host metrics »).
• Normalize field names (traceID, service.name) at collection time, with Alloy or the OpenTelemetry Collector, to reuse the same correlations everywhere.
• Provision correlations with the data sources to get identical ones on every environment.

Good practice: combine correlations with Tempo trace-to-logs links: investigations then flow both ways between logs and traces.