Correlation configuration
This documentation topic is designed for Grafana workspaces that support Grafana version 10.x.
For Grafana workspaces that support Grafana version 9.x, see Working in Grafana version 9.
For Grafana workspaces that support Grafana version 8.x, see Working in Grafana version 8.
Each correlation is configured with the following options:
- Label
-
Link label, shown in the visualization.
- Description
-
Optional description.
- Source data source
-
The source of results that have links displayed.
- Results field
-
Defines where the link is shown in a visualization.
- Target query
-
The target query run when a link is clicked.
- Transformations
-
Optional manipulations to the source data included passed to the target query.
For details about creating a correlation, see Create a correlation.
Source data source and result field
Links are shown in Explore visualizations for the results from the correlation’s source data source. A link is assigned to one of the fields from the result provided in the correlation configuration (the results field). Each visualization displays fields with links in a different way.
Target query
The target query is run when a link is clicked in the visualization. You can use the query editor of the selected target data source to specify the target query. Source data results can be accessed inside the target query with variables.
Correlation Variables
You can use variables inside the target query to access the source data related to the query. Correlations use Grafana variable syntax. Variables are filled with values from the source results when the link is chosen. There are two types of variables you can use:
-
Field variables (to access field values and labels).
-
Correlation variables (to access field values and transformations).
Example: If source results contain a field called employee,
the value of the field can be accessed with:
-
A field variable
${__data.fields.employee}. -
A correlation variable that maps the field value above to
${employee}.
In addition to mapping field values to shorter variable names, more correlation variables can be created by applying transformations to existing fields.
Correlation creates a data link only if all variables have values in the selected data row. Global variables are the exception to this rule and are not required to be filled in from the returned data. These variables are interpolated automatically by data sources.
Correlation Transformations
Transformations provide a way to extract more variables out of field values. The output of transformations is a set of new variables that can be accessed as any other variable.
There are two types of transformations: logfmt and regular expression.
Each transformation uses a selected field value as the input. The output of a transformation is a set of new variables based on the type and options of the transformation.
Logfmt transformation
The logfmt transformation deconstructs a field value containing text
formatted with logfmt key/value
pairs
The logfmt transformation only requires specifying the input field name if
you would like the transformation to apply to a different field than the results
field. Example output variables for field = "host=srv001 endpoint=/test
app=foo":
| name | value |
|---|---|
| host | srv001 |
| endpoint | /test |
| app | foo |
Regular expression transformation
The regular expression transformation deconstructs a field value based on the provided regular expression.
Regular expression transformation options:
- field
Input field name
- expression
-
Regular expression. Named capture groups are mapped to variables matching the group name. If non-named matching groups are used a variable is created out of the first match. The value overrides the variable matching the input field or a new variable is created if mapValue is provided (see examples in the following table).
- mapValue
-
Used with simple regex groups without named matching groups. By default, the first match overrides the variable with the name of the field that is used as the input. To change that default behavior you can specify the mapValue property. The provided name is used to create a new variable. This can be useful if your target query requires both the exact value and a part of the value extracted with the transformation.
Example: Assuming the selected field name is employee and the
field value is John Doe.
Various output variables based on expression and mapValue options:
| expression | mapValue | output variables | comment |
|---|---|---|---|
/\w+ (\w+)/ |
- | employee=Doe |
No mapValue provided. The first matching is mapped to the
existing field name variable (employee). |
/(\w+) (\w+)/ |
name | name=John |
The first matching is mapped to a new variable called
name.
|
/(?\w+) (?\w+)/ |
- | firstName=John, lastName=Doe |
When named groups are used they are the names of the output variables and mapValue is ignored. |
/(?\w+) (?\w+)/ |
name | firstName=John, lastName=Doe |
Same as above |
