Skip to content

Latest commit

 

History

History
111 lines (76 loc) · 4.07 KB

README.md

File metadata and controls

111 lines (76 loc) · 4.07 KB
Raw

K6 OTLP Output Extension

This repository is for K6 output extension. The extension exports metrics of K6 tests using OTLP/HTTP protocol.

Usage

The released binary is expected to run in containers or linux-like hosts of amd64 architecture. For Windows 10+ environments you can run it in WSL2. For other environments, please build your version from sources.

Build K6 binary

You should have Go 1.22+ and make installed.

  • clone the repository using git;
  • run make build;
  • the k6 binary is in the project's ./bin subfolder.

Configuration

Configuration parameters can be set in a JSON configuration file or using environment variables:

Example of configuration file:

{
  "collectors": {
    "otlp": {
      "metrics_url": "http://localhost:8080/v1/metrics",
      "headers": {
        "job": "tests"
      },
      "push_interval": "1m",
      "timeout": "3s",
      "gzip": true,
      "insecure": true,
      "add_id_attributes": true
    }
  }
}

Environment variables:

Environment Variable Default Value Description
K6_OTLP_ADD_ID_ATTRS false If true, attributes provider_id and run_id added to metrics.
K6_OTLP_GZIP false true or false. Use GZIP encoding or not.
K6_OTLP_HTTP_HEADERS empty Optional HTTP headers
K6_OTLP_INSECURE true true or false. Validate SSL certificate or not.
K6_OTLP_PUSH_INTERVAL 5s Metric push interval in Go duration format for intermediate metrics. At the end on the test metrics exported regardless of this value.
K6_OTLP_TIMEOUT 5s HTTP request timeout in Go duration format
K6_OTLP_SERVER_URL http://localhost:8080/v1/metrics OTLP metrics endpoint url. Usually ends with /v1/metrics

Run K6 tests like

./k6 run --out otlp --config <config-file> <test-file>

K6 Metrics Conversion

The Grafana K6 testing utility uses a metric model that requires some metrics conversion before sending to Opentelemetry Collector or other OTLP receiver.

Rate

Each metric of type "rate" is converted to three OTLP metrics.

If <name> is a name of the original rate metric, it produces:

  • k6_<name>_total OTLP counter which contains the total number of occurrences;
  • k6_<name>_success_total OTLP counter which contains the total number of successful occurrences;
  • k6_<name>_success_rate OTLP Gauge, which contains the pre-computed rate over the whole metric family.

The latest pre-computed rate value should match appropriate K6 output.

Trend

Each metric of type "trend" is converted to one OTLP histogram and a gauge which label stat will define pre-computed statistics.

Example: original K6 trend metric: http_req_duration typically produces k6_http_req_duration_stat{stat="avg|min|max|p50|p90|p95"} metric family.

The latest pre-computed stat values should match appropriate K6 output.

Attributes

Sometimes it's required to distinguish metrics received from different test runs. For this scenario we have a configuration option that adds the following attributes/labels to the metrics:

Attribute Meaning
provider_id Initially, a random generated string. Expected to be the same for the same running location (host, user)
run_id A cyclic counter 0..255 indicates the test run. We should limit the range for avoiding high-cardinality.

To insert attributes, set environment variable K6_OTLP_ADD_ID_ATTRS=true or set add_id_attributes: true in the config file.

Using of meaningful provider_id

You can update your local file ~/.xk6-output-otlp/provider_id by changing the randomly generated id to something meaningful (your hostname or username, etc.). The new id should be unique and match pattern ^[0-9a-zA-Z_]{3,16}$.

Contributing

See CONTRIBUTING

Contact

See the factbook.