Docs: Loki data sources updates (#72041)
* added new configure loki doc * finished first draft of config doc * changed file name * started updates to query editor * updated config and qury editor * updated index doc config doc and query editor * updated query editor * updates to query editor doc * more updates to query editor and index doc * one small update * updates to query editor doc and index * Update docs/sources/datasources/loki/_index.md Co-authored-by: Matias Chomicki <matyax@gmail.com> * Update docs/sources/datasources/loki/query-editor/index.md Co-authored-by: Matias Chomicki <matyax@gmail.com> * Update docs/sources/datasources/loki/query-editor/index.md Co-authored-by: Matias Chomicki <matyax@gmail.com> * Update docs/sources/datasources/loki/query-editor/index.md Co-authored-by: Ivana Huckova <30407135+ivanahuckova@users.noreply.github.com> * Update docs/sources/datasources/loki/_index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> * made changes suggested in PR --------- Co-authored-by: Matias Chomicki <matyax@gmail.com> Co-authored-by: Ivana Huckova <30407135+ivanahuckova@users.noreply.github.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
This commit is contained in:
lwandz13
co-authored by
Matias Chomicki
Ivana Huckova
Jack Baldry
Matias Chomicki
Ivana Huckova
Jack Baldry
parent
e4649e7099
commit
443b4b0327
@@ -21,15 +21,14 @@ weight: 300
|
||||
|
||||
The Loki data source's query editor helps you create [log]({{< relref "#create-a-log-query" >}}) and [metric]({{< relref "#create-a-metric-query" >}}) queries that use Loki's query language, [LogQL](/docs/loki/latest/logql/).
|
||||
|
||||
This topic explains querying specific to the Loki data source.
|
||||
For general documentation on querying data sources in Grafana, see [Query and transform data]({{< relref "../../../panels-visualizations/query-transform-data" >}}).
|
||||
|
||||
## Choose a query editing mode
|
||||
|
||||
You can switch the Loki query editor between two modes:
|
||||
The Loki query editor has two modes:
|
||||
|
||||
- [Code mode]({{< relref "#code-mode" >}}), which provides a feature-rich editor for writing queries
|
||||
- [Builder mode]({{< relref "#builder-mode" >}}), which provides a visual query designer
|
||||
- [Builder mode]({{< relref "#builder-mode" >}}), which provides a visual query designer.
|
||||
- [Code mode]({{< relref "#code-mode" >}}), which provides a feature-rich editor for writing queries.
|
||||
|
||||
To switch between the editor modes, select the corresponding **Builder** and **Code** tabs.
|
||||
|
||||
@@ -39,38 +38,63 @@ To run a query, select **Run queries** located at the top of the editor.
|
||||
To run Loki queries in [Explore]({{< relref "../../../explore/" >}}), select **Run query**.
|
||||
{{% /admonition %}}
|
||||
|
||||
Each mode is synchronized with the other modes, so you can switch between them without losing your work, although there are some limitations.
|
||||
|
||||
Builder mode doesn't yet support some complex queries.
|
||||
When you switch from Code mode to Builder mode with such a query, the editor displays a popup that explains how you might lose parts of the query if you continue.
|
||||
Each mode is synchronized, so you can switch between them without losing your work, although there are some limitations. Builder mode doesn't support some complex queries.
|
||||
When you switch from Code mode to Builder mode with such a query, the editor displays a warning message that explains how you might lose parts of the query if you continue.
|
||||
You can then decide whether you still want to switch to Builder mode.
|
||||
|
||||
You can also augment queries by using [template variables]({{< relref "./template-variables/" >}}).
|
||||
|
||||
## Code mode
|
||||
## Toolbar elements
|
||||
|
||||
In **Code mode**, you can write complex queries using a text editor with autocompletion features and syntax highlighting.
|
||||
It also contains a [label browser]({{< relref "#label-browser" >}}) to further help you write queries.
|
||||
The query editor toolbar contains the following elements:
|
||||
|
||||
For more information about Loki's query language, refer to the [Loki documentation](/docs/loki/latest/logql/).
|
||||
- **Kick start your query** - Click to see a list of queries that help you quickly get started creating LogQL queries. You can then continue to complete your query.
|
||||
|
||||
### Use autocompletion
|
||||
These include:
|
||||
|
||||
Code mode's autocompletion feature works automatically while typing.
|
||||
- Log query starters
|
||||
- Metric query starters
|
||||
|
||||
The query editor can autocomplete static functions, aggregations, and keywords, and also dynamic items like labels.
|
||||
The autocompletion dropdown includes documentation for the suggested items where available.
|
||||
Click the arrow next to each to see available query options.
|
||||
|
||||
- **Label browser** - Use the Loki label browser to navigate through your labels and values, and build queries.
|
||||
|
||||
To navigate Loki and build a query:
|
||||
|
||||
1. Choose labels to locate.
|
||||
1. Search for the values of your selected labels.
|
||||
|
||||
The search field supports fuzzy search, and the label browser also supports faceting to list only possible label combinations.
|
||||
|
||||
1. Select the **Show logs** button to display log lines based on the selected labels, or select the **Show logs rate** button to show the rate based on metrics such as requests per second. Additionally, you can validate the selector by clicking the **Validate selector** button. Click **Clear** to start from the beginning.
|
||||
|
||||
{{< figure src="/static/img/docs/explore/Loki_label_browser.png" class="docs-image--no-shadow" max-width="800px" caption="The Loki label browser" >}}
|
||||
|
||||
- **Explain query** - Toggle to display a step-by-step explanation of all query components and operations.
|
||||
|
||||
{{< figure src="/static/img/docs/prometheus/explain-results.png" max-width="500px" class="docs-image--no-shadow" caption="Explain results" >}}
|
||||
|
||||
- **Builder/Code** - Click the corresponding **Builder** or **Code** tab on the toolbar to select an editor mode.
|
||||
|
||||
## Builder mode
|
||||
|
||||
Use Builder mode to visually construct queries, without needing to manually enter LogQL.
|
||||
Builder mode helps you build queries using a visual interface without needing to manually enter LogQL. This option is best for users who have limited or no previous experience working with Loki and LogQL.
|
||||
|
||||
### Use the Labels selector
|
||||
### Label filters
|
||||
|
||||
Select labels and their values from the dropdown list.
|
||||
When you select a label, Grafana retrieves available values from the server.
|
||||
|
||||
Use the `+` button to add a label and the `x` button to remove a label.
|
||||
Use the `+` button to add a label and the `x` button to remove a label. You can add multiple labels.
|
||||
|
||||
Select comparison operators from the following options:
|
||||
|
||||
- `=` - equal to
|
||||
- `!=` - is not equal
|
||||
- `=~` - matches regex
|
||||
- `!~` - does not match regex
|
||||
|
||||
Select values by using the dropdown, which displays all possible values based on the label selected.
|
||||
|
||||
### Operations
|
||||
|
||||
@@ -86,17 +110,50 @@ Each operation's header displays its name, and additional action buttons appear
|
||||
| {{< figure src="/static/img/docs/v95/loki_operation_description.png" class="docs-image--no-shadow" max-width="30px" >}} | Opens the operation's description tooltip. |
|
||||
| {{< figure src="/static/img/docs/v95/loki_operation_remove.png" class="docs-image--no-shadow" max-width="30px" >}} | Removes the operation. |
|
||||
|
||||
Some operations have additional parameters under the operation header.
|
||||
For details about each operation, use the `info` button to view the operation's description, or refer to the [Loki documentation](/docs/loki/latest/operations/).
|
||||
The query editor groups operations into the following sections:
|
||||
|
||||
Some operations make sense only when used in a specific order.
|
||||
If adding an operation would result in nonsensical query, the query editor adds the operation to the correct place.
|
||||
To re-order operations manually, drag the operation box by its name and drop it into the desired place.
|
||||
- Aggregations - see [Built-in aggregation operators](/docs/loki/latest/logql/metric_queries/#built-in-aggregation-operators)
|
||||
- Range functions - see [Range Vector aggregation](/docs/loki/latest/logql/metric_queries/#range-vector-aggregation)
|
||||
- Formats - see [Log queries](/docs/loki/latest/logql/log_queries/#log-queries)
|
||||
- Binary operations - see [Binary operators](/docs/loki/latest/logql/#binary-operators)
|
||||
- Label filters - see [Label filter expression](/docs/loki/latest/logql/log_queries/#label-filter-expression)
|
||||
- Line filters - see [Line filter expression](/docs/loki/latest/logql/log_queries/#label-filter-expression)
|
||||
|
||||
#### Hints
|
||||
Some operations make sense only when used in a specific order. If adding an operation would result in nonsensical query, the query editor adds the operation to the correct place.
|
||||
To re-order operations manually, drag the operation box by its name and drop it into the desired place. For additional information see [Order of operations](/docs/loki/latest/logql/#order-of-operations).
|
||||
|
||||
### Hints
|
||||
|
||||
In same cases the query editor can detect which operations would be most appropriate for a selected log stream. In such cases it will show a hint next to the `+ Operations` button. Click on the hint to add the operations to your query.
|
||||
|
||||
## Code mode
|
||||
|
||||
In **Code mode**, you can write complex queries using a text editor with autocompletion feature, syntax highlighting, and query validation.
|
||||
It also contains a [label browser]({{< relref "#label-browser" >}}) to further help you write queries.
|
||||
|
||||
For more information about Loki's query language, refer to the [Loki documentation](/docs/loki/latest/logql/).
|
||||
|
||||
### Use autocompletion
|
||||
|
||||
Code mode's autocompletion feature works automatically while typing.
|
||||
|
||||
The query editor can autocomplete static functions, aggregations, and keywords, and also dynamic items like labels.
|
||||
The autocompletion dropdown includes documentation for the suggested items where available.
|
||||
|
||||
## Options
|
||||
|
||||
The following options are the same for both **Builder** and **Code** mode:
|
||||
|
||||
- **Legend** - Controls the time series name, using a name or pattern. For example, `{{hostname}}` is replaced with the label value for the label `hostname`.
|
||||
|
||||
- **Type** - Selects the query type to run. The `instant` type queries against a single point in time. We use the "To" time from the time range. The `range` type queries over the selected range of time.
|
||||
|
||||
- **Line limit** -Defines the upper limit for the number of log lines returned by a query. The default is `1000`
|
||||
|
||||
- **Step** Sets the step parameter of Loki metrics queries. The default value equals to the value of `$__interval` variable, which is calculated using the time range and the width of the graph (the number of pixels).
|
||||
|
||||
- **Resolution** Deprecated. Sets the step parameter of Loki metrics range queries. With a resolution of `1/1`, each pixel corresponds to one data point. `1/2` retrieves one data point for every other pixel, `1/10` retrieves one data point per 10 pixels, and so on. Lower resolutions perform better.
|
||||
|
||||
## Create a log query
|
||||
|
||||
Loki log queries return the contents of the log lines.
|
||||
@@ -182,45 +239,6 @@ You can use LogQL to wrap a log query with functions that create metrics from yo
|
||||
|
||||
For more information about metric queries, refer to the [Loki metric queries documentation](/docs/loki/latest/logql/metric_queries/).
|
||||
|
||||
## Review toolbar features
|
||||
|
||||
In addition to the **Run query** button and mode switcher, Builder mode provides additional elements:
|
||||
|
||||
| Name | Description |
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| **Kick start your query** | A list of useful operation patterns you can use to add multiple operations to your query. |
|
||||
| **Label browser** | Used to navigate through your labels and values, and also build queries. |
|
||||
| **Explain query** | Displays a step-by-step explanation of all query components and operations. |
|
||||
|
||||
### Label browser
|
||||
|
||||
You can use the Loki label browser to navigate through your labels and values, and build queries.
|
||||
|
||||
**To navigate Loki and build a query:**
|
||||
|
||||
1. Choose labels to locate.
|
||||
1. Search for the values of your selected labels.
|
||||
|
||||
The search field supports fuzzy search, and the label browser also supports faceting to list only possible label combinations.
|
||||
|
||||
1. Select the **Show logs** button to display log lines based on the selected labels, or select the **Show logs rate** button to show the rate based on metrics such as requests per second. Additionally, you can validate the selector by clicking the **Validate selector** button.
|
||||
|
||||
{{< figure src="/static/img/docs/v75/loki_label_browser.png" class="docs-image--no-shadow" max-width="800px" caption="The Loki label browser" >}}
|
||||
|
||||
### Explain query
|
||||
|
||||
This section is only shown if the `Explain query` switch from the query editor top toolbar is set to `on`. It shows a step by step explanation of all query parts and the operations.
|
||||
|
||||
## Configure query settings
|
||||
|
||||
| Name | Description |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Type** | Selects the query type to run. The `instant` type queries against a single point in time. We use the "To" time from the time range. The `range` type queries over the selected range of time. |
|
||||
| **Line limit** | Defines the upper limit for the number of log lines returned by a query. The default is Loki's configured maximum lines limit. |
|
||||
| **Legend** | _(Available only in a dashboard)_ Controls the time series name, using a name or pattern. For example, `{{hostname}}` is replaced with the label value for the label `hostname`. |
|
||||
| **Step** | Sets the step parameter of Loki metrics queries. The default value equals to the value of `$__interval` variable, which is calculated using the time range and the width of the graph (the number of pixels). |
|
||||
| **Resolution** | Deprecated. Sets the step parameter of Loki metrics range queries. With a resolution of `1/1`, each pixel corresponds to one data point. `1/2` retrieves one data point for every other pixel, `1/10` retrieves one data point per 10 pixels, and so on. Lower resolutions perform better. |
|
||||
|
||||
## Apply annotations
|
||||
|
||||
[Annotations]({{< relref "../../../dashboards/build-dashboards/annotate-visualizations" >}}) overlay rich event information on top of graphs.
|
||||
|
||||
Reference in New Issue
Block a user