diff --git a/docs/sources/datasources/loki/alerting/index.md b/docs/sources/datasources/loki/alerting/index.md index 8136d4178e4..3b090535a9d 100644 --- a/docs/sources/datasources/loki/alerting/index.md +++ b/docs/sources/datasources/loki/alerting/index.md @@ -55,25 +55,25 @@ Loki alerting requires **metric queries** that return numeric time series data. ### Query types and alerting compatibility -| Query type | Alerting support | Notes | -| ------------- | ---------------- | ------------------------------------------------ | -| Metric query | ✅ Full support | Use range aggregation functions like `rate()` | -| Log query | ❌ Not supported | Convert to metric query using aggregations | -| Instant query | ⚠️ Limited | Range queries recommended for time-based alerts | +| Query type | Alerting support | Notes | +| ------------- | ---------------- | ----------------------------------------------- | +| Metric query | ✅ Full support | Use range aggregation functions like `rate()` | +| Log query | ❌ Not supported | Convert to metric query using aggregations | +| Instant query | ⚠️ Limited | Range queries recommended for time-based alerts | ### Common metric functions for alerting Use these LogQL functions to convert log queries into metric queries suitable for alerting: -| Function | Description | Example | -| ------------------- | ------------------------------------------------ | ---------------------------------------------------- | -| `rate()` | Rate of log entries per second | `rate({job="app"}[5m])` | -| `count_over_time()` | Count of log entries in the specified interval | `count_over_time({job="app"}[5m])` | -| `sum_over_time()` | Sum of extracted numeric values | `sum_over_time({job="app"} \| unwrap latency [5m])` | -| `avg_over_time()` | Average of extracted numeric values | `avg_over_time({job="app"} \| unwrap latency [5m])` | -| `max_over_time()` | Maximum extracted value in the interval | `max_over_time({job="app"} \| unwrap latency [5m])` | -| `bytes_rate()` | Rate of bytes per second | `bytes_rate({job="app"}[5m])` | -| `absent_over_time()`| Returns 1 if no logs exist in the interval | `absent_over_time({job="app"}[5m])` | +| Function | Description | Example | +| -------------------- | ---------------------------------------------- | --------------------------------------------------- | +| `rate()` | Rate of log entries per second | `rate({job="app"}[5m])` | +| `count_over_time()` | Count of log entries in the specified interval | `count_over_time({job="app"}[5m])` | +| `sum_over_time()` | Sum of extracted numeric values | `sum_over_time({job="app"} \| unwrap latency [5m])` | +| `avg_over_time()` | Average of extracted numeric values | `avg_over_time({job="app"} \| unwrap latency [5m])` | +| `max_over_time()` | Maximum extracted value in the interval | `max_over_time({job="app"} \| unwrap latency [5m])` | +| `bytes_rate()` | Rate of bytes per second | `bytes_rate({job="app"}[5m])` | +| `absent_over_time()` | Returns 1 if no logs exist in the interval | `absent_over_time({job="app"}[5m])` | ## Create an alert rule @@ -176,4 +176,3 @@ Follow these best practices when creating Loki alerts: - **Test queries first:** Verify your query returns expected numeric results in Explore before creating an alert. - **Use meaningful thresholds:** Base alert thresholds on historical patterns in your log data. - **Add context with labels:** Include relevant labels in your alert to help with triage. - diff --git a/docs/sources/datasources/loki/annotations/index.md b/docs/sources/datasources/loki/annotations/index.md index 811b329aee7..73646317d9c 100644 --- a/docs/sources/datasources/loki/annotations/index.md +++ b/docs/sources/datasources/loki/annotations/index.md @@ -62,13 +62,13 @@ Use the query field to enter a LogQL expression that filters the log events to d **Examples:** -| Query | Description | -| --------------------------------------------------- | --------------------------------------------------- | -| `{job="app"}` | Shows all logs from the "app" job. | -| `{job="app"} \|= "error"` | Shows logs containing "error" from the "app" job. | -| `{namespace="production"} \|= "deployed"` | Shows deployment events in production. | -| `{job="app"} \| logfmt \| level="error"` | Shows error-level logs using logfmt parsing. | -| `{job="$job"}` | Uses a template variable to filter by job. | +| Query | Description | +| ----------------------------------------- | ------------------------------------------------- | +| `{job="app"}` | Shows all logs from the "app" job. | +| `{job="app"} \|= "error"` | Shows logs containing "error" from the "app" job. | +| `{namespace="production"} \|= "deployed"` | Shows deployment events in production. | +| `{job="app"} \| logfmt \| level="error"` | Shows error-level logs using logfmt parsing. | +| `{job="$job"}` | Uses a template variable to filter by job. | You can use template variables in your annotation queries to make them dynamic based on dashboard selections. @@ -141,4 +141,3 @@ To create dynamic annotations that respond to dashboard variable selections: - **Tags:** `severity` This configuration displays only alerts for the selected job, making the annotations relevant to the current dashboard context. - diff --git a/docs/sources/datasources/loki/configure/index.md b/docs/sources/datasources/loki/configure/index.md index d2681877ec8..f13f4bd0aae 100644 --- a/docs/sources/datasources/loki/configure/index.md +++ b/docs/sources/datasources/loki/configure/index.md @@ -93,45 +93,45 @@ You are taken to the **Settings** tab where you will set up your Loki configurat The following are the configuration options for Loki. -| Name | Description | -| ---- | ----------- | -| **Name** | The data source name. This is how you refer to the data source in panels and queries. Examples: `loki-1`, `loki_logs`. | -| **Default** | Toggle to set this data source as the default. When enabled, new panels automatically use this data source. | +| Name | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------------- | +| **Name** | The data source name. This is how you refer to the data source in panels and queries. Examples: `loki-1`, `loki_logs`. | +| **Default** | Toggle to set this data source as the default. When enabled, new panels automatically use this data source. | ### Connection section -| Name | Description | -| ---- | ----------- | +| Name | Description | +| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **URL** | The URL of your Loki server, including the port. The default Loki port is `3100`. Examples: `http://localhost:3100`, `http://loki.example.org:3100`. | ### Authentication section Select an authentication method from the **Authentication** dropdown. -| Setting | Description | -| ---- | ----------- | -| **No authentication** | No authentication is required to access the data source. | -| **Basic authentication** | Authenticate using a username and password. Enter the credentials in the **User** and **Password** fields. | -| **Forward OAuth identity** | Forward the OAuth access token (and the OIDC ID token if available) of the user querying the data source. | +| Setting | Description | +| -------------------------- | ---------------------------------------------------------------------------------------------------------- | +| **No authentication** | No authentication is required to access the data source. | +| **Basic authentication** | Authenticate using a username and password. Enter the credentials in the **User** and **Password** fields. | +| **Forward OAuth identity** | Forward the OAuth access token (and the OIDC ID token if available) of the user querying the data source. | ### TLS settings Use TLS (Transport Layer Security) for an additional layer of security when working with Loki. For more information on setting up TLS encryption with Loki, refer to [Grafana Loki configuration parameters](https://grafana.com/docs/loki/latest/configuration/). -| Setting | Description | -| ---- | ----------- | -| **Add self-signed certificate** | Enable to add a self-signed CA certificate. When enabled, enter the certificate in the **CA Certificate** field. The certificate must begin with `-----BEGIN CERTIFICATE-----`. | -| **TLS Client Authentication** | Enable to use client certificate authentication. When enabled, enter the **ServerName** (for example, `domain.example.com`), **Client Certificate** (begins with `-----BEGIN CERTIFICATE-----`), and **Client Key** (begins with `-----BEGIN RSA PRIVATE KEY-----`). | -| **Skip TLS certificate validation** | Enable to bypass TLS certificate validation. Use this option only for testing or when connecting to Loki instances with self-signed certificates. | +| Setting | Description | +| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Add self-signed certificate** | Enable to add a self-signed CA certificate. When enabled, enter the certificate in the **CA Certificate** field. The certificate must begin with `-----BEGIN CERTIFICATE-----`. | +| **TLS Client Authentication** | Enable to use client certificate authentication. When enabled, enter the **ServerName** (for example, `domain.example.com`), **Client Certificate** (begins with `-----BEGIN CERTIFICATE-----`), and **Client Key** (begins with `-----BEGIN RSA PRIVATE KEY-----`). | +| **Skip TLS certificate validation** | Enable to bypass TLS certificate validation. Use this option only for testing or when connecting to Loki instances with self-signed certificates. | ### HTTP headers Use HTTP headers to pass along additional context and metadata about the request/response. -| Setting | Description | -| ---- | ----------- | +| Setting | Description | +| ---------- | -------------------------------------------------------------- | | **Header** | The name of the custom header. For example, `X-Custom-Header`. | -| **Value** | The value of the custom header. For example, `Header value`. | +| **Value** | The value of the custom header. For example, `Header value`. | Click **+ Add another header** to add additional headers. @@ -141,25 +141,25 @@ Additional settings are optional settings that you can configure for more contro ### Advanced HTTP settings -| Setting | Description | -| ------- | ----------- | +| Setting | Description | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **Allowed cookies** | Specify cookies by name that should be forwarded to the data source. The Grafana proxy deletes all forwarded cookies by default. | -| **Timeout** | The HTTP request timeout in seconds. If not set, the default Grafana timeout is used. | +| **Timeout** | The HTTP request timeout in seconds. If not set, the default Grafana timeout is used. | ### Alerting Manage alert rules for the Loki data source. For more information, refer to [Alerting](ref:alerting). -| Setting | Description | -| ------- | ----------- | +| Setting | Description | +| ------------------------------------- | ---------------------------------------------------------------------------------- | | **Manage alert rules in Alerting UI** | Toggle to manage alert rules for this Loki data source in the Grafana Alerting UI. | ### Queries Configure options to customize your querying experience. -| Setting | Description | -| ------- | ----------- | +| Setting | Description | +| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Maximum lines** | The maximum number of log lines returned by Loki. The default is `1000`. Increase for larger result sets during ad-hoc analysis. Decrease if your browser is sluggish when displaying log results. | ### Derived fields @@ -168,15 +168,15 @@ Derived fields can be used to extract new fields from a log message and create a Click **+ Add** to add a derived field. Each derived field has the following settings: -| Setting | Description | -| ------- | ----------- | -| **Name** | The field name. Displayed as a label in the log details. | -| **Type** | The type of derived field. Select **Regex in log line** to extract values using a regular expression, or **Label** to use an existing label value. | -| **Regex** | A regular expression to parse a part of the log message and capture it as the value of the new field. Can contain only one capture group. | -| **URL** | The full link URL if the link is external, or a query for the target data source if the link is internal. You can interpolate the value from the field with the `${__value.raw}` macro. For example, `http://example.com/${__value.raw}`. | -| **URL Label** | A custom display label for the link. This setting overrides the link label, which defaults to the full external URL or name of the linked internal data source. | -| **Internal link** | Toggle to define an internal link. When enabled, you can select the target data source from a selector. This supports only tracing data sources. | -| **Open in new tab** | Toggle to open the link in a new browser tab or window. | +| Setting | Description | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Name** | The field name. Displayed as a label in the log details. | +| **Type** | The type of derived field. Select **Regex in log line** to extract values using a regular expression, or **Label** to use an existing label value. | +| **Regex** | A regular expression to parse a part of the log message and capture it as the value of the new field. Can contain only one capture group. | +| **URL** | The full link URL if the link is external, or a query for the target data source if the link is internal. You can interpolate the value from the field with the `${__value.raw}` macro. For example, `http://example.com/${__value.raw}`. | +| **URL Label** | A custom display label for the link. This setting overrides the link label, which defaults to the full external URL or name of the linked internal data source. | +| **Internal link** | Toggle to define an internal link. When enabled, you can select the target data source from a selector. This supports only tracing data sources. | +| **Open in new tab** | Toggle to open the link in a new browser tab or window. | {{< admonition type="caution" >}} Using complex regular expressions can impact browser performance when processing large volumes of logs. Consider using simpler patterns when possible. @@ -360,4 +360,4 @@ After configuring your Loki data source, explore these resources: - [Query the Loki data source](ref:loki-query-editor) to learn how to build LogQL queries in Grafana - [Use template variables](ref:loki-template-variables) to create dynamic, reusable dashboards -- [LogQL documentation](https://grafana.com/docs/loki/latest/query/) to learn more about the Loki query language \ No newline at end of file +- [LogQL documentation](https://grafana.com/docs/loki/latest/query/) to learn more about the Loki query language diff --git a/docs/sources/datasources/loki/query-editor/index.md b/docs/sources/datasources/loki/query-editor/index.md index 7751449f08c..060a47388cf 100644 --- a/docs/sources/datasources/loki/query-editor/index.md +++ b/docs/sources/datasources/loki/query-editor/index.md @@ -138,11 +138,11 @@ You can type while the operations dropdown is open to search and filter the list Each operation appears as a box in the query editor. Hover over an operation's header to reveal action buttons: -| Button | Action | -| ------ | ------ | -| {{< figure src="/static/img/docs/v95/loki_operation_replace.png" class="docs-image--no-shadow" max-width="30px" >}} | Replace the operation with a different operation of the same type. | -| {{< figure src="/static/img/docs/v95/loki_operation_description.png" class="docs-image--no-shadow" max-width="30px" >}} | Open the operation's description tooltip. | -| {{< figure src="/static/img/docs/v95/loki_operation_remove.png" class="docs-image--no-shadow" max-width="30px" >}} | Remove the operation. | +| Button | Action | +| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| {{< figure src="/static/img/docs/v95/loki_operation_replace.png" class="docs-image--no-shadow" max-width="30px" >}} | Replace the operation with a different operation of the same type. | +| {{< figure src="/static/img/docs/v95/loki_operation_description.png" class="docs-image--no-shadow" max-width="30px" >}} | Open the operation's description tooltip. | +| {{< figure src="/static/img/docs/v95/loki_operation_remove.png" class="docs-image--no-shadow" max-width="30px" >}} | Remove the operation. | Some operations only make sense in a specific order. If adding an operation would result in an invalid query, the editor automatically places it in the correct position. To re-order operations manually, drag the operation box by its name and drop it in the desired location. @@ -178,13 +178,13 @@ The autocompletion dropdown includes documentation for suggested items where ava The following options are available in both Builder and Code mode. Expand the **Options** section to configure them. -| Option | Description | -| ------ | ----------- | -| **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. `instant` queries a single point in time (uses the "To" time from the time range). `range` queries over the selected time range. | -| **Line limit** | Defines the maximum number of log lines returned by a query. Default is `1000`. | -| **Direction** | Determines the search order. **Backward** searches from the end of the time range (default). **Forward** searches from the beginning. | -| **Step** | Sets the step parameter for metric queries. Default is `$__auto`, calculated using the time range and graph width. | +| Option | Description | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **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. `instant` queries a single point in time (uses the "To" time from the time range). `range` queries over the selected time range. | +| **Line limit** | Defines the maximum number of log lines returned by a query. Default is `1000`. | +| **Direction** | Determines the search order. **Backward** searches from the end of the time range (default). **Forward** searches from the beginning. | +| **Step** | Sets the step parameter for metric queries. Default is `$__auto`, calculated using the time range and graph width. | ### Query stats @@ -232,12 +232,12 @@ Metric queries use LogQL to extract numeric data from logs. You wrap a log query ### Common metric query patterns -| Function | Description | Example | -| -------- | ----------- | ------- | -| `rate()` | Calculates the number of log entries per second | `rate({job="app"}[5m])` | -| `count_over_time()` | Counts log entries over the specified interval | `count_over_time({job="app"}[1h])` | -| `bytes_rate()` | Calculates bytes per second of log entries | `bytes_rate({job="app"}[5m])` | -| `sum_over_time()` | Sums extracted numeric values | `sum_over_time({job="app"} \| unwrap duration [5m])` | +| Function | Description | Example | +| ------------------- | ----------------------------------------------- | ---------------------------------------------------- | +| `rate()` | Calculates the number of log entries per second | `rate({job="app"}[5m])` | +| `count_over_time()` | Counts log entries over the specified interval | `count_over_time({job="app"}[1h])` | +| `bytes_rate()` | Calculates bytes per second of log entries | `bytes_rate({job="app"}[5m])` | +| `sum_over_time()` | Sums extracted numeric values | `sum_over_time({job="app"} \| unwrap duration [5m])` | ### Build a metric query diff --git a/docs/sources/datasources/loki/troubleshooting/index.md b/docs/sources/datasources/loki/troubleshooting/index.md index 16f60f36b15..47e0ada4f91 100644 --- a/docs/sources/datasources/loki/troubleshooting/index.md +++ b/docs/sources/datasources/loki/troubleshooting/index.md @@ -127,12 +127,12 @@ The following errors occur when there are issues with LogQL query syntax or exec **Common syntax issues:** -| Issue | Incorrect | Correct | -| ----- | --------- | ------- | -| Missing quotes | `{job=app}` | `{job="app"}` | -| Wrong operator | `{job=="app"}` | `{job="app"}` | -| Unbalanced braces | `{job="app"` | `{job="app"}` | -| Invalid regex | `{job=~"["}` | `{job=~"\\["}` | +| Issue | Incorrect | Correct | +| ----------------- | -------------- | -------------- | +| Missing quotes | `{job=app}` | `{job="app"}` | +| Wrong operator | `{job=="app"}` | `{job="app"}` | +| Unbalanced braces | `{job="app"` | `{job="app"}` | +| Invalid regex | `{job=~"["}` | `{job=~"\\["}` | ### Query limits exceeded @@ -240,11 +240,11 @@ The following issues don't always produce specific error messages but are common **Query optimization tips:** -| Slow | Fast | -| ---- | ---- | +| Slow | Fast | +| ----------------------------------------- | ------------------------------------------------- | | `{namespace="prod"} \|~ "error.*timeout"` | `{namespace="prod", level="error"} \|= "timeout"` | -| `{job=~".+"}` (matches all) | `{job="specific-job"}` | -| Wide time range, no filters | Narrow time range with label filters | +| `{job=~".+"}` (matches all) | `{job="specific-job"}` | +| Wide time range, no filters | Narrow time range with label filters | ### Labels not appearing in dropdown @@ -383,4 +383,3 @@ When reporting issues, include the following information: - Sample LogQL query (if applicable, with sensitive data redacted) - Time range of the query - Approximate volume of logs being queried -