mirror of https://github.com/grafana/loki
Docs: revise getting started guide (#5939)
* Revise the getting started section
* Docs: revise getting started guide
* Intermediate commit of getting started material.
* Intermediate revision of the getting started guide.
Add instructions to download, configure, and deploy the test environment.
* Add sample queries and instructions for breaking down the test env
* Revise prose using reviewer comments.
* update to use promtail and flog in the docker compose file
Signed-off-by: Edward Welch <edward.welch@grafana.com>
* Revise guide to put all parts into Docker containers.
* Add README files for examples directory. Revise getting started instructions.
* Address DylanGuedes review comments
* Getting started guide: incorporate suggestions from ssncferreira
Co-authored-by: Edward Welch <edward.welch@grafana.com>
pull/5897/head^2
Karen Miller
4 years ago
committed by
GitHub
parent
149227b889
commit
c4ebfd3020
@ -1,14 +1,142 @@ |
||||
--- |
||||
title: Getting started |
||||
weight: 300 |
||||
description: "This guide assists the reader to create and use a simple Loki cluster for testing and evaluation purposes." |
||||
aliases: |
||||
- /docs/loki/latest/getting-started/get-logs-into-loki/ |
||||
--- |
||||
|
||||
# Getting started with Grafana Loki |
||||
|
||||
> **Note:** You can use [Grafana Cloud](https://grafana.com/products/cloud/features/#cloud-logs) 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](https://grafana.com/auth/sign-up/create-user?pg=docs-loki&plcmt=in-text). |
||||
|
||||
1. [Getting Logs Into Loki](get-logs-into-loki/) |
||||
1. [Grafana](grafana/) |
||||
1. [LogCLI](logcli/) |
||||
1. [Labels](labels/) |
||||
1. [Troubleshooting](troubleshooting/) |
||||
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](https://github.com/mingrammer/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](../fundamentals/architecture/deployment-modes/) 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 |
||||
|
||||
- [Docker](https://docs.docker.com/install) |
||||
- [Docker Compose](https://docs.docker.com/compose/install) |
||||
|
||||
## Obtain the test environment |
||||
|
||||
1. Create a directory called `evaluate-loki` for the test environment. Make `evaluate-loki` your current working directory: |
||||
```bash |
||||
mkdir evaluate-loki |
||||
cd evaluate-loki |
||||
``` |
||||
1. Download `loki-config.yaml`, `promtail-local-config.yaml`, and `docker-compose.yaml`: |
||||
|
||||
```bash |
||||
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 |
||||
|
||||
All shell commands are issued from the `evaluate-loki` directory. |
||||
|
||||
1. With `evaluate-loki` as the current working directory, deploy the test environment using `docker-compose`: |
||||
```bash |
||||
docker-compose up -d |
||||
``` |
||||
1. (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 message `Query 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 returns `ready` when you point a web browser at http://localhost:3102/ready. The message `Ingester 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](https://grafana.com/docs/grafana/latest/) 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](https://grafana.com/docs/grafana/latest/datasources/loki/). |
||||
|
||||
Click on the Grafana instance's [Explore](https://grafana.com/docs/grafana/latest/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](../logql/query_examples/) for more examples. |
||||
|
||||
## Stop and clean up the test environment |
||||
|
||||
To break down the test environment: |
||||
|
||||
- Close the Grafana browser window |
||||
|
||||
- Stop and remove all the Docker containers. With `evaluate-loki` as the current working directory: |
||||
```bash |
||||
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. |
||||
|
||||
1. Stop and clean up an existing test environment: |
||||
``` |
||||
docker-compose down |
||||
``` |
||||
1. Edit the `docker-compose.yaml` file. Within the YAML file, change the `flog.command` field's value to specify your flog output. |
||||
1. Instantiate the new test environment: |
||||
``` |
||||
docker-compose up |
||||
``` |
||||
|
||||
- To keep already-generated logs in the running test environment, restart flog with a new configuration. |
||||
|
||||
1. Edit the `docker-compose.yaml` file. Within the YAML file, change the `flog.command` field's value to specify your flog output. |
||||
1. Restart only the flog app within the currently-running test environment: |
||||
``` |
||||
docker-compose up -d --force-recreate flog |
||||
``` |
||||
|
||||
|
||||
@ -1,78 +0,0 @@ |
||||
--- |
||||
title: Get logs into Loki |
||||
weight: 10 |
||||
--- |
||||
# Get logs into Grafana Loki |
||||
|
||||
After you [install and run Grafana Loki](../../installation/local/), you probably want to get logs from other applications into it. |
||||
|
||||
To get application logs into Loki, you need to edit the [Promtail]({{< relref "../clients/promtail" >}}) configuration file. |
||||
|
||||
Detailed information about configuring Promtail is available in [Promtail configuration](../../clients/promtail/configuration/). |
||||
|
||||
The following instructions should help you get started. |
||||
|
||||
1. If you haven't already, download a Promtail configuration file. Keep track of where it is, because you will need to cite it when you run the binary. |
||||
|
||||
``` |
||||
wget https://raw.githubusercontent.com/grafana/loki/main/clients/cmd/promtail/promtail-local-config.yaml |
||||
``` |
||||
|
||||
1. Open the configuration file in the text editor of your choice. It should look similar to this: |
||||
|
||||
``` |
||||
server: |
||||
http_listen_port: 9080 |
||||
grpc_listen_port: 0 |
||||
|
||||
positions: |
||||
filename: /tmp/positions.yaml |
||||
|
||||
clients: |
||||
- url: http://loki:3100/loki/api/v1/push |
||||
|
||||
scrape_configs: |
||||
- job_name: system |
||||
static_configs: |
||||
- targets: |
||||
- localhost |
||||
labels: |
||||
job: varlogs |
||||
__path__: /var/log/*log |
||||
``` |
||||
|
||||
The seven lines under `scrape_configs` are what send the logs that Promtail generates to Loki, which then outputs them in the command line and http://localhost:3100/metrics. |
||||
|
||||
Copy the seven lines under `scrape_configs`, and then paste them under the original job. You can instead edit the original seven lines. |
||||
|
||||
Below is an example that sends logs from a default Grafana installation to Loki. We updated the following fields: |
||||
- job_name - This differentiates the logs collected from other log groups. |
||||
- targets - Optional for `static_configs`. However, is often defined because in older versions of Promtail it was not optional. This was an artifact from directly using the Prometheus service discovery code, which required this entry. |
||||
- labels - Static label to apply to every log line scraped by this definition. Good examples include the environment name, job name, or app name. |
||||
- __path__ - The path to where the logs that Loki is to consume are stored. |
||||
|
||||
``` |
||||
- job_name: grafana |
||||
static_configs: |
||||
- targets: |
||||
- grafana |
||||
labels: |
||||
job: grafana |
||||
__path__: "C:/Program Files/GrafanaLabs/grafana/data/log/grafana.log" |
||||
``` |
||||
|
||||
1. Enter the following command to run Promtail. Examples below assume you have placed the configuration file in the same directory as the binary. |
||||
|
||||
**Windows** |
||||
|
||||
``` |
||||
.\promtail-windows-amd64.exe --config.file=promtail-local-config.yaml |
||||
``` |
||||
|
||||
**Linux** |
||||
|
||||
``` |
||||
./promtail-linux-amd64 -config.file=promtail-local-config.yaml |
||||
``` |
||||
|
||||
You should now see your application logs. If you are using Grafana, you might need to refresh your instance in order to see the logs. |
||||
|
After Width: | Height: | Size: 36 KiB |
@ -1,57 +0,0 @@ |
||||
--- |
||||
title: Simple scalable cluster |
||||
weight: 35 |
||||
--- |
||||
# Install and deploy a simple scalable cluster with Docker compose |
||||
|
||||
A local Docker compose installation of Grafana Loki and Promtail is appropriate for an evaluation, testing, or development environment. |
||||
Use a Tanka or Helm process for a production environment. |
||||
|
||||
This installation runs Loki in a simple scalable deployment mode with one read path component and one write path component. |
||||
|
||||
## Prerequisites |
||||
|
||||
- [Docker](https://docs.docker.com/install) |
||||
- [Docker Compose](https://docs.docker.com/compose/install) |
||||
|
||||
## Obtain Loki and Promtail configuration files |
||||
|
||||
Download `loki-config.yaml`, `promtail-config.yaml`, and `docker-compose.yaml` to your current directory: |
||||
|
||||
```bash |
||||
wget https://raw.githubusercontent.com/grafana/loki/main/production/simple-scalable/promtail-config.yaml -O promtail-config.yaml |
||||
wget https://raw.githubusercontent.com/grafana/loki/main/production/simple-scalable/loki-config.yaml -O loki-config.yaml |
||||
wget https://raw.githubusercontent.com/grafana/loki/main/production/simple-scalable/docker-compose.yaml -O docker-compose.yaml |
||||
``` |
||||
|
||||
This will download `loki-config.yaml`, `promtail-config.yaml`, and `docker-compose.yaml` to your current directory. |
||||
|
||||
The `docker-compose.yaml` relies on the [Loki docker driver](https://grafana.com/docs/loki/latest/clients/docker-driver/), |
||||
aliased to `loki-compose`, to send logs to the loki cluster. If this driver is not installed on your system, you can install it by running the following: |
||||
|
||||
```bash |
||||
docker plugin install grafana/loki-docker-driver:latest --alias loki-compose --grant-all-permissions |
||||
``` |
||||
|
||||
If this driver is already installed, but under a different alias, you will have to change `docker-compose.yaml` to use the correct alias. |
||||
|
||||
## Deploy and verify readiness of the Loki cluster |
||||
|
||||
From the directory containing the configuration files, deploy the cluster with docker-compose: |
||||
|
||||
```bash |
||||
docker-compose up |
||||
``` |
||||
|
||||
The running Docker containers use the directory's configuration files. |
||||
|
||||
Navigate to http://localhost:3101/ready to check for read container readiness. |
||||
Navigate to http://localhost:3101/metrics to view read container metrics. |
||||
|
||||
Navigate to http://localhost:3102/ready to check for write container readiness. |
||||
Navigate to http://localhost:3102/metrics to view write container metrics. |
||||
|
||||
Navigate to http://localhost:3000 for the Grafana instance that has Loki configured as a datasource. |
||||
|
||||
By default, the image runs processes as user loki with UID `10001` and GID `10001`. |
||||
You can use a different user, specially if you are using bind mounts, by specifying the UID with a `docker run` command and using `--user=UID` with numeric UID suited to your needs. |
||||
@ -1,6 +1,8 @@ |
||||
--- |
||||
title: Loki in Grafana |
||||
weight: 30 |
||||
weight: 15 |
||||
aliases: |
||||
- /docs/loki/latest/getting-started/grafana/ |
||||
--- |
||||
# Loki in Grafana |
||||
|
||||
@ -1,6 +1,8 @@ |
||||
--- |
||||
title: Troubleshooting |
||||
weight: 40 |
||||
weight: 80 |
||||
aliases: |
||||
- /docs/loki/latest/getting-started/troubleshooting/ |
||||
--- |
||||
# Troubleshooting Grafana Loki |
||||
|
||||
@ -0,0 +1,7 @@ |
||||
--- |
||||
title: Tools |
||||
weight: 1050 |
||||
--- |
||||
# Tools |
||||
|
||||
- [LogCLI](logcli/) |
||||
@ -1,6 +1,8 @@ |
||||
--- |
||||
title: LogCLI |
||||
weight: 20 |
||||
aliases: |
||||
- /docs/loki/latest/getting-started/logcli/ |
||||
--- |
||||
# LogCLI, Grafana Loki's command-line interface |
||||
|
||||
@ -0,0 +1,11 @@ |
||||
# Loki examples |
||||
|
||||
This directory contains examples and example configuration for Loki. |
||||
|
||||
## Hosted logs in Grafana Cloud |
||||
|
||||
You can use [Grafana Cloud](https://grafana.com/products/cloud/features/#cloud-logs) 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](https://grafana.com/auth/sign-up/create-user?pg=docs-loki&plcmt=in-text). |
||||
|
||||
## Getting started with Loki |
||||
|
||||
Configuration files in the `getting-started` directory are used by the [Loki getting started guide](https://grafana.com/docs/loki/latest/getting-started/). |
||||
@ -0,0 +1,4 @@ |
||||
# Loki getting started guide configuration |
||||
|
||||
This directory contains configuration to use with the [Loki getting started guide](https://grafana.com/docs/loki/latest/getting-started/). |
||||
|
||||
@ -0,0 +1,22 @@ |
||||
--- |
||||
server: |
||||
http_listen_port: 9080 |
||||
grpc_listen_port: 0 |
||||
|
||||
positions: |
||||
filename: /tmp/positions.yaml |
||||
|
||||
clients: |
||||
- url: http://gateway:3100/loki/api/v1/push |
||||
tenant_id: tenant1 |
||||
|
||||
scrape_configs: |
||||
- job_name: flog_scrape |
||||
docker_sd_configs: |
||||
- host: unix:///var/run/docker.sock |
||||
refresh_interval: 5s |
||||
relabel_configs: |
||||
- source_labels: ['__meta_docker_container_name'] |
||||
regex: '/(.*)' |
||||
target_label: 'container' |
||||
|
||||
@ -1 +0,0 @@ |
||||
.data |
||||
@ -1 +0,0 @@ |
||||
.data |
||||
@ -1,20 +0,0 @@ |
||||
--- |
||||
server: |
||||
http_listen_port: 9080 |
||||
grpc_listen_port: 0 |
||||
|
||||
positions: |
||||
filename: /tmp/positions.yaml |
||||
|
||||
clients: |
||||
- url: http://gateway:3100/loki/api/v1/push |
||||
tenant_id: tenant1 |
||||
|
||||
scrape_configs: |
||||
- job_name: system |
||||
static_configs: |
||||
- targets: |
||||
- localhost |
||||
labels: |
||||
job: varlogs |
||||
__path__: /var/log/*log |
||||
Loading…
Reference in new issue