{"id":14371037,"url":"https://github.com/grafana/xk6-client-prometheus-remote","last_synced_at":"2025-10-19T10:31:11.541Z","repository":{"id":39794719,"uuid":"342031394","full_name":"grafana/xk6-client-prometheus-remote","owner":"grafana","description":"A k6 extension for testing Prometheus Remote Write endpoints","archived":false,"fork":false,"pushed_at":"2024-06-21T13:36:11.000Z","size":5232,"stargazers_count":25,"open_issues_count":6,"forks_count":12,"subscribers_count":141,"default_branch":"main","last_synced_at":"2025-02-04T10:09:57.478Z","etag":null,"topics":["prometheus","remote-write","xk6"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grafana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-24T20:48:04.000Z","updated_at":"2024-11-30T05:52:02.000Z","dependencies_parsed_at":"2024-06-22T06:07:36.853Z","dependency_job_id":null,"html_url":"https://github.com/grafana/xk6-client-prometheus-remote","commit_stats":null,"previous_names":["dgzlopes/xk6-remote-write"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-client-prometheus-remote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-client-prometheus-remote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-client-prometheus-remote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-client-prometheus-remote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana","download_url":"https://codeload.github.com/grafana/xk6-client-prometheus-remote/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237109914,"owners_count":19257229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["prometheus","remote-write","xk6"],"created_at":"2024-08-27T23:00:52.866Z","updated_at":"2025-10-19T10:31:11.156Z","avatar_url":"https://github.com/grafana.png","language":"Go","funding_links":[],"categories":["Extensions"],"sub_categories":["Official"],"readme":"# xk6-client-prometheus-remote\n\nThis extension adds Prometheus Remote Write testing capabilities to [k6](https://go.k6.io/k6). You can test any service that accepts data via Prometheus remote_write API such as [Cortex](https://github.com/cortexproject/cortex), [Thanos](https://github.com/improbable-eng/thanos), [Prometheus itself](https://prometheus.io/docs/prometheus/latest/feature_flags/#remote-write-receiver) and other services [listed here](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage).\n\nIt is implemented using the [xk6](https://k6.io/blog/extending-k6-with-xk6/) system.\n\n\u003e :warning: Not to be confused with [Prometheus remote write **output** extension](https://github.com/grafana/xk6-output-prometheus-remote) which is publishing test-run metrics to Prometheus.\n\n## Getting started  \n\nTo start using k6 with the extension you can:\n- Download and run the [binaries](https://github.com/grafana/xk6-client-prometheus-remote/releases) that we build on each release.\n- Pull and run the [Docker images](https://github.com/grafana/xk6-client-prometheus-remote/pkgs/container/xk6-client-prometheus-remote) that we build on each release.\n- Build your own binary from the source.\n\nIf you wanna go with the last option, first, ensure you have the prerequisites:\n\n- [Go toolchain](https://go101.org/article/go-toolchain.html)\n- Git\n\nThen:\n\n1. Install `xk6`:\n  ```shell\n  $ go install go.k6.io/xk6/cmd/xk6@latest\n  ```\n\n2. Build the binary:\n  ```shell\n  $ xk6 build --with github.com/grafana/xk6-client-prometheus-remote@latest\n  ```\n\n## Basic Example\n\n```javascript\nimport { check, sleep } from 'k6';\nimport remote from 'k6/x/remotewrite';\n\nexport let options = {\n    vus: 10,\n    duration: '10s',\n};\n\nconst client = new remote.Client({\n    url: \"\u003cyour-remote-write-url\u003e\"\n});\n\nexport default function () {\n    let res = client.store([{\n        \"labels\": [\n            { \"name\": \"__name__\", \"value\": `my_cool_metric_${__VU}` },\n            { \"name\": \"service\", \"value\": \"bar\" }\n        ],\n        \"samples\": [\n            { \"value\": Math.random() * 100, }\n        ]\n    }]);\n    check(res, {\n        'is status 200': (r) =\u003e r.status === 200,\n    });\n    sleep(1)\n}\n```\n\nResult output:\n\n```\n$ ./k6 run examples/basic.js\n\n          /\\      |‾‾| /‾‾/   /‾‾/   \n     /\\  /  \\     |  |/  /   /  /    \n    /  \\/    \\    |     (   /   ‾‾\\  \n   /          \\   |  |\\  \\ |  (‾)  | \n  / __________ \\  |__| \\__\\ \\_____/ .io\n\n  execution: local\n     script: examples/basic.js\n     output: -\n\n  scenarios: (100.00%) 1 scenario, 10 max VUs, 40s max duration (incl. graceful stop):\n           * default: 10 looping VUs for 10s (gracefulStop: 30s)\n\n\nrunning (10.4s), 00/10 VUs, 90 complete and 0 interrupted iterations\ndefault ✓ [======================================] 10 VUs  10s\n\n     ✓ is status 200\n\n     checks.....................: 100.00% ✓ 90       ✗ 0   \n     data_received..............: 46 kB   4.4 kB/s\n     data_sent..................: 24 kB   2.3 kB/s\n     http_req_blocked...........: avg=7.52ms   min=290ns    med=380ns    max=68.08ms  p(90)=67.2ms   p(95)=67.7ms  \n     http_req_connecting........: avg=1.88ms   min=0s       med=0s       max=18.27ms  p(90)=15.25ms  p(95)=17.11ms \n     http_req_duration..........: avg=136.88ms min=131.24ms med=135.66ms max=215.49ms p(90)=139.2ms  p(95)=140.72ms\n     http_req_receiving.........: avg=42.9µs   min=22µs     med=40.65µs  max=86.74µs  p(90)=57.7µs   p(95)=64.26µs \n     http_req_sending...........: avg=68.74µs  min=38.42µs  med=61.17µs  max=144.06µs p(90)=102.71µs p(95)=113.75µs\n     http_req_tls_handshaking...: avg=3.8ms    min=0s       med=0s       max=35.93ms  p(90)=32.92ms  p(95)=34.2ms  \n     http_req_waiting...........: avg=136.76ms min=131.07ms med=135.56ms max=215.35ms p(90)=139.09ms p(95)=140.63ms\n     http_reqs..................: 90      8.650581/s\n     iteration_duration.........: avg=1.14s    min=1.13s    med=1.13s    max=1.28s    p(90)=1.2s     p(95)=1.2s    \n     iterations.................: 90      8.650581/s\n     vus........................: 10      min=10     max=10\n     vus_max....................: 10      min=10     max=10\n```\nInspect examples folder for more details.\n\n## More advanced use case\n\nThe above example shows how you can generate samples in JS and pass them into the extension, the extension will then submit them to the remote_write API endpoint.\nWhen you want to produce samples at a very high rate the overhead which is involved when passing objects from the JS runtime to the extension can get expensive though,\nto optimize this the extension also offers the option for the user to pass it a template based on which samples should be generated and then sent,\nby generating the samples inside the extension the overhead of passing objects from the JS runtime to the extension can be avoided.\n\n```javascript\nconst template = {\n    __name__: 'k6_generated_metric_${series_id/4}',    // Name of the series.\n    series_id: '${series_id}',                         // Each value of this label will match 1 series.\n    cardinality_1e1: '${series_id/10}',                // Each value of this label will match 10 series.\n    cardinality_2: '${series_id%2}',                   // Each value of this label will match 2 series.\n};\n\nwrite_client.storeFromTemplates(\n    100,                // minimum random value\n    200,                // maximum random value\n    1643235433 * 1000,  // timestamp in ms\n    42,                 // series id range start\n    45,                 // series id range end\n    template,\n);\n```\n\nThe above code could generate and send the following 3 samples, values are randomly chosen from the defined range:\n\n```\nMetric:    k6_generated_metric_10{cardinality_1e1=\"4\", cardinality_2=\"0\", series_id=\"42\"},\nTimestamp: 16432354331000\nValue:     193\n---\nMetric:    k6_generated_metric_10{cardinality_1e1=\"4\", cardinality_2=\"1\", series_id=\"43\"},\nTimestamp: 16432354331000\nValue:     121\n---\nMetric:    k6_generated_metric_11{cardinality_1e1=\"4\", cardinality_2=\"0\", series_id=\"44\"},\nTimestamp: 16432354331000\nValue:     142\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6-client-prometheus-remote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana%2Fxk6-client-prometheus-remote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6-client-prometheus-remote/lists"}