Socket on Grafana Labs

Socket.connect( port, [host] )

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

Socket.connect()

Asynchronously establishes a TCP connection to a remote server. Returns a Promise that resolves when the connection is established, or rejects on failure.

Signature

// Overload 1: port and optional host
socket.connect(port, host)

// Overload 2: options object
socket.connect(options)

Parameters

Overload 1

Parameter	Type	Description
port	number \| string	Destination port (1-65535)
host	string	Destination hostname or IP address. Defaults to `'localhost'`

Overload 2

Parameter	Type	Description
options.port	number \| string	Destination port (required)
options.host	string	Destination hostname or IP address. Defaults to `'localhost'`
options.tls	boolean	Enable TLS/SSL encryption. Defaults to `false`
options.tags	object	Custom tags for connection metrics (key-value pairs)

Returns

Type	Description
Promise<void>	Resolves when the connection is established. Rejects on connection failure

TLS/SSL configuration

When tls: true is set, the socket performs a TLS handshake after establishing the TCP connection. TLS settings such as certificates, verification, and cipher suites are controlled by k6’s standard TLS configuration.

Example

import { Socket } from "k6/x/tcp"

export default async function () {
  // Overload 1: connect with separate port and host
  const socket = new Socket()
  const closed = new Promise((resolve) => { socket.on("close", resolve) })
  socket.on("error", (err) => { console.error("Error:", err) })

  await socket.connect(8080, "example.com")
  console.log("Connected")
  socket.destroy()
  await closed

  // Overload 2: connect with options object and TLS
  const tlsSocket = new Socket({ tags: { protocol: "tls" } })
  const tlsClosed = new Promise((resolve) => { tlsSocket.on("close", resolve) })
  tlsSocket.on("error", (err) => { console.error("TLS error:", err) })

  await tlsSocket.connect({
    port: 443,
    host: "secure.example.com",
    tls: true,
  })
  console.log("TLS connection established")
  tlsSocket.destroy()
  await tlsClosed
}

Socket.write( data, [options] )

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

Socket.write()

Asynchronously sends data to the remote server. Returns a Promise that resolves when the data has been written to the socket.

Signature

socket.write(data, options)

Parameters

Parameter	Type	Description
data	string \| ArrayBuffer	Data to send. Use `ArrayBuffer` for binary data
options	object	Optional write configuration
options.encoding	string	Encoding for string data: `utf8` / `utf-8` (default), `ascii`, `base64`, `base64url`, `hex`. Ignored when `data` is an `ArrayBuffer`
options.tags	object	Custom tags for this write operation’s metrics (key-value pairs)

Returns

Type	Description
Promise<void>	Resolves when the data has been written to the socket

Example

import { Socket } from "k6/x/tcp"

export default async function () {
  const socket = new Socket()
  const closed = new Promise((resolve) => { socket.on("close", resolve) })
  socket.on("error", (err) => { console.error("Error:", err) })

  await socket.connect(8080, "example.com")

  // Write a plain text string (utf8 by default)
  await socket.write("Hello, server!")

  // Write base64-encoded data
  await socket.write("SGVsbG8gV29ybGQ=", { encoding: "base64" })

  // Write with custom tags for metrics
  await socket.write("request payload", {
    tags: { operation: "auth-request" },
  })

  socket.destroy()
  await closed
}

Socket.destroy()

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

Socket.destroy()

Closes the connection and destroys the socket. After you call destroy(), the socket transitions to the 'destroyed' state, and you can’t reuse it. A close event is emitted after the socket is destroyed.

Signature

socket.destroy();

Parameters

None.

Returns

void

Example

import { Socket } from 'k6/x/tcp';

export default async function () {
  const socket = new Socket();

  const closed = new Promise((resolve) => {
    socket.on('close', () => {
      console.log('Connection closed');
      resolve();
    });
  });

  socket.on('data', (data) => {
    const str = new TextDecoder().decode(data);
    console.log('Received:', str);
    socket.destroy();
  });

  socket.on('error', (err) => {
    console.error('Error:', err);
    socket.destroy();
  });

  const host = __ENV.TCP_HOST || 'localhost';
  const port = __ENV.TCP_PORT || '8080';

  await socket.connect(port, host);
  await socket.write('Hello, server!');

  await closed;
}

Socket.setTimeout( timeout )

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

Socket.setTimeout()

Sets the inactivity timeout for the socket. When the socket has been idle for timeout milliseconds without receiving data, a timeout event is emitted.

The socket doesn’t automatically close after a timeout. The connection remains open until you explicitly call destroy(). To disable a previously set timeout, pass 0.

Signature

socket.setTimeout(timeout);

Parameters

Parameter	Type	Description
timeout	number	Inactivity timeout in milliseconds. Pass `0` to disable

Returns

Type	Description
Socket	The socket instance, for method chaining

Example

import { Socket } from 'k6/x/tcp';

export default async function () {
  const socket = new Socket();

  const closed = new Promise((resolve) => {
    socket.on('close', () => {
      console.log('Connection closed');
      resolve();
    });
  });

  socket.on('data', (data) => {
    const str = new TextDecoder().decode(data);
    console.log('Received:', str);
    // Reset the timeout after each data event
    socket.setTimeout(5000);
  });

  socket.on('timeout', () => {
    console.log('No data received for 5 seconds — closing');
    socket.destroy();
  });

  socket.on('error', (err) => {
    console.error('Error:', err);
  });

  const host = __ENV.TCP_HOST || 'localhost';
  const port = __ENV.TCP_PORT || '8080';

  await socket.connect(port, host);
  console.log('Connected — waiting for data (5s timeout)');

  // Set timeout after connecting; no immediate write so the idle timer can fire
  socket.setTimeout(5000);

  await closed;
}

Socket.on( event, listener )

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

Socket.on()

Registers an event listener for a socket lifecycle event. All event handlers execute in the context of the k6 VU event loop.

Only one listener per event type is supported. Calling on() for an event that already has a listener replaces the previous one.

Signature

socket.on(event, listener);

Parameters

Parameter	Type	Description
event	string	Event name: `'connect'`, `'data'`, `'close'`, `'error'`, or `'timeout'`
listener	function	Callback invoked when the event fires

Events

connect

Emitted when the socket successfully establishes a connection to the remote server.

Signature

socket.on('connect', () => {
  // Connection established
});

data

Emitted when data is received from the remote endpoint. The data is provided as a Uint8Array.

Signature

socket.on('data', (data) => {
  // data is Uint8Array
});

Parameters

Parameter	Type	Description
data	Uint8Array	The received data

close

Emitted when the socket connection is fully closed, either by the local or remote side. This is the final event in the socket lifecycle and is emitted exactly once per socket.

Signature

socket.on('close', () => {
  // Connection fully closed
});

error

Emitted when a socket error occurs, such as a connection failure or network issue.

Signature

socket.on('error', (error) => {
  // Handle error
});

Parameters

Parameter	Type	Description
error	Error	The error object

timeout

Emitted when the socket times out due to inactivity as configured by setTimeout(). The socket doesn’t automatically close the connection—call destroy() to close it.

Signature

socket.on('timeout', () => {
  // Inactivity timeout reached
});

Returns

void

Example

import { Socket } from 'k6/x/tcp';

export default async function () {
  const socket = new Socket();

  const closed = new Promise((resolve) => {
    socket.on('close', () => {
      console.log('Connection closed');
      resolve();
    });
  });

  socket.on('connect', () => {
    console.log('Connected to server');
  });

  socket.on('data', (data) => {
    const str = new TextDecoder().decode(data);
    console.log('Received:', str);
    socket.destroy();
  });

  socket.on('error', (err) => {
    console.error('Socket error:', err);
    socket.destroy();
  });

  socket.on('timeout', () => {
    console.log('Socket timed out');
    socket.destroy();
  });

  const host = __ENV.TCP_HOST || 'localhost';
  const port = __ENV.TCP_PORT || '8080';

  await socket.connect(port, host);
  await socket.write('Hello, server!');

  await closed;
}