Socket

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

Socket

The Socket class provides an event-driven interface for establishing TCP connections, sending and receiving data, and managing the connection lifecycle.

Constructor

new Socket(options);

Creates a new TCP socket in the disconnected state. Use connect() to establish a connection.

Parameters

Parameter	Type	Description
options	object	Optional socket configuration
options.tags	object	Custom tags for metrics (key-value pairs). Applied to all metrics generated by this socket

Properties

Property	Type	Description
`ready_state`	`SocketState`	Current connection state: `'disconnected'`, `'opening'`, `'open'`, or `'destroyed'`
`connected`	`boolean`	Read-only. `true` when `ready_state` is `'open'`
`local_ip`	`string \| undefined`	Local IP address. Only available after the socket connects
`local_port`	`number \| undefined`	Local port number. Only available after the socket connects
`remote_ip`	`string \| undefined`	Remote IP address. Only available after the socket connects
`remote_port`	`number \| undefined`	Remote port number. Only available after the socket connects
`bytes_written`	`number`	Total bytes sent through this socket
`bytes_read`	`number`	Total bytes received through this socket

Events

Register handlers for these events using socket.on(). The socket supports only one listener per event. Registering a second listener replaces the first.

Event	Listener signature	Description
`connect`	`() => void`	Emitted when the connection is established
`data`	`(data: Uint8Array) => void`	Emitted when data is received from the server
`close`	`() => void`	Emitted when the connection is fully closed
`error`	`(error: Error) => void`	Emitted on socket error
`timeout`	`() => void`	Emitted when the inactivity timeout fires (see `setTimeout()`)

Methods

Method	Description
connect()	Establish a TCP connection
write()	Send data over the socket
destroy()	Close and destroy the socket
setTimeout()	Set inactivity timeout
on()	Register an event handler

Example

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

export default async function () {
  const socket = new Socket({ tags: { service: 'echo' } });

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

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

  await socket.connect(port, host);
  console.log('Connected. State:', socket.ready_state);
  await socket.write('Hello, server!');

  await closed;
}

k6/x/tcp on Grafana Labs

Socket

Socket

Constructor

Parameters

Properties

Events

Methods

Example