{"id":18230445,"url":"https://github.com/benc-uk/postman-prometheus","last_synced_at":"2025-04-03T15:30:26.184Z","repository":{"id":41814960,"uuid":"349478719","full_name":"benc-uk/postman-prometheus","owner":"benc-uk","description":"Run Postman collections continuously and export results as Prometheus metrics","archived":false,"fork":false,"pushed_at":"2025-02-23T09:58:07.000Z","size":152,"stargazers_count":30,"open_issues_count":2,"forks_count":21,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-19T05:43:04.528Z","etag":null,"topics":["api-testing","monitoring","postman","prometheus"],"latest_commit_sha":null,"homepage":"https://code.benco.io/postman-prometheus/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benc-uk.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-19T15:58:39.000Z","updated_at":"2025-03-17T17:21:07.000Z","dependencies_parsed_at":"2023-01-18T10:59:53.306Z","dependency_job_id":null,"html_url":"https://github.com/benc-uk/postman-prometheus","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/benc-uk%2Fpostman-prometheus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benc-uk%2Fpostman-prometheus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benc-uk%2Fpostman-prometheus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benc-uk%2Fpostman-prometheus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benc-uk","download_url":"https://codeload.github.com/benc-uk/postman-prometheus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247027633,"owners_count":20871566,"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":["api-testing","monitoring","postman","prometheus"],"created_at":"2024-11-04T11:04:13.309Z","updated_at":"2025-04-03T15:30:26.127Z","avatar_url":"https://github.com/benc-uk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Postman Monitor with Prometheus\n\nThis project provides a small Node.js based server which will run a Postman collection continuously on regular interval. It uses the Newman library that Postman provides, and exposes various HTTP and request metrics and stats in Prometheus exposition format so they can be scraped by Prometheus. This allows you to proactively monitor any Postman collection you wish, from wherever you wish.\n\nYou can use this to monitor the health and performance of web sites and REST APIs, and by using test assertions (see below) you can validate the contents returned, status codes, headers etc. Even chain requests together extracting variables from one request to use with another.\n\nBy default the server listens on port 8080 and provides metrics at the standard `/metrics` endpoint (this is configurable). The collection you want to run can be fetched by the runner at startup from a URL you supply, or you can build the runner container with the collection file copied into the image.\n\nConfiguration can be fetched from local files (typically bundled inside the container) or from remote URL sources. This configuration is a Postman collection file (as a JSON export) and **optionally** a Postman environment file (also in JSON)\n\nThe server is containerised and published publicly as a container image at `ghcr.io/benc-uk/postman-prometheus`\n\nKubernetes manifests for deployment are also provided.\n\nGoals:\n\n- Turn Postman into a continuous monitoring tool\n- Export Postman/Newman data into Prometheus\n\nUse cases \u0026 key features:\n\n- Monitoring of APIs and websites\n- Host your own monitoring with Kubernetes or anywhere you need\n- Go beyond simple single HTTP checks, using Postman's [collection feature](https://learning.postman.com/docs/running-collections/intro-to-collection-runs/) and [test assertions](https://learning.postman.com/docs/writing-scripts/script-references/test-examples/) for checking and chaining\n- Validate HTML or API responses, payloads and even build end to end journeys\n\n![](https://img.shields.io/github/license/benc-uk/postman-prometheus)\n![](https://img.shields.io/github/last-commit/benc-uk/postman-prometheus)\n![](https://img.shields.io/github/release/benc-uk/postman-prometheus)\n![](https://img.shields.io/github/checks-status/benc-uk/postman-prometheus/main)\n\n# 🖼️ Example\n\nThis is a screenshot of the provided Grafana dashboard\n\nThe dashboard can be found in the [grafana directory](https://github.com/benc-uk/postman-prometheus/tree/main/grafana) as a JSON file which you can import.\n\n![screen shot of dashboard](https://user-images.githubusercontent.com/14982936/111913204-fd8a6400-8a64-11eb-95c1-a40f4828d05f.png)\n\n# ⚙️ Configuration\n\n| Environmental Variable | Purpose                                                          | Default           |\n| ---------------------- | ---------------------------------------------------------------- | ----------------- |\n| PORT                   | Port the server listens on                                       | 8080              |\n| COLLECTION_FILE        | Path to Postman collection file to load and use                  | ./collection.json |\n| COLLECTION_URL         | Load from Postman collection from URL, overrides COLLECTION_FILE | _none_            |\n| REFRESH_INTERVAL       | How frequently fetch and refresh remote collection/env files     | 300               |\n| RUN_INTERVAL           | How frequently to run the collection, in seconds                 | 30                |\n| RUN_ITERATIONS         | How many iterations of the collection to run                     | 1                 |\n| ENABLE_BAIL            | Stops the run when a test case or request fails                  | false             |\n| ENABLE_REQUEST_METRICS | Disable the per-request metrics if you wish                      | true              |\n| ENVIRONMENT_FILE       | Path to a Postman environment file                               | _none_            |\n| ENVIRONMENT_URL        | Load a Postman environment from URL, overrides ENVIRONMENT_FILE  | _none_            |\n| GLOBAL_FILE            | Path to a Postman globals file                                   | _none_            |\n| GLOBAL_URL             | Load Postman globals from URL, overrides GLOBAL_FILE             | _none_            |\n| POSTMAN\\_{varname}     | Environment vars to pass to running the collection               | _none_            |\n| METRICS_URL_PATH       | URL path to serve the metrics from, must start with slash        | /metrics          |\n| STATUS_ENABLED         | Enable/disable the status endpoint.                              | true              |\n\n\u003e NOTE: When both `COLLECTION_URL` and `COLLECTION_FILE` are set, then `COLLECTION_URL` will take precedence. Likewise for `ENVIRONMENT_FILE` and `ENVIRONMENT_URL` and also `GLOBAL_FILE` and `GLOBAL_URL`. Meaning these configuration settings are effectively mutually exclusive\n\n## Note on Postman variables\n\nPostman/Newman can [accept variables a number of ways](https://learning.postman.com/docs/sending-requests/variables/) with this runner you supply values for any variables your scripts reference in two ways:\n\n- Environments file, this is a JSON file created by defining an environment in Postman and [exporting as JSON](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#exporting-environments)\n- Using special `POSTMAN_{varname}` environment vars, set as regular OS environment vars (therefor settable at runtime from Docker and Kubernetes). The prefix `POSTMAN_` is required and stripped off, leaving the name of the variable to set when running the collection, e.g. if your Postman request referenced a variable `{{myvar}}` you can set it using `POSTMAN_myvar=foo`\n\n# 📃 Repo Contents\n\n📁 `src` - Source of the Node.js runner which wraps Newman  \n📁 `samples` - Example Postman collections for monitoring  \n📁 `grafana` - Example Grafana dashboard which can be imported  \n📁 `deploy` - Deployment to Kubernetes, plus Helm samples for alerting  \n📁 `build` - Dockerfile mostly  \n📁 `scripts` - Some bash scripts\n\n# 🔨 Using\n\nJust about everything you need to do with this project has been put into make\n\n```txt\n$ make\n\nhelp                 💬 This help message\nrun                  🥈 Run locally (requires Node.js) ‍\nimage                🔨 Build container image from Dockerfile\nlint-fix             📜 Lint \u0026 format, will try to fix errors and modify code\nlint                 🔎 Lint \u0026 format, will not fix but sets exit code on error\npush                 📤 Push container image to registry\nclean                🧹 Clean up local repo\ndeploy               🚀 Deploy to Kubernetes\nundeploy             💀 Remove from Kubernetes\n```\n\nThe `deploy` target provides a lightweight \"Helm-less\" way to deploy to Kubernetes, using envsubst, makefile variables and deploy/deployment.yaml as a template.\nBefore running `make deploy` check the `DEPLOY_` variables in the makefile, then either edit or override these\n\n# 🌐 Other Endpoints\n\nAs well as exposing metrics for scraping, the server also exposes a small status API at `/status`, which will show details of the configuration, the loaded collection and some runtime statistics in JSON form. In addition the endpoint `/health` will return an HTTP 200\n\n# 📊 Exported Metrics\n\nBelow is a dump of all the metrics the server will export.\n\n\u003e **💬 Note**. There could be MANY per-request metrics, if running a collection with a large number of requests and a large number of iterations. You have been warned!\n\n```txt\n# ==========================================================\n# Lifetime metrics for the whole life of the monitor server\n# ==========================================================\n\n# TYPE postman_lifetime_runs_total counter\npostman_lifetime_runs_total{collection=\"Example\"} 69\n\n# TYPE postman_lifetime_iterations_total counter\npostman_lifetime_iterations_total{collection=\"Example\"} 138\n\n# TYPE postman_lifetime_requests_total counter\npostman_lifetime_requests_total{collection=\"Example\"} 276\n\n# ==========================================================\n# Metrics aggregated for the whole collection\n# ==========================================================\n\n# TYPE postman_stats_iterations_total gauge\npostman_stats_iterations_total{collection=\"Example\"} 2\n\n# TYPE postman_stats_iterations_failed gauge\npostman_stats_iterations_failed{collection=\"Example\"} 0\n\n# TYPE postman_stats_requests_total gauge\npostman_stats_requests_total{collection=\"Example\"} 4\n\n# TYPE postman_stats_requests_failed gauge\npostman_stats_requests_failed{collection=\"Example\"} 0\n\n# TYPE postman_stats_tests_total gauge\npostman_stats_tests_total{collection=\"Example\"} 4\n\n# TYPE postman_stats_tests_failed gauge\npostman_stats_tests_failed{collection=\"Example\"} 0\n\n# TYPE postman_stats_test_scripts_total gauge\npostman_stats_test_scripts_total{collection=\"Example\"} 4\n\n# TYPE postman_stats_test_scripts_failed gauge\npostman_stats_test_scripts_failed{collection=\"Example\"} 0\n\n# TYPE postman_stats_assertions_total gauge\npostman_stats_assertions_total{collection=\"Example\"} 8\n\n# TYPE postman_stats_assertions_failed gauge\npostman_stats_assertions_failed{collection=\"Example\"} 2\n\n# TYPE postman_stats_transfered_bytes_total gauge\npostman_stats_transfered_bytes_total{collection=\"Example\"} 43750\n\n# TYPE postman_stats_resp_avg gauge\npostman_stats_resp_avg{collection=\"Example\"} 40.25\n\n# TYPE postman_stats_resp_min gauge\npostman_stats_resp_min{collection=\"Example\"} 17\n\n# TYPE postman_stats_resp_max gauge\npostman_stats_resp_max{collection=\"Example\"} 107\n\n# ==========================================================\n# These metrics are per request AND per iteration\n# ==========================================================\n\n# TYPE postman_request_status_code gauge\npostman_request_status_code{request_name=\"Some Example Request\",iteration=\"0\",collection=\"Example\"} 200\n\n# TYPE postman_request_resp_time gauge\npostman_request_resp_time{request_name=\"Some Example Request\",iteration=\"0\",collection=\"Example\"} 19\n\n# TYPE postman_request_resp_size gauge\npostman_request_resp_size{request_name=\"Some Example Request\",iteration=\"0\",collection=\"Example\"} 8684\n\n# TYPE postman_request_status_ok gauge\npostman_request_status_ok{request_name=\"Some Example Request\",iteration=\"0\",collection=\"Example\"} 1\n\n# TYPE postman_request_failed_assertions gauge\npostman_request_failed_assertions{request_name=\"Some Example Request\",iteration=\"0\",collection=\"Example\"} 0\n\n# TYPE postman_request_total_assertions gauge\npostman_request_total_assertions{request_name=\"Some Example Request\",iteration=\"0\",collection=\"Example\"} 3\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenc-uk%2Fpostman-prometheus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenc-uk%2Fpostman-prometheus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenc-uk%2Fpostman-prometheus/lists"}