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

     1  ---
     2  title: k6 load testing
     3  weight: 90
     4  ---
     5  
     6  # k6 Loki extension load testing
     7  
     8  Grafana [k6](https://k6.io) is a modern load-testing tool.
     9  Its clean and approachable scripting [API](https://k6.io/docs/javascript-api/)
    10  works locally or in the cloud.
    11  Its configuration makes it flexible.
    12  
    13  The [xk6-loki extension](https://github.com/grafana/xk6-loki) permits pushing logs to and querying logs from a Loki instance.
    14  It acts as a Loki client, simulating real-world load to test the scalability,
    15  reliability, and performance of your Loki installation.
    16  
    17  ## Before you begin
    18  
    19  k6 is written in Golang. [Download and install](https://go.dev/doc/install) a Go environment.
    20  
    21  ## Installation
    22  
    23  `xk6-loki` is an extension to the k6 binary.
    24  Build a custom k6 binary that includes the `xk6-loki` extension.
    25  
    26  1. Install the `xk6` extension bundler:
    27  
    28     ```bash
    29     go install go.k6.io/xk6/cmd/xk6@latest
    30     ```
    31  
    32  1. Check out the `grafana/xk6-loki` repository:
    33  
    34     ```bash
    35     git clone https://github.com/grafana/xk6-loki
    36     cd xk6-loki
    37     ```
    38  
    39  1. Build k6 with the extension:
    40  
    41     ```bash
    42     make k6
    43     ```
    44  
    45  ## Usage
    46  
    47  Use the custom-built k6 binary in the same way as a non-custom k6 binary:
    48  
    49  ```bash
    50  ./k6 run test.js
    51  ```
    52  
    53  `test.js` is a Javascript load test.
    54  Refer to the [k6 documentation](https://k6.io/docs/) to get started.
    55  
    56  ### Scripting API
    57  
    58  The custom-built k6 binary provides a Javascript `loki` module.
    59  
    60  Your Javascript load test imports the module: 
    61  
    62  ```js
    63  import loki from 'k6/x/loki';
    64  ```
    65  
    66  Classes of this module are:
    67  
    68  | class | description |
    69  | ----- | ----------- |
    70  | `Config` | configuration for the `Client` class |
    71  | `Client` | client for writing and reading logs from Loki |
    72  
    73  `Config` and `Client` must be called on the k6 init context (see
    74  [Test life cycle](https://k6.io/docs/using-k6/test-life-cycle/)) outside of the
    75  default function so the client is only configured once and shared between all
    76  VU iterations.
    77  
    78  The `Client` class exposes the following instance methods:
    79  
    80  | method | description |
    81  | ------ | ----------- |
    82  | `push()` | shortcut for `pushParameterized(5, 800*1024, 1024*1024)` |
    83  | `pushParameterized(streams, minSize, maxSize)` | execute push request ([POST /loki/api/v1/push]({{< relref "../../api/_index.md#post-lokiapiv1push" >}})) |
    84  | `instantQuery(query, limit)` | execute instant query  ([GET /loki/api/v1/query]({{< relref "../../api/_index.md#get-lokiapiv1query" >}})) |
    85  | `client.rangeQuery(query, duration, limit)` | execute range query  ([GET /loki/api/v1/query_range]({{< relref "../../api/_index.md#get-lokiapiv1query_range" >}})) |
    86  | `client.labelsQuery(duration)` | execute labels query  ([GET /loki/api/v1/labels]({{< relref "../../api/_index.md#get-lokiapiv1labels" >}})) |
    87  | `client.labelValuesQuery(label, duration)` | execute label values query  ([GET /loki/api/v1/label/\<name\>/values]({{< relref "../../api/_index.md#get-lokiapiv1labelnamevalues" >}})) |
    88  | `client.seriesQuery(matchers, duration)` | execute series query  ([GET /loki/api/v1/series]({{< relref "../../api/_index.md#series" >}})) |
    89  
    90  **Javascript load test example:**
    91  
    92  ```js
    93  import loki from 'k6/x/loki';
    94  
    95  const timeout = 5000; // ms
    96  const conf = loki.Config("http://localhost:3100", timeout);
    97  const client = loki.Client(conf);
    98  
    99  export default () => {
   100     client.pushParameterized(2, 512*1024, 1024*1024);
   101  };
   102  ```
   103  
   104  Refer to
   105  [grafana/xk6-loki](https://github.com/grafana/xk6-loki#javascript-api)
   106  for the complete `k6/x/loki` module API reference.