{"id":14971762,"url":"https://github.com/grafana/xk6-dns","last_synced_at":"2025-07-23T11:05:43.550Z","repository":{"id":244070229,"uuid":"798163253","full_name":"grafana/xk6-dns","owner":"grafana","description":"A k6 extension to resolve DNS names to IP addresses","archived":false,"fork":false,"pushed_at":"2025-05-21T13:18:27.000Z","size":129,"stargazers_count":6,"open_issues_count":5,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-19T11:44:05.255Z","etag":null,"topics":["dns","k6","xk6"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-09T08:09:58.000Z","updated_at":"2025-07-18T11:13:11.000Z","dependencies_parsed_at":"2024-06-12T19:50:42.029Z","dependency_job_id":"78903d6b-c082-4d8d-89ef-e75d8e7ad331","html_url":"https://github.com/grafana/xk6-dns","commit_stats":null,"previous_names":["grafana/xk6-dns"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/grafana/xk6-dns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-dns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-dns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-dns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-dns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grafana","download_url":"https://codeload.github.com/grafana/xk6-dns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grafana%2Fxk6-dns/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266665813,"owners_count":23964974,"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-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":["dns","k6","xk6"],"created_at":"2024-09-24T13:45:47.740Z","updated_at":"2025-07-23T11:05:43.528Z","avatar_url":"https://github.com/grafana.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xk6-dns\n\nThis is a DNS resolver extension for [k6](https://go.k6.io/k6). It allows you to resolve DNS names to IP addresses\nin your k6 scripts. \n\nThis extension was designed with the following goals in mind:\n- Assert the performance of custom DNS servers under load.\n- Provide a way to resolve DNS names to IP addresses using a specific DNS server in k6 scripts.\n\n## Features\n\nThis extension provides two functions:\n- [`dns.resolve()`](#dnsresolvequery-recordtype-options) - resolves a DNS name to an IP address using the provided DNS server.\n- [`dns.lookup()`](#dnslookuphost) - resolves a DNS name to an IP address using the system's default DNS server.\n\n## Usage\n\n### Installation\n\nTo use this extension requires using the xk6 tool to build a custom k6 binary that includes the extension. You can install the extension using the following command:\n\n```bash\nxk6 install github.com/grafana/xk6-dns@latest\n```\n\n### Example k6 script\n\nFrom there we can use the bustom built binary to run the following example script:\n\n```javascript\nimport dns from 'k6/x/dns';\n\nexport const options = {\n    vus: 10,\n    duration: 200,\n};\n\nexport default async function() {\n    // Request the IP address of k6.io from the selected namerserver A records.\n    const resolvedIP = await dns.resolve('k6.io', 'A', '192.168.2.100:53');\n    console.log(`k6.io IPs as resolved against the 192.168.2.100 nameserver: ${resolvedIP}`);\n    \n    // Lookup the IP address of k6.io using the system's default DNS server.\n    const lookupIP = await dns.lookup('k6.io');\n    console.log(`k6.io IP as looked up by the system's default DNS server: ${lookupIP}`);\n}\n```\n\n### Example results\n\n```\n          /\\      |‾‾| /‾‾/   /‾‾/\n     /\\  /  \\     |  |/  /   /  /\n    /  \\/    \\    |     (   /   ‾‾\\\n   /          \\   |  |\\  \\ |  (‾)  |\n  / __________ \\  |__| \\__\\ \\_____/ .io\n\n     execution: local\n        script: example.js\n        output: -\n\n     scenarios: (100.00%) 1 scenario, 10 max VUs, 10m30s max duration (incl. graceful stop):\n              * default: 200 iterations shared among 10 VUs (maxDuration: 10m0s, gracefulStop: 30s)\n\n\n     data_received.............: 0 B 0 B/s\n     data_sent.................: 0 B 0 B/s\n     dns_lookup_duration.......: avg=5.9ms  min=0s    med=3.5ms  max=44ms    p(90)=9.1ms   p(95)=11.69ms\n     dns_lookups...............: 20  84.316677/s\n     dns_resolution_duration...: avg=4.95ms min=2ms   med=3ms    max=31ms    p(90)=6.6ms   p(95)=12.94ms\n     dns_resolutions...........: 20  84.316677/s\n     iteration_duration........: avg=11.8ms min=2.1ms med=8.45ms max=76.46ms p(90)=17.21ms p(95)=23.16ms\n     iterations................: 200 843.166766/s\n\n\nrunning (00m00.2s), 00/10 VUs, 200 complete and 0 interrupted iterations\ndefault ✓ [======================================] 10 VUs  00m00.2s/10m0s  200/200 shared iters\n```\n\n## API\n\n### `dns.resolve(query, recordType, options)`\n\nResolves a DNS name to an IP address using the provided DNS server. It returns an array of IP addresses.\n\nThe `query` parameter is the DNS name to resolve, the `recordType` parameter is the type of DNS record to query for (e.g. 'A', 'AAAA', 'CNAME', 'NS', and 'PTR'), and the `options` parameter is an object that can contain the following properties:\n- `nameserver` - the IP address and port of the DNS server to query. It should be in the format `ip:port`. If not provided, the system's default DNS server will be used.\n\nUsing the `dns.resolve()` operation will emit the following metrics:\n- `dns_resolutions`: a [**Counter**](https://grafana.com/docs/k6/latest/using-k6/metrics/) metric tracking the number of DNS resolutions performed.\n- `dns_resolution_duration`: a [**Trend**](https://grafana.com/docs/k6/latest/using-k6/metrics/) metric tracking the time taken to resolve the DNS.\n\n### `dns.lookup(host)`\n\nLookups a host name using the system's default DNS server. It returns an array of IP addresses.\n\nThe `host` parameter is the DNS name to resolve.\n\nUsing the `dns.lookup()` operation will emit the following metrics:\n- `dns_lookups`: a [**Counter**](https://grafana.com/docs/k6/latest/using-k6/metrics/) metric tracking the number of DNS lookups performed.\n- `dns_lookup_duration`: A [**Trend**](https://grafana.com/docs/k6/latest/using-k6/metrics/) metric tracking the time taken to lookup the DNS.\n\n## Contributing\n\nContributions are welcome! If the module is missing a feature you need, or if you find a bug, please open an issue or a pull request. If you are not sure about something, feel free to open an issue and ask.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6-dns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrafana%2Fxk6-dns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrafana%2Fxk6-dns/lists"}