{"id":21187555,"url":"https://github.com/pb82/prometheus-toolbox","last_synced_at":"2025-07-10T02:31:04.820Z","repository":{"id":64411449,"uuid":"573819110","full_name":"pb82/prometheus-toolbox","owner":"pb82","description":"Tools for Prometheus","archived":false,"fork":false,"pushed_at":"2024-06-17T08:04:37.000Z","size":218,"stargazers_count":17,"open_issues_count":5,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-20T09:02:38.041Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pb82.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-03T14:32:59.000Z","updated_at":"2023-09-13T14:04:41.000Z","dependencies_parsed_at":"2024-01-28T21:31:25.895Z","dependency_job_id":"bc5207c9-8eda-4cd3-9f96-708f86df14d7","html_url":"https://github.com/pb82/prometheus-toolbox","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb82%2Fprometheus-toolbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb82%2Fprometheus-toolbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb82%2Fprometheus-toolbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pb82%2Fprometheus-toolbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pb82","download_url":"https://codeload.github.com/pb82/prometheus-toolbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225611706,"owners_count":17496511,"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":[],"created_at":"2024-11-20T18:37:36.365Z","updated_at":"2024-11-20T18:37:36.859Z","avatar_url":"https://github.com/pb82.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Prometheus Toolbox\n\nA CLI tool to generate metrics data for the [Prometheus](https://prometheus.io/) monitorig system.\nIt allows you to define time series and values and send them directly to Prometheus using the remote write protocol.\n\n## Why?\n\nI found this very useful for testing PromQL queries and alerts.\nSometimes you don't have the right data in Prometheus or simply no access. \nThis tool lets you simulate the data you need and test your queries against it.\n\n## Installation\n\nThe latest version:\n\n`GOPROXY=direct go install github.com/pb82/prometheus-toolbox@latest`\n\nA specific version:\n\n`GOPROXY=direct go install github.com/pb82/prometheus-toolbox@\u003cversion\u003e`\n\n*NOTE*: [Go](https://go.dev/) must be installed\n\n### Building locally\n\nBuild directly for your platform with go:\n\n```shell\n$ go build\n```\n\n## Starting a local development environment\n\nTo start a local development environment including Prometheus and Grafana use the built-in `--environment` command.\nThis prints out a shell script to spin up containers for both applications.\nIt also sets up a data source in Grafana to connect it to Prometheus.\nEither `podman` or `docker`, as well as `curl` are required.\n\nExample:\n\n```sh\n$ prometheus-toolbox --environment | bash\ndetected runtime is podman, starting containers. this can take some time...\nstarting prometheus container from image docker.io/prom/prometheus:latest\nstarting grafana container from image docker.io/grafana/grafana-oss:latest\ncreating prometheus datasource\nPrometheus is running on port 9090\nGrafana is running on port 3000\nGrafana credentials are admin/admin\npress ctrl-c to quit\n```\n\nThe Prometheus and Grafana images can be overridden by exporting the `PROMETHEUS_IMAGE` or `GRAFANA_IMAGE` variables:\n\n```shell\n$ export GRAFANA_IMAGE=docker.io/grafana/grafana-oss:8.5.15 \u0026\u0026 ./prometheus-toolbox --environment | bash\n```\n\n### Importing Prometheus rules into the local development environment\n\nThe environment script checks for the presence of a file with the name `rules.yml` in the directory it's running.\nIf present, Prometheus is configured to import [alerting](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/) and [recording](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/) rules from it.\n\nA sample rules file can be generated with the following command:\n\n```shell\n$ prometheus-toolbox --rules \u003e rules.yml\n```\n\n# Flags\n\nThe following flags are accepted:\n\n* `--help` Print help and exit\n* `--version` Print version and exit\n* `--prometheus.url` Prometheus base url\n* `--config.file` Config file location, defaults to `./config.yml`\n* `--batch.size` Samples per remote write request, defaults to 500\n* `--proxy.listen` Turns on the remote write listener, defaults to `false`\n* `--proxy.listen.port` Port to receive remote write requests, defaults to 3241\n* `--environment` Print environment setup script and exit\n* `--init` Print sample config file and exit\n* `--rules` Print sample alerting rules file and exit\n* `--oidc.enabled` Enable authenticated requests\n* `--oidc.issuer` OIDC auth token issuer URL\n* `--oidc.clientId` OIDC client id\n* `--oidc.clientSecret` OIDC client secret\n* `--oidc.audience` OIDC audience\n* `--prometheus.url.suffix` Allow alternate remote write endpoints, in case your receiver uses a different endpoint than the default `/api/v1/write`\n\n# Config file format\n\nThis tool reads from a config file where the simulated time series and values are defined.\nThe format is:\n\n```yaml\ninterval: \"10s\"                       # Interval between samples, in this case 10 seconds\ntime_series:                          # List of time series to simulate\n  - series: metric_a{label=\"a\"}       # Time series (metric name and label list)\n    values: 1+1x100                   # Precalculated samples\n  - series: metric_a{label=\"a\"}       # Another time series\n    stream: 1+0                       # Realtime samples\n  - series: metric_b{label=\"a\"}       # \n    values: 1+1x50 50+0x50            # Multiple value sequences are possible\n  - series: metric_c{l1=\"a\",l2=\"b\"}   # Multiple labels are possible\n    values: _x50 1+0x50               # The underscore represents an empty value (no data received). Time still advances.    \n```\n\nThe format for precalculated samples is:\n\n```\nvalues: 1+1x100 # \u003cinitial\u003e(plus or minus)\u003cincrement\u003ex\u003chow many samples\u003e\n```\n\nThe format for realtime samples is:\n\n```\nstream: 1+1 # \u003cinitial\u003e(plus or minus)\u003cincrement\u003e\n```\n\nStreaming realtime samples only ends when the user interrupts the program, thus no number of samples is needed.\n\nA basic config file can be created using the `--init` command:\n\n```shell\n$ prometheus-toolbox --init \u003e config.yml\n```\n\n# Features\n\n[Data generator](#data-generator): write precalculated samples.\n\n[Streaming samples](#streaming-samples): write realtime data.\n\n[Remote write inspector](#remote-write-inspector): inspect remote write requests.\n\n## Data generator\n\nGenerates data and sends it to a Prometheus instance using the [remote write](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) protocol.\n\n**NOTE:** remote write needs to be specifically enabled in Prometheus with the flag `--web.enable-remote-write-receiver`\n\nProvide the base URL of the Prometheus instance and a config file, for example:\n\n```shell\n$ cat config.yaml\n---\ninterval: 10s\ntime_series:\n  - series: metric_a{label=\"a\"}\n    values: 1+0x100 _x50\n  - series: metric_b{label=\"b\"}\n    values: 1+1x50 50+0x50 50-1x50\n```\n\n**NOTE:** if you're not familiar with the `series` and `values` notation, it is similar to how unit tests with `promtool` are written. For more information, have a look [here](https://prometheus.io/docs/prometheus/latest/configuration/unit_testing_rules/#series).\n\nRun the CLI with the following options:\n\n```shell\n$ ./prometheus-toolbox --prometheus.url=http://localhost:9090 --config.file=./config.yml\n```\n\nOpen the Prometheus UI and run a query like `{__name__~=\"metric_a|metric_b\"}`, or go to the graph view.\nSamples for both time series should be visible.\n\n### How the samples are generated\n\nSamples are always generated for the past. The time series that produces the most samples (in the above example it is `metrics_a`) determines how far back in time the samples go.\nIn the above case 100 samples are generated with an interval of ten seconds between them.\nSo both series will start at a point in time 1000 seconds in the past.\n\nSamples are batched to avoid sending one huge remote write request.\nThe default batch size is 500.\n\n## Streaming samples\n\nYou can stream continuous samples for series to a Prometheus instances:\n\n```shell\n$ cat example/config.yaml\n---\ninterval: 10s\ntime_series:\n  - series: up{label=\"a\"}\n    stream: 1+0\n```\n\nThis will send a sample generated from the field `stream` every ten seconds.\n\n**NOTE:** in contrast to `values`, when providing `stream` you can't specify the number of samples. Data is generated continuously.\n\n**NOTE:** you can have both, `values` and `stream` for the same series.\n\n## Remote write inspector\n\nThis tool can receive remote write requests and expose insights as metrics.\nTo enable the remote write listener, pass the `--proxy.listen` flag.\nBy default, remote write requests are received on port 3241, but this can be overridden using the `--proxy.listen.port` flag.\n\nWhen remote write requests are received, `prometheus-toolbox` will collect data and expose it as metrics.\nThe metrics can be viewed on the same port as the listener with a GET request.\n\nThe following data is collected:\n\n* Request count - how many write requests have been received\n* Compressed size - snappy compressed size of the write request in bytes\n* Uncompressed size - uncompressed size of the write request in bytes\n* Timeseries count - number of time series in write request\n* Http headers - present http headers\n\nFor example:\n\nConfigure prometheus to send write requests to `prometheus-toolbox`, by adding a `remote_write` section to `prometheus.yaml`: \n\n```yaml\nremote_write:\n  - name: \"self\"\n    url: \"http://localhost:3241\"\n```\n\n**NOTE:** This is assuming that both Prometheus and prometheus-toolbox are running locally.\n\nThen send a GET request to the `--proxy.listen` endpoint: \n\n```shell\n$ curl -XGET http://localhost:3241\n\n# HELP prometheus_toolbox_remote_write_compressed_size compressed remote write request size in bytes\n# TYPE prometheus_toolbox_remote_write_compressed_size gauge\nprometheus_toolbox_remote_write_compressed_size{origin=\"[::1]:58060\"} 112\n# HELP prometheus_toolbox_remote_write_header present http headers in remote write requests\n# TYPE prometheus_toolbox_remote_write_header gauge\nprometheus_toolbox_remote_write_header{header=\"Authorization\",origin=\"[::1]:58060\",value=\"Bearer 92MO6wrerqwoLWlJZfhunRIRGwl2QgsGl9rkJRI5Ts3mr1oYLBsjw92dREb2QRpfrGn5xvZFC4pwKdSupMTcBHZVRien6oXg8VSFCuAaquF9Wcagem6aHVyewDejqXFfg0m0pgTAf6hqbfNFFe5ysnygnaZfaGNHpKR5SC2VpscTKeHElEvhJUqSHxc6TO9RMzJBXjL2XPi0GMAshLMrP23clY9y9UtByF2cbobH3eYqrbRUocXog...\"} 1\nprometheus_toolbox_remote_write_header{header=\"Content-Encoding\",origin=\"[::1]:58060\",value=\"snappy\"} 1\nprometheus_toolbox_remote_write_header{header=\"Content-Type\",origin=\"[::1]:58060\",value=\"application/x-protobuf\"} 1\nprometheus_toolbox_remote_write_header{header=\"User-Agent\",origin=\"[::1]:58060\",value=\"Prometheus/2.39.1\"} 1\nprometheus_toolbox_remote_write_header{header=\"X-Prometheus-Remote-Write-Version\",origin=\"[::1]:58060\",value=\"0.1.0\"} 1\n# HELP prometheus_toolbox_remote_write_request_count number of received remote write requests\n# TYPE prometheus_toolbox_remote_write_request_count counter\nprometheus_toolbox_remote_write_request_count{origin=\"[::1]:58060\"} 3\n# HELP prometheus_toolbox_remote_write_timeseries_count number of time series in remote write request\n# TYPE prometheus_toolbox_remote_write_timeseries_count gauge\nprometheus_toolbox_remote_write_timeseries_count{origin=\"[::1]:58060\"} 2\n# HELP prometheus_toolbox_remote_write_uncompressed_size uncompressed remote write request size in bytes\n# TYPE prometheus_toolbox_remote_write_uncompressed_size gauge\nprometheus_toolbox_remote_write_uncompressed_size{origin=\"[::1]:58060\"} 143\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpb82%2Fprometheus-toolbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpb82%2Fprometheus-toolbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpb82%2Fprometheus-toolbox/lists"}