icmp

README

xk6-icmp

[!WARNING] This is an experimental extension for k6. It is not officially supported yet.
We are actively working on it to make it officially supported in the future.

ICMP protocol support for k6

xk6-icmp is a k6 extension that adds support for sending ICMP echo requests (pings) from your k6 scripts. This allows you to measure network latency and reachability of hosts directly within your load testing and synthetic monitoring scenarios.

The main use case for this extension is integration with Grafana's Synthetic Monitoring product to make a quick reachability check after a scripted check fails. It can also be used directly in k6 scripts, for example as a pre-check to verify network connectivity before running your main test.

Here is a basic example showing how to use the ping() function:

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`);
  }
}

A more advanced example below demonstrates how to use the callback to access detailed ping results for each request.

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: 3000,
    count: 5
  };

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

      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`);
  }
}

You can find more examples in the examples folder.

API documentation can be found at icmp.x.k6.io.

Metrics

The table below lists all the metrics generated by xk6-icmp during ping operations, along with their types, descriptions, and available tags.

Metric Name	Type	Description	Tags
icmp_packets_sent	Counter	Number of ICMP echo requests sent	proto, ip
icmp_packets_received	Counter	Number of ICMP echo replies received	proto, ip
icmp_reply_ttl	Gauge	TTL value from received ICMP replies
icmp_rtt	Trend	Round-trip time (RTT) for ICMP requests (milliseconds)	proto, ip
icmp_resolve	Trend	Time taken to resolve target address (milliseconds)	proto, ip
icmp_setup	Trend	Time taken to set up ICMP socket (milliseconds)	proto, ip
icmp_errors	Counter	Number of ICMP errors	proto, ip
data_sent	Counter	Total bytes sent (builtin k6 metric)
data_received	Counter	Total bytes received (builtin k6 metric)

You can pass custom tags in the options parameter to include additional metadata with each metric.

Tags:

• proto: Protocol used (ICMP)
• ip: Target IP address

These metrics allow you to monitor network latency, packet loss, TTL, and errors for each ping operation.

Elevated permission

Sending ICMP echo requests (pings) typically requires elevated (root or administrator) permissions because it involves creating raw network sockets. On supported platforms like Linux and Darwin (macOS), this extension will first attempt to use unprivileged ICMP sockets if available. If unprivileged ICMP is not supported or available, it will fall back to using privileged ICMP, which requires running k6 with elevated permissions. On other platforms, elevated permissions may always be required to send ICMP packets.

Linux

In most cases, unprivileged ICMP is already enabled by default on modern Linux distributions, so you can usually skip this section.

Enabling unprivileged ICMP

To enable unprivileged ICMP on Linux, you may need to adjust the system setting that controls whether non-root users can create ICMP sockets. You can do this by running the following command as root:

sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"

This command allows all user groups to create unprivileged ICMP sockets. To make this change persistent across reboots, add the following line to your /etc/sysctl.conf file:

net.ipv4.ping_group_range = 0

In most cases, this setting is already enabled by default on modern Linux distributions.

Granting Raw Socket Permission

If you do not want to run k6 as root but still need to allow it to create raw sockets for ICMP, you can grant the necessary capability using the setcap command. Run the following as root or with sudo:

sudo setcap cap_net_raw+ep /path/to/k6

Replace /path/to/k6 with the actual path to your k6 binary.
This command allows the k6 binary to create raw sockets (required for sending ICMP packets) without needing full root privileges.

Setuid

As a last resort, if you do not want to use unprivileged ICMP or grant raw socket capabilities with setcap, you can make the k6 binary setuid root. This allows any user to run k6 with root privileges, which enables sending ICMP packets.

[!WARNING] Setting the setuid bit on a binary can have significant security implications and is generally discouraged unless absolutely necessary.

To set the setuid bit, run the following commands as root:

sudo chown root:root /path/to/k6
sudo chmod u+s /path/to/k6

Replace /path/to/k6 with the actual path to your k6 binary.
This will allow k6 to run with root privileges even when executed by a non-root user.

[!WARNING] If you run k6 with root privileges (for example, using setuid bit or sudo command), any files created by the k6 process (such as output files, logs, or artifacts) will be owned by root. This can cause permission issues when accessing or modifying these files later as a non-root user.

Quick Start

1. Build a custom k6 binary with xk6-icmp
   You need to build k6 with this extension using xk6:

   go install go.k6.io/xk6/cmd/xk6@latest
   xk6 build --with github.com/grafana/xk6-icmp
   

2. Write your test script
   Use the example above or create your own test script using the ping() function.

3. Run your test
   Use your custom k6 binary to run the script:

   ./k6 run script.js
   

Download

Pre-built binaries for k6 with the xk6-mqtt extension are available on the Releases page.

Contributing

We welcome contributions! Please see the Contributing Guidelines for details on how to get started.

Status

xk6-icmp is in an early stage of development but is already usable. We are actively working to improve the extension. Feedback and contributions are welcome!

Documentation

Overview

Package icmp contains the xk6-icmp extension.