xk6-prometheus

A k6 extension implements Prometheus HTTP exporter as k6 output extension.

Using xk6-prometheus output extension you can collect metrics from long running k6 process with Prometheus. All custom k6 metrics (Counter,Gauge,Rate,Trend) and build-in metrics will be accessible as appropiate Prometheus metrics on a given HTTP port in Prometheus importable text format.

Built for k6 using xk6.

Build

To build a k6 binary with this extension, first ensure you have the prerequisites:

Go toolchain
Git

Then:

Download xk6:

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

Build the binary:

$ xk6 build --with github.com/szkiba/xk6-prometheus@latest

You should use at least v0.31.0 version because xk6-prometheus extension registers itself as output extension. This feature introduced in the v0.31.0 version of k6.

Usage

With defaults

Without parameters the Prometheus HTTP exporter will accessible on port 5656.

$ ./k6 run -d 1m --out prometheus script.js

          /\      |‾‾| /‾‾/   /‾‾/   
     /\  /  \     |  |/  /   /  /    
    /  \/    \    |     (   /   ‾‾\  
   /          \   |  |\  \ |  (‾)  | 
  / __________ \  |__| \__\ \_____/ .io

  execution: local
     script: script.js
     output: prometheus (:5656)

  scenarios: (100.00%) 1 scenario, 1 max VUs, 1m30s max duration (incl. graceful stop):
           * default: 1 looping VUs for 1m0s (gracefulStop: 30s)


running (1m01.0s), 0/1 VUs, 54 complete and 0 interrupted iterations
default ✓ [======================================] 1 VUs  1m0s

     data_received..................: 611 kB 10 kB/s
     data_sent......................: 4.1 kB 67 B/s
     http_req_blocked...............: avg=3.37ms   min=2.86µs   med=3.82µs   max=181.96ms p(90)=11.15µs  p(95)=13.52µs 
     http_req_connecting............: avg=2.19ms   min=0s       med=0s       max=118.34ms p(90)=0s       p(95)=0s      
     http_req_duration..............: avg=125.14ms min=118.99ms med=120.68ms max=237.66ms p(90)=121.45ms p(95)=124.07ms
       { expected_response:true }...: avg=125.14ms min=118.99ms med=120.68ms max=237.66ms p(90)=121.45ms p(95)=124.07ms
     http_req_failed................: 0.00%  ✓ 0   ✗ 54 
     http_req_receiving.............: avg=5.1ms    min=85.32µs  med=792.2µs  max=118.29ms p(90)=860.41µs p(95)=903.71µs
     http_req_sending...............: avg=20.68µs  min=12.53µs  med=16.69µs  max=75.97µs  p(90)=29.39µs  p(95)=37.87µs 
     http_req_tls_handshaking.......: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s      
     http_req_waiting...............: avg=120.01ms min=118.17ms med=119.78ms max=127.48ms p(90)=120.6ms  p(95)=120.71ms
     http_reqs......................: 54     0.885451/s
     iteration_duration.............: avg=1.12s    min=1.11s    med=1.12s    max=1.3s     p(90)=1.12s    p(95)=1.16s   
     iterations.....................: 54     0.885451/s
     vus............................: 1      min=1 max=1
     vus_max........................: 1      min=1 max=1

Parameters

The output extension accept parameters in a standard query string format:

k6 run --out 'prometheus=param1=value1&param2=value2&param3=value3'

Note apostrophe (') characters around the --out parameter! You should use it for escape & characters from shell (or use backslash before & characters).

The following paremeters are recognized:

parameter	description
namespace	Prometheus namespace for exported metrics (default: "", empty)
subsystem	Prometheus subsystem for exported metrics (default: "", empty)
host	Hostname or IP address for HTTP endpoint (default: "", empty, listen on all interfaces)
port	TCP port for HTTP endoint (default: 5656)

It is recommended to use k6 as either namespace or subsystem to prefix exported metrics names with k6_ string.

Sample HTTP response

Here is the relevant part of the metrics HTTP response: