Repository files navigation

A k6 extension for pushing logs to Loki.

1. Installxk6

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

2. Checkoutgrafana/xk6-loki

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

3. Build the extension

   make k6

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

importlokifrom'k6/x/loki';

on top of your test file.

The classConfig holds configuration for the Loki client. The constructortakes the following arguments:

Example:

importlokifrom'k6/x/loki';letconf=loki.Config("localhost:3100");

The classLabels allows the definition of custom labels that can be usedinstead of the built-in labels. An instance of this class can be passed asfifth argument to theloki.Config constructor.

Example:

importlokifrom'k6/x/loki';letlabels=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 classClient is a Loki client that can read from and write to a Loki instance.The constructor takes the following arguments:

Example:

importlokifrom'k6/x/loki';letconf=loki.Config("localhost:3100");letclient=loki.Client(conf);

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

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

The functionpushParameterized 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 andmaxSize define the boundaries for a random value of the actual batch size.

This function is a shortcut forclient.instantQueryAt(query, limit, time.Now()) wheretime.Now() is the current nanosecond.

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

This function is a shortcut forclient.rangeQueryAt(query, duration, limit, time.Now()) wheretime.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 forclient.labelsQueryAt(duration, time.Now()) wheretime.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 forclient.labelValuesQueryAt(label, duration, time.Now()) wheretime.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 forclient.seriesQueryAt(matchers, duration, time.Now()) wheretime.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 insteadof the built-in labels.

Seeexamples/custom-labels.js for a full example with custom labels.

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

These metrics are collected only for instant and range queries.

importsleepfrom'k6';importlokifrom'k6/x/loki';/** * URL used for push and query requests * Path is automatically appended by the client *@constant {string} */constBASE_URL=`http://localhost:3100`;/** * Client timeout for read and write in milliseconds *@constant {number} */consttimeout=5000;/** * Ratio between Protobuf and JSON encoded payloads when pushing logs to Loki *@constant {number} */constratio=0.5;/** * Cardinality for labels *@constant {object} */constcardinality={"app":5,"namespace":5};/** * Execution options */exportconstoptions={vus:10,iterations:10,};/** * Create configuration object */constconf=newloki.Config(BASE_URL,timeout,ratio,cardinality);/** * Create Loki client */constclient=newloki.Client(conf);exportdefault()=>{// Push a batch of 2 streams with a payload size between 500KB and 1MBletres=client.pushParameterized(2,512*1024,1024*1024);// A successful push request returns HTTP status 204check(res,{'successful write':(res)=>res.status==204});sleep(1);}

./k6 run examples/simple.js

You can find more examples in theexamples/ folder.