github.com/yankunsam/loki/v2@v2.6.3-0.20220817130409-389df5235c27/docs/sources/getting-started/_index.md (about)

     1  ---
     2  title: Getting started
     3  weight: 300
     4  description: "This guide assists the reader to create and use a simple Loki cluster for testing and evaluation purposes."
     5  aliases:
     6      - /docs/loki/latest/getting-started/get-logs-into-loki/
     7  ---
     8  
     9  # Getting started with Grafana Loki
    10  
    11  > **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).
    12  
    13  This guide assists the reader to create and use a simple Loki cluster.
    14  The cluster is intended for testing, development, and evaluation;
    15  it will not meet most production requirements.
    16  
    17  The test environment runs the [flog](https://github.com/mingrammer/flog) app to generate log lines.
    18  Promtail is the test environment's agent (or client) that captures the log lines and pushes them to the Loki cluster through a gateway.
    19  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.
    20  
    21  Grafana provides a way to pose queries against the logs stored in Loki and visualize query results.
    22   
    23  ![Simple scalable deployment test environment](simple-scalable-test-environment.png)
    24  
    25  The test environment uses Docker compose to instantiate these parts, each in its own container: 
    26  
    27  - One [single scalable deployment](../fundamentals/architecture/deployment-modes/) mode **Loki** instance has:
    28      - One Loki read component
    29      - One Loki write component
    30      - **Minio** is Loki's storage back end in the test environment.
    31  - The **gateway** receives requests and redirects them to the appropriate container based on the request's URL.
    32  - **Flog** generates log lines.
    33  - **Promtail** scrapes the log lines from flog, and pushes them to Loki through the gateway.
    34  - **Grafana** provides visualization of the log lines captured within Loki.
    35  
    36  ## Prerequisites
    37  
    38  - [Docker](https://docs.docker.com/install)
    39  - [Docker Compose](https://docs.docker.com/compose/install)
    40  
    41  ## Obtain the test environment
    42  
    43  1. Create a directory called `evaluate-loki` for the test environment. Make `evaluate-loki` your current working directory:
    44      ```bash
    45      mkdir evaluate-loki
    46      cd evaluate-loki
    47      ```
    48  1. Download `loki-config.yaml`, `promtail-local-config.yaml`, and `docker-compose.yaml`:
    49  
    50      ```bash
    51      wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/loki-config.yaml -O loki-config.yaml
    52      wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/promtail-local-config.yaml -O promtail-local-config.yaml
    53      wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/docker-compose.yaml -O docker-compose.yaml
    54      ```
    55  
    56  ## Deploy the test environment
    57  
    58  1. With `evaluate-loki` as the current working directory, deploy the test environment using `docker-compose`:
    59      ```bash
    60      docker-compose up -d
    61      ```
    62  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.
    63  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.
    64  
    65  ## Use Grafana and the test environment
    66  
    67  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.
    68  The Grafana instance has Loki configured as a [datasource](https://grafana.com/docs/grafana/latest/datasources/loki/).
    69  
    70  Click on the Grafana instance's [Explore](https://grafana.com/docs/grafana/latest/explore/) icon to bring up the explore pane.
    71  
    72  Use the Explore dropdown menu to choose the Loki datasource and bring up the Loki query browser.
    73  
    74  Try some queries.
    75  Enter your query into the **Log browser** box, and click on the blue **Run query** button.
    76  
    77  To see all the log lines that flog has generated:
    78  ```
    79  {container="evaluate-loki_flog_1"}
    80  ```
    81  
    82  The flog app will generate log lines for invented HTTP requests.
    83  To see all `GET` log lines, enter the query:
    84  
    85  ```
    86  {container="evaluate-loki_flog_1"} |= "GET"
    87  ```
    88  For `POST` methods:
    89  ```
    90  {container="evaluate-loki_flog_1"} |= "POST"
    91  ```
    92  
    93  To see every log line with a 401 status (unauthorized error): 
    94  ```
    95  {container="evaluate-loki_flog_1"} | json | status="401"
    96  ```
    97  To see every log line other than those that contain the value 401: 
    98  ```
    99  {container="evaluate-loki_flog_1"} != "401"
   100  ```
   101  
   102  Refer to [query examples](../logql/query_examples/) for more examples.
   103  
   104  ## Stop and clean up the test environment
   105  
   106  To break down the test environment:
   107  
   108  - Close the Grafana browser window
   109  
   110  - With `evaluate-loki` as the current working directory, stop and remove all the Docker containers:
   111      ```bash
   112      docker-compose down
   113      ```
   114  
   115  ## Modifying the flog app output
   116  
   117  You can modify the flog app's log line generation by changing
   118  its configuration.
   119  Choose one of these two ways to apply a new configuration:
   120  
   121  - To remove already-generated logs, restart the test environment with a new configuration.
   122  
   123      1. With `evaluate-loki` as the current working directory, stop and clean up an existing test environment:
   124          ```
   125          docker-compose down
   126          ```
   127      1. Edit the `docker-compose.yaml` file.  Within the YAML file, change the `flog.command` field's value to specify your flog output.
   128      1. With `evaluate-loki` as the current working directory, instantiate the new test environment:
   129          ```
   130          docker-compose up -d
   131          ```
   132  
   133  - To keep already-generated logs in the running test environment, restart flog with a new configuration.
   134  
   135      1. Edit the `docker-compose.yaml` file.  Within the YAML file, change the `flog.command` field's value to specify your flog output.
   136      1. With `evaluate-loki` as the current working directory, restart only the flog app within the currently-running test environment:
   137          ```
   138          docker-compose up -d --force-recreate flog
   139          ```
   140