Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Getting started with Grafana Loki
Note: You can use Grafana Cloud to avoid installing, maintaining, and scaling your own instance of Grafana Loki. The free forever plan includes 50GB of free logs. Create an account to get started.
This guide assists the reader to create and use a simple Loki cluster. The cluster is intended for testing, development, and evaluation; it will not meet most production requirements.
The test environment runs the flog app to generate log lines. Promtail is the test environment’s agent (or client) that captures the log lines and pushes them to the Loki cluster through a gateway. In a typical environment, the log-generating app and the agent run together, but in locations distinct from the Loki cluster. This guide runs each piece of the test environment locally, in Docker containers.
Grafana provides a way to pose queries against the logs stored in Loki and visualize query results.
The test environment uses Docker compose to instantiate these parts, each in its own container:
- One single scalable deployment mode Loki instance has:
- One Loki read component
- One Loki write component
- Minio is Loki’s storage back end in the test environment.
- The gateway receives requests and redirects them to the appropriate container based on the request’s URL.
- Flog generates log lines.
- Promtail scrapes the log lines from flog, and pushes them to Loki through the gateway.
- Grafana provides visualization of the log lines captured within Loki.
Prerequisites
Obtain the test environment
Create a directory called
evaluate-loki
for the test environment. Makeevaluate-loki
your current working directory:mkdir evaluate-loki cd evaluate-loki
Download
loki-config.yaml
,promtail-local-config.yaml
, anddocker-compose.yaml
:wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/loki-config.yaml -O loki-config.yaml wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/promtail-local-config.yaml -O promtail-local-config.yaml wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/docker-compose.yaml -O docker-compose.yaml
Deploy the test environment
- With
evaluate-loki
as the current working directory, deploy the test environment usingdocker-compose
:docker-compose up -d
- (Optional) Verify that the Loki cluster is up and running. The read component returns
ready
when you point a web browser at http://localhost:3101/ready. The messageQuery Frontend not ready: not ready: number of schedulers this worker is connected to is 0
will show prior to the read component being ready. The write component returnsready
when you point a web browser at http://localhost:3102/ready. The messageIngester not ready: waiting for 15s after being ready
will show prior to the write component being ready.
Use Grafana and the test environment
Use Grafana to query and observe the log lines captured in the Loki cluster by navigating a browser to http://localhost:3000. The Grafana instance has Loki configured as a datasource.
Click on the Grafana instance’s Explore icon to bring up the explore pane.
Use the Explore dropdown menu to choose the Loki datasource and bring up the Loki query browser.
Try some queries. Enter your query into the Log browser box, and click on the blue Run query button.
To see all the log lines that flog has generated:
{container="evaluate-loki_flog_1"}
The flog app will generate log lines for invented HTTP requests.
To see all GET
log lines, enter the query:
{container="evaluate-loki_flog_1"} |= "GET"
For POST
methods:
{container="evaluate-loki_flog_1"} |= "POST"
To see every log line with a 401 status (unauthorized error):
{container="evaluate-loki_flog_1"} | json | status="401"
To see every log line other than those that contain the value 401:
{container="evaluate-loki_flog_1"} != "401"
Refer to query examples for more examples.
Stop and clean up the test environment
To break down the test environment:
Close the Grafana browser window
With
evaluate-loki
as the current working directory, stop and remove all the Docker containers:docker-compose down
Modifying the flog app output
You can modify the flog app’s log line generation by changing its configuration. Choose one of these two ways to apply a new configuration:
To remove already-generated logs, restart the test environment with a new configuration.
- With
evaluate-loki
as the current working directory, stop and clean up an existing test environment:docker-compose down
- Edit the
docker-compose.yaml
file. Within the YAML file, change theflog.command
field’s value to specify your flog output. - With
evaluate-loki
as the current working directory, instantiate the new test environment:docker-compose up -d
- With
To keep already-generated logs in the running test environment, restart flog with a new configuration.
- Edit the
docker-compose.yaml
file. Within the YAML file, change theflog.command
field’s value to specify your flog output. - With
evaluate-loki
as the current working directory, restart only the flog app within the currently-running test environment:docker-compose up -d --force-recreate flog
- Edit the