docs: add comprehensive k6/x/dns extension documentation #2073
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
oleiade
force-pushed
the
document-k6-x-dns
branch
from
81b9c46 to
228a414
Compare
|
💻 Deploy preview available (docs: add comprehensive k6/x/dns extension documentation): |
oleiade
force-pushed
the
document-k6-x-dns
branch
from
228a414 to
8083bb5
Compare
- Add complete documentation for k6/x/dns module with _index.md overview - Create resolve.md documenting dns.resolve() function with parameters, examples, and error handling - Create lookup.md documenting dns.lookup() function for system DNS resolution - Include installation instructions, API reference, and metrics documentation - Add comprehensive examples for IPv4/IPv6 resolution, performance testing, and validation - Use IPv6 DNS server (2606:4700:4700::1111) in IPv6 examples for consistency - Replace check() usage with k6-jslib-testing expect() assertions throughout examples - Follow k6 documentation conventions matching existing API documentation structure
oleiade
force-pushed
the
document-k6-x-dns
branch
from
8083bb5 to
a096157
Compare
There was a problem hiding this comment.
Thanks for creating these docs @oleiade 🙇 .
A lot of my comments are just removing the code shortcode, we only need them for tabbed code samples.
You can also replace some of the <!-- md-k6:skip --> statements and just add a <!-- md-k6:skipall --> at the top of the page. I'm happy to make that change if you want to, just let me know. 🙇
| @@ -0,0 +1,30 @@ | |||
| # Repository Guidelines | |||
There was a problem hiding this comment.
This is really helpful @oleiade! I just added the AGENTS.md file with the instructions we have for general technical writing guidance in a previous PR, but maybe we can merge them together?
| weight: 11 | ||
| --- | ||
|
|
||
| # DNS |
There was a problem hiding this comment.
Suggested change
| # DNS | |
| # k6/x/dns |
We usually keep the title and the H1 heading the same.
|
|
||
| {{< docs/shared source="k6" lookup="extension.md" version="<K6_VERSION>" >}} | ||
|
|
||
| The `k6/x/dns` modul enables DNS resolution testing in k6, allowing you to resolve DNS names to IP addresses using custom DNS servers or the system's default DNS configuration. This module is particularly useful for testing DNS server performance, validating DNS configurations, and incorporating DNS resolution into your load testing scenarios. |
There was a problem hiding this comment.
Suggested change
| The `k6/x/dns` modul enables DNS resolution testing in k6, allowing you to resolve DNS names to IP addresses using custom DNS servers or the system's default DNS configuration. This module is particularly useful for testing DNS server performance, validating DNS configurations, and incorporating DNS resolution into your load testing scenarios. | |
| The `k6/x/dns` module enables DNS resolution testing in k6, allowing you to resolve DNS names to IP addresses using custom DNS servers or the system's default DNS configuration. This module is useful for testing DNS server performance, validating DNS configurations, and incorporating DNS resolution into your load testing scenarios. |
|
|
||
| ### Basic DNS resolution with custom server | ||
|
|
||
| {{< code >}} |
There was a problem hiding this comment.
Suggested change
| {{< code >}} |
| } | ||
| ``` | ||
|
|
||
| {{< /code >}} |
There was a problem hiding this comment.
Suggested change
| {{< /code >}} |
| - DNS server unreachable or timeout | ||
| - DNS server returns an error response | ||
|
|
||
| {{< code >}} |
There was a problem hiding this comment.
Suggested change
| {{< code >}} |
| } | ||
| ``` | ||
|
|
||
| {{< /code >}} |
There was a problem hiding this comment.
Suggested change
| {{< /code >}} |
|
|
||
| These metrics help you monitor DNS performance and identify potential bottlenecks in your testing scenarios. | ||
|
|
||
| ## Notes on Usage |
There was a problem hiding this comment.
Suggested change
| ## Notes on Usage | |
| ## Best practices |
Comment on lines
+178
to
+181
| - **Nameserver format**: Always specify the port number (typically 53 for DNS) in the nameserver parameter | ||
| - **Record type support**: Currently supports "A" and "AAAA" record types; additional types may be added in future versions | ||
| - **Timeout behavior**: DNS queries have built-in timeouts; consider this when designing load tests | ||
| - **Load testing**: Use multiple VUs and iterations to properly test DNS server performance under load |
There was a problem hiding this comment.
Suggested change
| - **Nameserver format**: Always specify the port number (typically 53 for DNS) in the nameserver parameter | |
| - **Record type support**: Currently supports "A" and "AAAA" record types; additional types may be added in future versions | |
| - **Timeout behavior**: DNS queries have built-in timeouts; consider this when designing load tests | |
| - **Load testing**: Use multiple VUs and iterations to properly test DNS server performance under load | |
| - **Nameserver format**: Always specify the port number, typically 53 for DNS, in the nameserver parameter. | |
| - **Timeout behavior**: DNS queries have built-in timeouts; consider this when designing load tests. | |
| - **Load testing**: Use multiple VUs and iterations to properly test DNS server performance under load. |
The supported record types are already listed in the table above, so I think we can remove it from here.
|
|
||
| {{< admonition type="note">}} | ||
|
|
||
| This module is implemented as an official extension and is available natively in k6, requiring no additional installation or build steps thanks to native extensions support. See the [extensions documentation](/docs/k6/<K6_VERSION>/extensions/explore) for available extensions and details. |
There was a problem hiding this comment.
Suggested change
| This module is implemented as an official extension and is available natively in k6, requiring no additional installation or build steps thanks to native extensions support. See the [extensions documentation](/docs/k6/<K6_VERSION>/extensions/explore) for available extensions and details. | |
| This module is implemented as an official extension and is available natively in k6, requiring no additional installation or build steps. Refer to the [extensions documentation](/docs/k6/<K6_VERSION>/extensions/explore) for available extensions and details. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
This pull request adds comprehensive documentation for the new
k6/x/dnsextension module, which enables DNS resolution testing in k6. The documentation introduces the module, details its API, provides usage examples, explains error handling, and describes the metrics generated. The changes are organized into three new documentation pages: an overview, and detailed pages for theresolveandlookupfunctions.New documentation for the DNS extension:
Overview and Introduction
docs/sources/k6/next/javascript-api/k6-x-dns/_index.mdwith an overview of thek6/x/dnsmodule, its key features, use cases, API summary, available metrics, and practical code examples for DNS testing scenarios.API Reference and Usage Details
docs/sources/k6/next/javascript-api/k6-x-dns/resolve.mdwith detailed documentation for thedns.resolve()function, including parameters, return values, usage examples (A and AAAA record resolution, multiple DNS servers, performance comparison), error handling, metrics, and important notes on usage.docs/sources/k6/next/javascript-api/k6-x-dns/lookup.mdwith detailed documentation for thedns.lookup()function, including parameters, return values, usage examples (basic lookup, comparison with custom DNS, load testing, configuration validation), error handling, metrics, and usage notes.Checklist
npm startcommand locally and verified that the changes look good.docs/sources/k6/nextfolder of the documentation.Related PR(s)/Issue(s)