k6/x/dns on Grafana Labs

resolve( query, recordType, nameserver )

Mon, 21 Sep 2026 15:16:28 +0000

resolve( query, recordType, nameserver )

The dns.resolve function performs DNS resolution using a specified DNS server and returns a promise that resolves to an array of IP addresses. This function allows you to test specific DNS servers, validate DNS configurations, and measure DNS resolution performance under load.

Parameters

Parameter	Type	Description
query	string	The domain name to resolve. For example, “example.com” or “k6.io”.
recordType	string	The DNS record type to query. Supported values: “A” (IPv4 addresses), “AAAA” (IPv6 addresses)
nameserver	string	The DNS server to use for resolution in the format “host:port”. For example, “8.8.8.8:53” or “[2606:4700:4700::1111]:53”

Returns

A promise resolving to an array of strings, where each string is an IP address that the domain name resolves to. For A records, these will be IPv4 addresses. For AAAA records, these will be IPv6 addresses.

Examples

Basic A record resolution

import dns from 'k6/x/dns';

export default async function () {
  // Resolve IPv4 addresses using Google's DNS server
  const ipv4Addresses = await dns.resolve('k6.io', 'A', '8.8.8.8:53');
  console.log('k6.io IPv4 addresses:', ipv4Addresses);
  // Output: k6.io IPv4 addresses: ["104.21.7.127", "172.67.154.74"]
}

AAAA record resolution

import dns from 'k6/x/dns';

export default async function () {
  // Resolve IPv6 addresses using Cloudflare's IPv6 DNS server
  const ipv6Addresses = await dns.resolve('k6.io', 'AAAA', '[2606:4700:4700::1111]:53');
  console.log('k6.io IPv6 addresses:', ipv6Addresses);
  // Output: k6.io IPv6 addresses: ["2606:4700:3033::6815:77f", "2606:4700:3030::ac43:9a4a"]
}

Testing multiple DNS servers

import dns from 'k6/x/dns';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  vus: 5,
  duration: '30s',
};

const dnsServers = [
  '8.8.8.8:53',     // Google DNS
  '1.1.1.1:53',     // Cloudflare DNS
  '9.9.9.9:53',     // Quad9 DNS
];

export default async function () {
  const domain = 'example.com';

  for (const server of dnsServers) {
    try {
      const results = await dns.resolve(domain, 'A', server);

      expect(results.length).toBeGreaterThan(0);
      expect(results.every(ip => /^\d+\.\d+\.\d+\.\d+$/.test(ip))).toBeTruthy();

      console.log(`${server} resolved ${domain} to:`, results);
    } catch (error) {
      console.error(`Failed to resolve ${domain} using ${server}:`, error);
    }
  }
}

Performance comparison

import dns from 'k6/x/dns';
import { Trend } from 'k6/metrics';

const resolutionTime = new Trend('custom_dns_resolution_time');

export const options = {
  vus: 1,
  iterations: 100,
};

export default async function () {
  const startTime = Date.now();

  try {
    const results = await dns.resolve('k6.io', 'A', '8.8.8.8:53');
    const duration = Date.now() - startTime;

    resolutionTime.add(duration);

    console.log(`Resolution took ${duration}ms, found ${results.length} addresses`);
  } catch (error) {
    console.error('DNS resolution failed:', error);
  }
}

Error handling

The resolve function may throw errors in the following cases:

Invalid domain name format
Unsupported record type
DNS server unreachable or timeout
DNS server returns an error response

import dns from 'k6/x/dns';

export default async function () {
  try {
    const results = await dns.resolve('nonexistent.invalid', 'A', '8.8.8.8:53');
    console.log('Unexpected success:', results);
  } catch (error) {
    console.log('Expected DNS resolution error:', error.message);
  }
}

Metrics

When using dns.resolve, the following metrics are automatically generated:

dns_resolutions: Counter incremented for each resolution attempt
dns_resolution_duration: Trend measuring the time taken for DNS resolution

These metrics help you monitor DNS performance and identify potential bottlenecks in your testing scenarios.

Best practices

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.

lookup( hostname )

Mon, 21 Sep 2026 15:16:28 +0000

lookup( hostname )

The dns.lookup function performs DNS resolution using the system’s default DNS configuration and returns a promise that resolves to an array of IP addresses. This function is useful, for instance, for testing standard DNS resolution behavior and comparing it with custom DNS server results.

Parameters

Parameter	Type	Description
hostname	string	The domain name to resolve. For example, “example.com” or “k6.io”.

Returns

A promise resolving to an array of strings, where each string is an IP address that the domain name resolves to. The function returns the same IP addresses that would be returned by the system’s standard DNS resolution mechanism.

Metrics

When using dns.lookup, the following metrics are automatically generated:

dns_lookups: Counter incremented for each lookup attempt
dns_lookup_duration: Trend measuring the time taken for DNS lookup

These metrics help you monitor DNS performance using your system’s DNS configuration.

Examples

Basic lookup

import dns from 'k6/x/dns';

export default async function () {
  // Resolve using system DNS servers
  const addresses = await dns.lookup('k6.io');
  console.log('k6.io resolves to:', addresses);
  // Output: k6.io resolves to: ["104.21.7.127", "172.67.154.74"]
}

Comparing system vs custom DNS

import dns from 'k6/x/dns';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export default async function () {
  const domain = 'example.com';

  // Get results from system DNS
  const systemResults = await dns.lookup(domain);

  // Get results from Google's DNS
  const googleResults = await dns.resolve(domain, 'A', '8.8.8.8:53');

  console.log('System DNS results:', systemResults);
  console.log('Google DNS results:', googleResults);

  // Check if both methods return results
  expect(systemResults.length).toBeGreaterThan(0);
  expect(googleResults.length).toBeGreaterThan(0);

  // Compare results (they might differ due to different DNS configurations)
  const hasCommonAddress = systemResults.some(ip => googleResults.includes(ip));
  expect(hasCommonAddress).toBeTruthy();
}

Testing DNS consistency

import dns from 'k6/x/dns';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  vus: 1,
  iterations: 10,
};

export default async function () {
  const domain = 'k6.io';

  try {
    const results = await dns.lookup(domain);

    expect(results.length).toBeGreaterThan(0);
    expect(results.every(ip =>
      /^\d+\.\d+\.\d+\.\d+$/.test(ip) || /^[0-9a-fA-F:]+$/.test(ip)
    )).toBeTruthy();

    console.log(`Iteration ${__ITER}: ${domain} -> ${results.join(', ')}`);
  } catch (error) {
    console.error('DNS lookup failed:', error);
  }
}

Load testing with system DNS

import dns from 'k6/x/dns';
import { sleep } from 'k6';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
import { Trend, Rate } from 'k6/metrics';

const lookupDuration = new Trend('dns_lookup_duration_custom');
const successRate = new Rate('dns_lookup_success_rate');

export const options = {
  vus: 10,
  duration: '60s',
};

const domains = [
  'k6.io',
  'example.com',
  'google.com',
  'github.com',
  'stackoverflow.com',
];

export default async function () {
  const domain = domains[Math.floor(Math.random() * domains.length)];
  const startTime = Date.now();

  try {
    const results = await dns.lookup(domain);
    const duration = Date.now() - startTime;

    lookupDuration.add(duration);
    successRate.add(true);

    expect(results.length).toBeGreaterThan(0);

    console.log(`${domain} resolved in ${duration}ms to ${results.length} addresses`);
  } catch (error) {
    const duration = Date.now() - startTime;
    lookupDuration.add(duration);
    successRate.add(false);

    console.error(`Failed to resolve ${domain}: ${error.message}`);
  }

  sleep(1);
}

Validating DNS configuration

import dns from 'k6/x/dns';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export default async function () {
  const testDomains = [
    'k6.io',
    'grafana.com',
    'example.com',
  ];

  for (const domain of testDomains) {
    try {
      const results = await dns.lookup(domain);

      expect(results.length).toBeGreaterThan(0);
      expect(results.every(ip => {
        // Basic IPv4/IPv6 validation
        return /^\d+\.\d+\.\d+\.\d+$/.test(ip) || /^[0-9a-fA-F:]+$/.test(ip);
      })).toBeTruthy();

      console.log(`✓ ${domain}: ${results.join(', ')}`);
    } catch (error) {
      console.error(`✗ ${domain}: ${error.message}`);
    }
  }
}

Error handling

The lookup function may throw errors in the following cases:

Invalid hostname format
DNS resolution timeout
No DNS servers configured on the system
Network connectivity issues

import dns from 'k6/x/dns';

export default async function () {
  try {
    const results = await dns.lookup('nonexistent.invalid.domain.test');
    console.log('Unexpected success:', results);
  } catch (error) {
    console.log('Expected DNS lookup error:', error.message);
  }

  // Test with invalid hostname format
  try {
    const results = await dns.lookup('');
    console.log('Unexpected success with empty hostname:', results);
  } catch (error) {
    console.log('Expected error for empty hostname:', error.message);
  }
}