Configuring Loki Data Source

1. Setting Loki URL and Authentication

Property	Value	Description
url	`http://loki:3100`	URL of the Loki server instance
basicAuth	`true`	Enable basic authentication for Loki
basicAuthUser	`loki`	Username for basic authentication
basicAuthPassword	`loki-password`	Password for basic authentication

Example: Grafana Loki Data Source Configuration

{
  "name": "Loki",
  "type": "loki",
  "url": "http://loki:3100",
  "access": "proxy",
  "basicAuth": true,
  "basicAuthUser": "loki",
  "basicAuthPassword": "loki-password"
}

2. Configuring Maximum Lines

Option	Values	Notes
max_lines	`1000`	Maximum number of log lines to return per query
max_lines_limit	`5000`	Hard limit for max_lines (configurable in Loki config)

Example: Setting max_lines in Grafana

datasources:
  - name: loki
    type: loki
    access: proxy
    url: http://loki:3100
    jsonData:
      maxLines: 1000

Note: Adjust max_lines based on your dashboard performance needs and log volume.

3. Setting Derived Fields

Field Name	Description	Example	Notes
name	The name of the derived field	`status_code`	Must be unique within the data source
matcherRegex	Regular expression to extract the field value	`status_code=(\d+)`	Uses Go-style regex syntax
url	URL to link the field value to	`https://httpstatuses.com/$$value$$`	Supports variable substitution with `$$value$$`
index	Index of the capturing group in the regex	`1`	Defaults to 0 (entire match)

Example: Extracting Log Fields

{
  "name": "status_code",
  "matcherRegex": "status_code=(\\d+)",
  "url": "https://httpstatuses.com/$value$",
  "index": 1
}

Note: Derived fields are applied to logs matching the configured regex pattern. Ensure that the regex is correctly capturing the intended field value.

4. Configuring Timeout Settings

Setting	Default Value	Description
timeout	`30s`	Timeout for requests to Loki data source
idle_conn_timeout	`90s`	Timeout for idle connections
max_idle_conns	`100`	Maximum number of idle connections to keep open

Example: Timeout Configuration in Grafana

{
  "timeout": "60s",
  "idle_conn_timeout": "120s",
  "max_idle_conns": 50
}

5. Using Custom Headers

Header Name	Value	Description
Authorization	`Bearer <token>`	Token for authenticating with Loki
X-Scope-OrgID	`tenant-id`	Organization ID for multi-tenancy support
User-Agent	`grafana-loki-datasource/2.0`	Identifies the datasource version

Example: Configuring Custom Headers in Grafana

{
  "name": "Loki",
  "type": "loki",
  "access": "proxy",
  "url": "http://localhost:3100",
  "jsonData": {
    "customHeaders": {
      "Authorization": "Bearer <your-token>",
      "X-Scope-OrgID": "tenant-123"
    }
  }
}

Note: Custom headers are sent with every request to the Loki server. Ensure tokens and IDs are properly escaped in configuration files.

6. Setting Alerting Integration

Property	Description	Values	Notes
alerting.enabled	Enables or disables alerting integration	`true` / `false`	Default: `false`
alerting.rule_path	Path to alert rules directory	`/etc/grafana/alerts`	Must be readable by Grafana process
alerting.eval_interval	How often to evaluate alert rules	`30s`, `1m`, `5m`	Default: `30s`

Example: Alerting Configuration

[alerting]
enabled = true
rule_path = /etc/grafana/alerts
eval_interval = 1m

Note: Alerting requires Loki to be configured with remote_write and remote_read endpoints for storing and retrieving alerting data.

Alerting Integration Options

Internal Alerting: Built-in Grafana alerting engine
External Alertmanager: Integrates with Prometheus Alertmanager
Loki Alerting Rules: Define rules directly in Loki config

7. Configuring Multiple Loki Instances

Example: Adding Multiple Loki Data Sources

datasources:
  - name: "Loki-Primary"
    type: loki
    uid: "loki-primary"
    access: proxy
    url: "http://loki-primary:3100"
    jsonData:
      maxLines: 1000
  - name: "Loki-Secondary"
    type: loki
    uid: "loki-secondary"
    access: proxy
    url: "http://loki-secondary:3100"
    jsonData:
      maxLines: 1000

Field	Description	Notes
name	Name of the Loki data source	Must be unique within Grafana
type	Must be `loki`	Required for Loki data source
uid	Unique identifier for the data source	Used internally by Grafana
url	URL to the Loki instance	Must be accessible from Grafana server
jsonData.maxLines	Maximum number of log lines to return	Default is 1000

Note: Ensure that each Loki instance is accessible from the Grafana server and that appropriate authentication is configured if required.

8. Setting Label Browser Options

Option	Values	Description
labelBrowser.enabled	`true` \| `false`	Enables or disables the label browser in the Loki data source configuration.
labelBrowser.refreshInterval	`30s`, `1m`, `5m`	Defines how often the label browser refreshes the available labels from Loki.
labelBrowser.maxLabelNames	`100`, `500`	Maximum number of label names to fetch from Loki for display in the browser.
labelBrowser.maxLabelValues	`1000`, `5000`	Maximum number of label values to fetch for each label name.

Example: Loki Data Source Configuration with Label Browser

{
  "name": "Loki",
  "type": "loki",
  "url": "http://localhost:3100",
  "jsonData": {
    "labelBrowser": {
      "enabled": true,
      "refreshInterval": "1m",
      "maxLabelNames": 500,
      "maxLabelValues": 2000
    }
  }
}

9. Configuring Query Patterns

Pattern	Description	Example
LogQL	Query language for Loki logs	`{job="nginx"} \|= "error"`
LogQL with regex	Filter logs using regex patterns	`{job="app"} \|= "ERROR" \|~ ".timeout."`
LogQL with labels	Filter logs by label values	`{job="web", env="prod"} \|= "500"`
LogQL with time range	Filter logs within a specific time window	`{job="api"} \|= "error" [1h]`
LogQL with aggregation	Aggregate logs using functions like count, rate, etc.	`{job="app"} \|= "error" \| count by (level)`

Example: Basic LogQL Query

{job="nginx"} |= "error"

Example: Regex Filter in LogQL

{job="app"} |= "ERROR" |~ ".*timeout.*"

Example: Aggregation with LogQL

{job="app"} |= "error" | count by (level)

10. Testing Loki Connection

Example: Test Loki connection via Grafana UI

curl -X GET \
  "http://localhost:3000/api/datasources/uid/loki-datasource" \
  -H "Authorization: Bearer <your-api-token>"

Field	Description	Value
datasource.uid	Unique identifier for the Loki data source	`loki-datasource`
datasource.name	Name of the data source as configured in Grafana	`Loki`
datasource.type	Type of the data source (e.g., Loki)	`loki`

Note: Ensure the Loki server is running and accessible from Grafana's network.

Warning: If the connection fails, check the Loki server URL and authentication settings.