A k6 extension for pushing logs to Loki.

1. Install xk6

   go install go.k6.io/xk6/cmd/xk6@latest

2. Checkout grafana/xk6-loki

   git clone https://github.com/grafana/xk6-loki
   cd xk6-loki

3. Build the extension

   make k6

The k6/x/loki module contains the Loki extension to interact with the Loki API. To import the module add

import loki from 'k6/x/loki';

on top of your test file.

The class Config holds configuration for the Loki client. The constructor takes the following arguments:

Example:

import loki from 'k6/x/loki';
let conf = loki.Config("localhost:3100");

The class Labels allows the definition of custom labels that can be used instead of the built-in labels. An instance of this class can be passed as fifth argument to the loki.Config constructor.

Example:

import loki from 'k6/x/loki';
let labels = loki.Labels({
  "format": ["json", "logfmt"], // must contain at least one of the supported log formats
  "cluster": ["prod-us-east-0", "prod-eu-west-1"],
  "namespace": ["dev", "staging", "prod"],
  "container": ["nginx", "app-1", "app-2", "app-3"]
});

The class Client is a Loki client that can read from and write to a Loki instance. The constructor takes the following arguments:

Example:

import loki from 'k6/x/loki';
let conf = loki.Config("localhost:3100");
let client = loki.Client(conf);

This function is a shortcut for client.pushParameterized(5, 800*1024, 1024*1024).

Execute a push request (POST /loki/api/v1/push).

The function pushParameterized generates batch of logs and pushes it to the Loki instance. A batch consists of one or more streams which hold multiple log lines. A stream is a set of log lines with a unique set of labels.

minSize and maxSize define the boundaries for a random value of the actual batch size.

This function is a shortcut for client.instantQueryAt(query, limit, time.Now()) where time.Now() is the current nanosecond.

Execute an instant query (GET /loki/api/v1/query).

This function is a shortcut for client.rangeQueryAt(query, duration, limit, time.Now()) where time.Now() is the current nanosecond.

Execute a range query (GET /loki/api/v1/query_range).

duration defines the range for the query and uses the current timestamp as end and current timestamp - duration as start.

This function is a shortcut for client.labelsQueryAt(duration, time.Now()) where time.Now() is the current nanosecond.

Execute a labels query (GET /loki/api/v1/labels).

duration defines the range for the query and uses the current timestamp as end and current timestamp - duration as start.

This function is a shortcut for client.labelValuesQueryAt(label, duration, time.Now()) where time.Now() is the current nanosecond.

Execute a label values query (GET /loki/api/v1/label//values).

duration defines the range for the query and uses the current timestamp as end and current timestamp - duration as start.

This function is a shortcut for client.seriesQueryAt(matchers, duration, time.Now()) where time.Now() is the current nanosecond.

Execute a series query (GET /loki/api/v1/series).

duration defines the range for the query and uses the current timestamp as end and current timestamp - duration as start.

xk6-loki uses the following built-in label names for generating streams:

The total amount of different streams is defined by the carthesian product of all label values. Keep in mind that high cardinality impacts the performance of the Loki instance.

Additionally, xk6-loki also supports custom labels that can be used instead of the built-in labels.

See examples/custom-labels.js for a full example with custom labels.

The extension collects metrics that are printed in the end-of-test summary in addition to the built-in metrics.

These metrics are collected only for instant and range queries.

import sleep from 'k6';
import loki from 'k6/x/loki';

/**
 * URL used for push and query requests
 * Path is automatically appended by the client
 * @constant {string}
 */
const BASE_URL = `http://localhost:3100`;

/**
 * Client timeout for read and write in milliseconds
 * @constant {number}
 */
const timeout = 5000;

/**
 * Ratio between Protobuf and JSON encoded payloads when pushing logs to Loki
 * @constant {number}
 */
const ratio = 0.5;

/**
 * Cardinality for labels
 * @constant {object}
 */
const cardinality = {
  "app": 5,
  "namespace": 5
};

/**
 * Execution options
 */
export const options = {
  vus: 10,
  iterations: 10,
};

/**
 * Create configuration object
 */
const conf = new loki.Config(BASE_URL, timeout, ratio, cardinality);

/**
 * Create Loki client
 */
const client = new loki.Client(conf);

export default () => {
  // Push a batch of 2 streams with a payload size between 500KB and 1MB
  let res = client.pushParameterized(2, 512 * 1024, 1024 * 1024);
  // A successful push request returns HTTP status 204
  check(res, { 'successful write': (res) => res.status == 204 });
  sleep(1);
}

./k6 run examples/simple.js

You can find more examples in the examples/ folder.