public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

edited the template variables doc

Browse Source
This commit is contained in:
Larissa Wandzura
2026-01-06 16:10:26 -06:00
parent 3f78facce0
commit db96b6c1e3
1 changed files with 47 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/datasources/loki/template-variables/index.md
+47 -23
View File
@@ -38,28 +38,32 @@ refs:
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/
query-editor-options:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/loki/query-editor/#options
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/loki/query-editor/#options
configure-loki:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/loki/configure/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/loki/configure/
---
## Use template variables
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
Grafana refers to such variables as template variables.
# Loki template variables
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables.
Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard.
Grafana refers to such variables as template variables.
Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana lists these variables in dropdown select boxes at the top of the dashboard to help you change the data displayed in your dashboard. Grafana refers to such variables as template variables.
For an introduction to templating and template variables, refer to the [Templating](ref:variables) and [Add and manage variables](ref:add-template-variables) documentation.
## Before you begin
- Ensure you have [configured the Loki data source](ref:configure-loki).
- Your Loki instance should have logs with labels that you want to use as variable values.
## Use query variables
Variables of the type _Query_ help you query Loki for lists of labels or label values.
The Loki data source provides a form to select the type of values expected for a given variable.
The form has these options:
Use _Query_ type variables to dynamically fetch label names or label values from Loki. When you create a query variable with the Loki data source, you can choose what type of data to retrieve:
| Query type | Example label | Example stream selector | List returned |
| ------------ | ------------- | ----------------------- | ---------------------------------------------------------------- |
@@ -67,6 +71,26 @@ The form has these options:
| Label values | `label` | | Label values for `label`. |
| Label values | `label` | `log stream selector` | Label values for `label` in the specified `log stream selector`. |
### Create a query variable
To create a query variable for Loki:
1. Open the dashboard where you want to add the variable.
1. Click **Dashboard settings** (gear icon) in the top navigation.
1. Select **Variables** in the left menu.
1. Click **Add variable**.
1. Enter a **Name** for your variable (for example, `job`, `instance`, `level`).
1. In the **Type** dropdown, select **Query**.
1. In the **Data source** dropdown, select your Loki data source.
1. In the **Query type** dropdown, select **Label names** or **Label values**.
1. If you selected **Label values**, enter the label name in the **Label** field (for example, `job`).
1. Optionally, enter a **Stream selector** to filter the label values (for example, `{namespace="production"}`).
1. Click **Run query** to preview the variable values.
1. Configure display options such as **Multi-value** or **Include All option** as needed.
1. Click **Apply** to save the variable.
You can now use the variable in your Loki queries with the syntax `${variable_name}`. For example, `{job="$job"}` filters logs by the selected job.
## Use ad hoc filters
Loki supports the special **Ad hoc filters** variable type.
@@ -74,27 +98,29 @@ You can use this variable type to specify any number of key/value filters, and G
For more information, refer to [Add ad hoc filters](ref:add-template-variables-add-ad-hoc-filters).
## Use $\_\_auto variable for Loki metric queries
## Use the $\_\_auto variable for Loki metric queries
Consider using the `$__auto` variable in your Loki metric queries, which will automatically be substituted with the [step value](https://grafana.com/docs/grafana/next/datasources/loki/query-editor/#options) for range queries, and with the selected time range's value (computed from the starting and ending times) for instant queries.
Consider using the `$__auto` variable in your Loki metric queries. This variable is automatically substituted with the [step value](ref:query-editor-options) for range queries, and with the selected time range's value (computed from the starting and ending times) for instant queries.
For more information about variables, refer to [Global built-in variables](ref:add-template-variables-global-variables).
## Label extraction and indexing in Loki
## Extract and index labels in Loki
Labels play a fundamental role in Loki's log aggregation and querying capabilities. When logs are ingested into Loki, they are often accompanied by metadata called `labels`, which provide contextual information about the log entries. These labels consist of `key-value` pairs and are essential for organizing, filtering, and searching log data efficiently.
### Label extraction
### Extract labels
During the ingestion process, Loki performs label extraction from log lines. Loki's approach to label extraction is based on `regular expressions`, allowing users to specify custom patterns for parsing log lines and extracting relevant label key-value pairs. This flexibility enables Loki to adapt to various log formats and schemas.
For example, suppose you have log lines in the following format:
**2023-07-25 12:34:56 INFO: Request from IP A.B.C.D to endpoint /api/data**
```
2023-07-25 12:34:56 INFO: Request from IP A.B.C.D to endpoint /api/data
```
To extract labels from this log format, you could define a regular expression to extract the log level ("INFO"), IP address ("A.B.C.D"), and endpoint ("/api/data") as labels. These labels can later be used to filter and aggregate log entries.
To extract labels from this log format, you could define a regular expression to extract the log level (`INFO`), IP address (`A.B.C.D`), and endpoint (`/api/data`) as labels. These labels can later be used to filter and aggregate log entries.
### Indexing labels
### Index labels
Once labels are extracted, Loki efficiently indexes them. The index serves as a lookup mechanism that maps labels to the corresponding log entries. This indexing process enables faster retrieval of logs based on specific label criteria, significantly enhancing query performance.
@@ -102,6 +128,4 @@ For instance, if you have a label "job" that represents different services in yo
By effectively extracting and indexing labels, Loki enables users to perform complex and targeted log queries without compromising on query speed and resource consumption.
Utilizing Loki's indexed labels in combination with Grafana's template variables provides a powerful way to interactively explore and visualize log data. Template variables allow users to create dynamic queries, selecting and filtering logs based on various labels, such as job names, instance IDs, severity levels, or any other contextual information attached to the log entries.
In conclusion, Loki's label extraction and indexing mechanisms are key components that contribute to its ability to handle vast amounts of log data efficiently. By making use of labels and template variables, users can easily gain valuable insights from their log data and troubleshoot issues effectively.
Combining Loki's indexed labels with Grafana template variables provides a powerful way to interactively explore and visualize log data. Template variables let you create dynamic queries that filter logs based on labels such as job names, instance IDs, or severity levels.