{"id":26579843,"url":"https://github.com/mondaycom/ns1-prometheus-exporter","last_synced_at":"2025-09-18T16:34:08.673Z","repository":{"id":41868570,"uuid":"381928265","full_name":"mondaycom/ns1-prometheus-exporter","owner":"mondaycom","description":"A simple, unofficial gateway application for exposing NS1 queries/min metrics using the OpenMetrics format","archived":false,"fork":false,"pushed_at":"2023-03-20T23:09:17.000Z","size":41,"stargazers_count":17,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-16T23:49:13.790Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mondaycom.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-01T06:09:24.000Z","updated_at":"2023-11-19T20:32:50.000Z","dependencies_parsed_at":"2025-03-23T06:29:18.668Z","dependency_job_id":"9b7440ab-d0c2-40d3-b4c9-faaf316618b2","html_url":"https://github.com/mondaycom/ns1-prometheus-exporter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mondaycom/ns1-prometheus-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondaycom%2Fns1-prometheus-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondaycom%2Fns1-prometheus-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondaycom%2Fns1-prometheus-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondaycom%2Fns1-prometheus-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mondaycom","download_url":"https://codeload.github.com/mondaycom/ns1-prometheus-exporter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mondaycom%2Fns1-prometheus-exporter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275797329,"owners_count":25530253,"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","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-03-23T06:29:13.716Z","updated_at":"2025-09-18T16:34:08.618Z","avatar_url":"https://github.com/mondaycom.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ns1-prometheus-exporter\n\n![Docker Image Version (latest by date)](https://img.shields.io/docker/v/mondaycom/ns1-prometheus-exporter)\n\nA simple, unofficial gateway application for exposing NS1 queries/min metrics using the OpenMetrics format\n\n## How it works\nThis project is a HTTP proxy application that listens on the `/metrics` HTTP endpoint, performs calls to the NS1 API and returns the results in a format that's ready to be scraped by Prometheus.\n\nResults that are fetched from the API are cached for 1 minute to prevent excessive external calls. Results can be retrieved and displayed either on a record-level, i.e.\n```\nns1_record_queries_per_minute{zone=\"example.com\",domain=\"www.example.com\",type=\"CNAME\"} 450 1625082420000\nns1_record_queries_per_minute{zone=\"example.com\",domain=\"mx.example.com\",type=\"MX\"} 150 1625082420000\n```\nor, if you just need zone-level monitoring, can return the cumulative queries/min value for the whole zone:\n```\nns1_record_queries_per_minute{zone=\"example.com\"} 600 1625082420000\n```\n\n## Quick start\nTo run the exporter **locally**:\n```bash\nnpm install\nNS1_API_KEY=8H9sX... node index.js\n```\n\nTo run the exporter using **Docker**:\n```bash\ndocker run -d -p 3000:3000 -e NS1_API_KEY=8H9sX... mondaycom/ns1-prometheus-exporter\n```\n\nTo run the exporter as a **Kubernetes** deployment, including a `ServiceMonitor` object to instruct Prometheus to scrape the metrics endpoint, see the `example/` directory for YAML files.\n\n## Environment variables\nThe exporter can be configured using the following environment variables:\n\n| Variable | Description | Default |\n|--|--|--|\n| `NS1_API_KEY` | The API key to NS1 to use for data fetching | - (required) |\n| `EXPORTER_GRANULARITY` | Whether to scrape `zone`-level data or `record`-level data | `record` |\n| `MONITOR_ZONES` | A comma-separated list of zones to monitor (e.g. `foo.com,bar.com`). Leaving this unset will monitor all zones automatically | - |\n| `SERVER_PORT` | The port the server will listen on | `3000` |\n| `CLIENT_TIMEOUT` | The time, in milliseconds, for the HTTP client to wait for a response from NS1 | `3000` |\n| `CLIENT_BATCH_SIZE` | The maximum number of parallel requests to send to the NS1 API | `10` |\n\n## Notes\n\n### Exporter times and Prometheus timeouts\nWhen calling the `/metrics` endpoint, the exporter fetches near-real-time data from the NS1 API, if such data was not fetched in the last minute (and can be returned from cache).\n\nDepending on the amount of zones/records you monitor, the response from the endpoint may take several seconds to return. If you're running in Kubernetes and using a `ServiceMonitor` object,\nyou can adjust the `scrapeTimeout` property according to your needs:\n```yaml\nspec:\n  endpoints:\n    - interval: 30s\n      path: /metrics\n      scrapeTimeout: 15s\n      ...\n```\n\n### NS1's API and rate limiting notes\nNS1 has a rate limiting policy on their API which is specified [here](https://help.ns1.com/hc/en-us/articles/360020250573-About-API-rate-limiting).\n\nTo ensure you get the monitoring data you need, while minimizing API calls to NS1's backend, consider the following configurations while setting up the exporter:\n- `MONITOR_ZONES` - if you have a lot of zones with many records, you might want to specify a subset of these zones to be monitored. This will eliminate API calls to zones you don't need to monitor\n- `EXPORTER_GRANULARITY` - if you maintain large zones with hundreds/thousands of DNS records, consider setting this to `zone`. Zone-level monitoring requires a single API call, while record-level monitoring requires querying every one of your records individually to obtain the QPS metric data\n\n### Value accuracy and the meaning of queries/min\nNS1 expose DNS query throughput in units of QPS (queries/sec), which are defined by them as so:\n\u003e ...Once per minute on the minute, a new QPS value is calculated using the query count in a two minute period ending five minutes ago. This query count is divided by 120 seconds to return an average QPS for that time period\n\nThe exporter returns a queries/min by multiplying the returned value by 60, along a timestamp of 5 minutes ago, rounded down to the start of that minute.\n\nGiven these differences, you may see small differences between NS1 data presented on their website and data presented by the exporter over time. Still, the values are close enough to be used for monitoring over long periods of time and for active domains.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmondaycom%2Fns1-prometheus-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmondaycom%2Fns1-prometheus-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmondaycom%2Fns1-prometheus-exporter/lists"}