Configure the Loki data source on Grafana Labs

Configure the Loki data source

Fri, 03 Apr 2026 19:43:06 +0000

Loki data source

Grafana ships with built-in support for Loki, an open-source log aggregation system by Grafana Labs. If you are new to Loki the following documentation will help you get started:

Configure the Loki data source

To add the Loki data source, complete the following steps:

Click Connections in the left-side menu.
Under Connections, click Add new connection.
Enter Loki in the search bar.
Select Loki data source.
Click Create a Loki data source in the upper right.

You will be taken to the Settings tab where you will set up your Loki configuration.

Configuration options

The following is a list of configuration options for Loki.

The first option to configure is the name of your connection:

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 select as the default name in dashboard panels. When you go to a dashboard panel this will be the default selected data source.

HTTP section

URL - The URL of your Loki server. Loki uses port 3100. If your Loki server is local, use http://localhost:3100. If it is on a server within a network, this is the URL with port where you are running Loki. Example: http://loki.example.orgname:3100.
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. This must be in seconds. There is no default, so this setting is up to you.

Auth section

There are several authentication methods you can choose in the Authentication section.

Note
Use TLS (Transport Layer Security) for an additional layer of security when working with Loki. For information on setting up TLS encryption with Loki see Grafana Loki configuration parameters.

Basic authentication - The most common authentication method. Use your data source user name and data source password to connect.
With credentials - Toggle on to enable credentials such as cookies or auth headers to be sent with cross-site requests.
TLS client authentication - Toggle on to use client authentication. When enabled, add the Server name, Client cert and Client key. The client provides a certificate that is validated by the server to establish the client’s trusted identity. The client key encrypts the data between client and server.
With CA cert - Authenticate with a CA certificate. Follow the instructions of the CA (Certificate Authority) to download the certificate file.
Skip TLS verify - Toggle on to bypass TLS certificate validation.
Forward OAuth identity - Forward the OAuth access token (and also the OIDC ID token if available) of the user querying the data source.

Custom HTTP headers

Header - Add a custom header. This allows custom headers to be passed based on the needs of your Loki instance.
Value - The value of the header.

Alerting

Manage alert rules in Alerting UI - Toggle on to manage alert rules for the Loki data source. To manage other alerting resources add an Alertmanager data source.

Queries

Maximum lines - Sets the maximum number of log lines returned by Loki. Increase the limit to have a bigger results set for ad-hoc analysis. Decrease the limit if your browser is sluggish when displaying log results. The default is 1000.

Derived fields

Derived Fields are used to extract new fields from your logs and create a link from the value of the field.

For example, you can link to your tracing backend directly from your logs, or link to a user profile page if the log line contains a corresponding userId. These links appear in the log details.

You can add multiple derived fields.

Note
If you use Grafana Cloud, you can request modifications to this feature by clicking Open a Support Ticket from the Grafana Cloud Portal.

Each derived field consists of the following:

Name - Sets the field name. Displayed as a label in the log details.
Type - Defines the type of the derived field. It can be either:

Caution
Using complex regular expressions in either type can impact browser performance when processing large volumes of logs. Consider using simpler patterns when possible.

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.
Label: A label from the selected log line. This can be any type of label - indexed, parsed or structured metadata. When using this type, the input will match as a regular expression against label keys, allowing you to match variations like traceid and trace_id with a single regex pattern like trace[_]?id. The value of the matched label will be used as the value of the derived field.
URL/query Sets 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.
URL Label - Sets 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 on to define an internal link. For internal links, you can select the target data source from a selector. This supports only tracing data sources.
Open in new tab - Toggle on to open the link in a new tab or window.
Show example log message - Click to paste an example log line to test the regular expression of your derived fields.

Click Save & test to test your connection.

Troubleshoot interpolation

You can use a debug section to see what your fields extract and how the URL is interpolated. Select Show example log message to display a text area where you can enter a log message.

The new field with the link shown in log details:

Loki query editor

Fri, 03 Apr 2026 19:43:06 +0000

Loki query editor

The Loki data source’s query editor helps you create log and metric queries that use Loki’s query language, LogQL.

For general documentation on querying data sources in Grafana, refer to Query and transform data.

Choose a query editing mode

The Loki query editor has two modes:

Builder mode, which provides a visual query designer.
Code mode, which provides a feature-rich editor for writing queries.

To switch between the editor modes, select the corresponding Builder and Code tabs.

To run a query, select Run queries located at the top of the editor.

Note
To run Loki queries in Explore, select Run query.

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.

The query editor toolbar contains the following elements:

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.

These include:

Log query starters
Metric query starters

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:

Choose labels to locate.
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.
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.

Explain query - Toggle to display a step-by-step explanation of all query components and operations.

Builder/Code - Click the corresponding Builder or Code tab on the toolbar to select an editor mode.

Builder mode

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.

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. 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

Select the + Operations button to add operations to your query. The query editor groups operations into related sections, and you can type while the operations dropdown is open to search and filter the list.

The query editor displays a query’s operations as boxes in the operations section. Each operation’s header displays its name, and additional action buttons appear when you hover your cursor over the header:

Button	Action
	Replaces the operation with different operation of the same type.
	Opens the operation’s description tooltip.
	Removes the operation.

The query editor groups operations into the following sections:

Aggregations - see Built-in aggregation operators
Range functions - see Range Vector aggregation
Formats - see Log queries
Binary operations - see Binary operators
Label filters - see Label filter expression
Line filters - see Line filter expression

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.

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 to further help you write queries.

For more information about Loki’s query language, refer to the Loki documentation.

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
Direction - Determines the search order. Backward is a backward search starting at the end of the time range. Forward is a forward search starting at the beginning of the time range. The default is Backward
Step Sets the step parameter of Loki metrics queries. The default value equals to the value of $__auto variable, which is calculated using the time range and the width of the graph (the number of pixels).

Create a log query

Loki log queries return the contents of the log lines. You can query and display log data from Loki via Explore, and with the Logs panel in dashboards.

To display the results of a log query, select the Loki data source, then enter a LogQL query.

For more information about log queries and LogQL, refer to the Loki log queries documentation.

Show log context

In Explore, you can can retrieve the context surrounding your log results by clicking the Show Context button. You’ll be able to investigate the logs from the same log stream that came before and after the log message you’re interested in.

The initial log context query is created from all labels defining the stream for the selected log line. You can use the log context query editor to widen the search by removing one or more of the label filters from log stream. Additionally, if you used a parser in your original query, you can refine your search by using extracted labels filters.

To reduce the repetition of selecting and removing the same labels when examining multiple log context windows, Grafana stores your selected labels and applies them to each open context window. This lets you seamlessly navigate through various log context windows without having to reapply your filters.

To reset filters and use the initial log context query, click the Revert to initial query button next to the query preview.

Tail live logs

Loki supports live tailing of logs in real-time in Explore.

Live tailing relies on two Websocket connections: one between the browser and Grafana server, and another between the Grafana server and Loki server.

To start tailing logs click the Live button in the top right corner of the Explore view.

Proxying examples

If you use reverse proxies, configure them accordingly to use live tailing:

Using Apache2 for proxying between the browser and the Grafana server:

ProxyPassMatch "^/(api/datasources/proxy/\d+/loki/api/v1/tail)" "ws://127.0.0.1:3000/$1"

Using NGINX:

This example provides a basic NGINX proxy configuration. It assumes that the Grafana server is available at http://localhost:3000/, the Loki server is running locally without proxy, and your external site uses HTTPS. If you also host Loki behind an NGINX proxy, repeat the following configuration for Loki.

In the http section of NGINX configuration, add the following map definition:

  map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
  }

In your server section, add the following configuration:

  location ~ /(api/datasources/proxy/\d+/loki/api/v1/tail) {
      proxy_pass          http://localhost:3000$request_uri;
      proxy_set_header    Host              $host;
      proxy_set_header    X-Real-IP         $remote_addr;
      proxy_set_header    X-Forwarded-for   $proxy_add_x_forwarded_for;
      proxy_set_header    X-Forwarded-Proto "https";
      proxy_set_header    Connection        $connection_upgrade;
      proxy_set_header    Upgrade           $http_upgrade;
  }

  location / {
      proxy_pass          http://localhost:3000/;
      proxy_set_header    Host              $host;
      proxy_set_header    X-Real-IP         $remote_addr;
      proxy_set_header    X-Forwarded-for   $proxy_add_x_forwarded_for;
      proxy_set_header    X-Forwarded-Proto "https";
  }

Create a metric query

You can use LogQL to wrap a log query with functions that create metrics from your logs.

For more information about metric queries, refer to the Loki metric queries documentation.

Apply annotations

Annotations overlay rich event information on top of graphs. You can add annotation queries in the Dashboard menu’s Annotations view.

You can only use log queries as a source for annotations. Grafana automatically uses log content as annotation text and your log stream labels as tags. You don’t need to create any additional mapping.

Loki template variables

Fri, 03 Apr 2026 19:43:06 +0000

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.

For an introduction to templating and template variables, refer to the Templating and Add and manage variables documentation.

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:

Query type	Example label	Example stream selector	List returned
Label names	Not required	Not required	Label names.
Label values	`label`		Label values for `label`.
Label values	`label`	`log stream selector`	Label values for `label` in the specified `log stream selector`.

Use ad hoc filters

Loki supports the special Ad hoc filters variable type. You can use this variable type to specify any number of key/value filters, and Grafana applies them automatically to all of your Loki queries.

For more information, refer to Add ad hoc filters.

Use $__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 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.

Label extraction and indexing 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

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

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

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.

For instance, if you have a label “job” that represents different services in your application, Loki will index the logs for each job separately. This indexing allows you to quickly query and analyze logs for individual jobs without the need to scan the entire log dataset.

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.

Configure the Loki data source on Grafana Labs

Configure the Loki data source

Loki data source

Configure the Loki data source

Configuration options

HTTP section

Auth section

Custom HTTP headers

Alerting

Queries

Derived fields

Troubleshoot interpolation

Loki query editor

Loki query editor

Choose a query editing mode

Toolbar elements

Builder mode

Label filters

Operations

Hints

Code mode

Use autocompletion

Options

Create a log query

Show log context

Tail live logs

Proxying examples

Create a metric query

Apply annotations

Loki template variables

Loki template variables

Use query variables

Use ad hoc filters

Use $__auto variable for Loki metric queries

Label extraction and indexing in Loki

Label extraction

Indexing labels