k6/x/icmp on Grafana Labs

ping( target, [options] )

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

ping( target, [options] )

Sends ICMP echo requests (pings) to the specified target.

Signature

ping(target, options)

Parameters

Parameter	Type	Description
target	string	Hostname or IP address to ping.
options	PingOptions	Optional ping configuration options.

Returns

Type	Description
boolean	Returns `true` if the number of successful pings is greater than or equal to the threshold, otherwise `false`.

Example

import { ping } from "k6/x/icmp"

export default function () {
  const host = "8.8.8.8"

  console.log(`Pinging ${host}:`);

  if (ping(host)) {
    console.log(`Host ${host} is reachable`);
  } else {
    console.error(`Host ${host} is unreachable`);
  }
}

pingAsync( target, [optsOrCallback], [callback] )

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

pingAsync( target, [optsOrCallback], [callback] )

Sends ICMP echo requests (pings) to the specified target asynchronously.

Signature

await pingAsync(target, optsOrCallback, callback)

Parameters

Parameter	Type	Description
target	string	Hostname or IP address to ping.
optsOrCallback	PingOptions \| PingCallback	Optional ping options or callback function.
callback	PingCallback	Optional callback function for ping results.

Returns

Type	Description
Promise<boolean>	Promise that resolves to `true` if the number of successful pings is greater than or equal to the threshold, otherwise `false`.

Example

import { pingAsync } from "k6/x/icmp"

export default async function () {
  const host = "8.8.8.8"

  console.log(`Pinging ${host} with callback:`);

  const opts = {
    timeout: 1000,
    retries: 2,
    count: 5
  };

  const result = await pingAsync(host, opts, (err, { target, sent_at, received_at, seq, ttl, size, options }) => {
    if (err) {
      console.error(`${target}: ${err}`);

      return
    }

    const rtt = received_at - sent_at;

    console.log(`${size} bytes from ${target}: icmp_seq=${seq} ttl=${ttl} time=${rtt} ms`);
  });

  if (result) {
    console.log(`Host ${host} is reachable`);
  } else {
    console.error(`Host ${host} is unreachable`);
  }
}

PingOptions

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

PingOptions

Options for configuring the ping operation.

Properties

Property	Type	Description
id	number	Identifier for the ICMP session. It is a 16-bit unsigned integer. Default is a k6 process ID plus a VU ID modulo 65536.
seq	number	Starting sequence number for the ICMP echo request. It is a 16-bit unsigned integer. Default is a random value.
ttl	number	Time to live for the ping packets. This value is decremented by each router the packet passes through.
timeout	number \| string	Timeout for the single echo request and its response. The value is a number or string. The number value is in milliseconds, the string value contains the unit (for example, `2s`). If the timeout is exceeded, the callback will be invoked with an error and the result will be `false`. Default is `10s` (10 seconds).
deadline	number \| string	Deadline for the whole ping operation. The value is a number or string. The number value is in milliseconds, the string value contains the unit (for example, `2s`). The deadline includes all echo requests and their responses. If the deadline is exceeded, the callback will be invoked with an error and the result will be `false`. Default is no deadline.
count	number	Number of ping requests to send. Default is 1. If the count is set to a value greater than 1, the ping process will send multiple requests and returns `true` if at least `threshold` percent of the requests succeed.
threshold	number	Minimum percent of successful ping responses required for the ping operation to be considered successful. If this option is not set, the default is `100` (%).
size	number	Size of the data to include in the ping request, in bytes. If this option is not set, 56 bytes will be used (ping command default).
interval	number \| string	Interval between ping requests if `count` is set to a value greater than 1. The value is a number or string. The number value is in milliseconds, the string value contains the unit (for example, `2s`). Default is `1s` (1 second). A very low value can be used for DoS attacks, so the allowed minimum value can be configured via the `K6_PING_MINIMUM_INTERVAL` environment variable for safety. Default allowed minimum value is `500ms` (0.5 seconds).
source	string	Source IP address to use for the ping request. If not set, the system’s default source address will be used.
preferred_ip_version	IP	Preferred IP protocol version to use for the ping request if the target is not an IPv4 or IPv6 address. Valid values are `"ip4"` and `"ip6"`. If not set, `"ip4"` protocol will be used.
tags	object	Optional tags for metrics and logging (key-value pairs).

PingDetail

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

PingDetail

Data you receive as a parameter in the ping callback.

Properties

Property	Type	Description
alive	boolean	Indicates whether the target is reachable (if an echo reply was received).
target	string	Hostname or IP address that was pinged.
target_ip	string	Target IP address that was pinged.
target_ip_version	IP	Target IP version that was used for the ping request. Valid values are `"ip4"` and `"ip6"`.
sent_at	number	Timestamp when the request was sent. Value is in UTC milliseconds since the Unix epoch.
received_at	number	Timestamp when the response was received. Value is in UTC milliseconds since the Unix epoch.
ttl	number	Time to live from the echo reply, if a response was received.
id	number	Identifier for the ICMP session from the echo reply, if a response was received.
seq	number	Sequence number for the ICMP echo request from the echo reply, if a response was received.
size	number	Size of the ICMP echo reply, if a response was received.
options	PingOptions	Ping options used for the request.

PingCallback

Callback function for ping results. This function is called for every echo packet sent. If the deadline is exceeded, it is not called for the remaining packets. If the echo response has been received, the error value will be null, otherwise it contains the error.

Signature

(err, data) => void

Parameters

Parameter	Type	Description
err	Error \| null	Error object if an error occurred, otherwise `null`.
data	PingDetail	Data about the ping attempt, including timing and echo details.

IP

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

IP

IP protocol version enumeration.

Values

Value	Name	Description
`"ip4"`	V4	IPv4 protocol
`"ip6"`	V6	IPv6 protocol