You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Mar 18, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+33-13Lines changed: 33 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,14 @@
1
1
# xk6-output-prometheus-remote
2
+
2
3
[k6](https://github.com/grafana/k6) extension for publishing test-run metrics to Prometheus via Remote Write endpoint.
3
4
4
5
> :warning: Not to be confused with [Prometheus Remote Write **client** extension](https://github.com/grafana/xk6-client-prometheus-remote) which is for load testing _Prometheus_ itself.
5
6
6
-
> :bookmark: As of k6 v0.42.0, this extension is available within k6 as an _experimental module_.
7
+
> :bookmark: As of k6 v0.42.0, this extension is available within k6 as an _experimental module_.
7
8
> This means that the extension has entered the process of being fully merged into the core of k6 and does not require a special build with xk6 to utilize this feature.
8
-
>
9
+
>
9
10
> See the [Prometheus remote write guide](https://k6.io/docs/results-output/real-time/prometheus-remote-write/) to utilize this feature.
10
-
>
11
+
>
11
12
12
13
There are many options for remote-write compatible agents, the official list can be found [here](https://prometheus.io/docs/operating/integrations/). The exact details of how metrics will be processed or stored depends on the underlying agent used.
13
14
@@ -20,16 +21,19 @@ Key points to know:
20
21
### Usage
21
22
22
23
To build k6 binary with the Prometheus remote write output extension use:
@@ -51,17 +55,17 @@ All the k6 metric types are converted into an equivalent Prometheus' type:
51
55
52
56
The obvious conversion with a classic Prometheus Histogram is not convenient because k6 can't determine the fixed buckets in advance, so the Output maps a Trend metric by default into a Gauge representing p(99). It is possible to map the same Trend to multiple stats at the same time (count, sum, min, max, avg, med, p(x)), it is possible to specify them via the `K6_PROMETHEUS_RW_TREND_STATS` environment variable (e.g `K6_PROMETHEUS_RW_TREND_STATS=avg,p(90),p(99),min,max`). Note that for each added stat a new time series will be generated.
53
57
Mapping Trend by stats has the following cons:
54
-
* It is impossible to aggregate some Gauge's value (especially the percentiles).
55
-
* It uses a memory-expensive k6's data structure.
58
+
59
+
- It is impossible to aggregate some Gauge's value (especially the percentiles).
60
+
- It uses a memory-expensive k6's data structure.
56
61
57
62
The previous points can be resolved by mapping Trend as [Prometheus Native Histogram](https://prometheus.io/docs/concepts/metric_types/#histogram). Enabling the conversion by the `K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM=true` environment variable (or one of the other ways), then the Output converts all the Trend types into a dedicated Native Histogram.
58
63
59
64
Native Histogram is a Prometheus' experimental feature, so it has to be enabled (`--enable-feature=native-histograms`). Note that other Remote-write implementations don't support it yet.
60
65
61
66
### Prometheus as remote-write agent
62
67
63
-
To enable remote write in Prometheus 2.x use `--enable-feature=remote-write-receiver` option. See docker-compose samples in `example/`. Options for remote write storage can be found [here](https://prometheus.io/docs/operating/integrations/).
64
-
68
+
To enable remote write in Prometheus 2.x use `--enable-feature=remote-write-receiver` option. See docker-compose samples in `example/`. Options for remote write storage can be found [here](https://prometheus.io/docs/operating/integrations/).
65
69
66
70
### Docker Compose
67
71
@@ -71,13 +75,14 @@ Note: the `docker-compose.yml` file has the Native Histogram mapping set as enab
71
75
72
76
> This is just a quick setup to show the usage. For a real use case, you will want to deploy outside of docker.
73
77
74
-
Clone the repo to get started and follow these steps:
78
+
Clone the repo to get started and follow these steps:
75
79
76
80
1. Start the docker compose environment.
81
+
77
82
```shell
78
83
docker-compose up -d
79
84
```
80
-
85
+
81
86
> Some users have encountered failures forthe k6 build portion. A workaround may be to disable the _"Use Docker Compose V2"_ checkboxin the _General_ section of Docker Desktop settings.
82
87
83
88
```shell
@@ -88,23 +93,38 @@ Clone the repo to get started and follow these steps:
88
93
```
89
94
90
95
2. Use the k6 Docker image to run the k6 script and send metrics to the Prometheus container started on the previous step. You must [set the `testid` tag](https://k6.io/docs/using-k6/tags-and-groups/#test-wide-tags) with a unique identifier to segment the metrics into discrete test runs for the Grafana dashboards.
96
+
91
97
```shell
92
98
docker-compose run --rm -T k6 run -<samples/test.js --tag testid=<SOME-ID>
93
99
```
100
+
94
101
For convenience, the `docker-run.sh` can be used to simply:
102
+
95
103
```shell
96
104
./docker-run.sh samples/test.js
97
105
```
98
106
99
-
3. Visit http://localhost:3000/ to view results in Grafana.
107
+
3. Visit <http://localhost:3000/> to view results in Grafana.
100
108
101
109
## Dashboards
110
+
102
111
The docker-compose setup comes with two pre-built Grafana dashboards. One for listing the discrete test runs as a list, and the other for visualizing the results of a specific test run.
103
112
>Note: The dashboards work with the Native Histogram mapping so it is required to enable it.
104
113
105
114
### Test result dashboard
106
-
107
115
108
-
### Test list dashboard
109
-
Add custom dashboards here, then start the [docker-compose](../../docker-compose.yml) to have the dashboards provisioned at startup. Use folders to group related dashboards.
4
+
5
+
6
+
7
+
## Dashboards
8
+
9
+
The docker-compose setup comes with two pre-built Grafana dashboards. One for listing the discrete test runs as a list, and the other for visualizing the results of a specific test run.
10
+
>Note: The dashboards work with the Native Histogram mapping so it is required to enable it.
The Apdex score is calculated based on your SLA ```([T]target time (seconds) Apdex
55
+
variable, default 0.3 sec)``` required where you can define a response time threshold of T seconds, where all responses handled in T seconds or less satisfy the end user.
0 commit comments