Client on Grafana Labs

Client.connect( url, [options] )

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

Client.connect()

Establishes a connection to an MQTT broker. When the connection is successfully established, the connect event is triggered.

Signature

client.connect(url, options)

Parameters

Parameter	Type	Description
url	string	Broker URL (for example, `mqtt://broker.emqx.io:1883`)
options	object	Optional connection configuration
options.keepalive	number	Keep-alive interval in seconds (default: 60)
options.connect_timeout	number	Connection timeout in milliseconds (default: 30000)
options.clean_session	boolean	Whether to start with a clean session (default: true)
options.servers	string[]	Array of broker URLs for failover
options.tags	object	Custom tags for metrics (key-value pairs)

Supported broker URL schemas

Schema	Description
`mqtt://`	Plain TCP connection (no encryption)
`mqtts://`	Secure connection over SSL/TLS
`tcp://`	Alias for `mqtt://`
`ssl://`	Alias for `mqtts://`
`tls://`	Alias for `mqtts://`
`ws://`	MQTT over WebSocket
`wss://`	MQTT over secure WebSocket

If the schema is omitted, mqtt:// is used as the default.

SSL/TLS configuration

The extension uses standard k6 TLS configuration for all SSL/TLS settings. Configure certificates, verification, and other TLS-related options using k6’s environment variables and configuration files.

Client.reconnect()

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

Client.reconnect()

Attempts to reconnect to the MQTT broker using the same connection parameters as the last successful connection.

Signature

client.reconnect()

Client.subscribe( topic, [options] )

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

Client.subscribe()

Subscribe to topics synchronously.

Signature

client.subscribe(topic, options)

Parameters

Parameter	Type	Description
topic	string \| string[]	Topic or array of topics to subscribe to
options	object	Optional subscription configuration
options.qos	number	Quality of Service level (0, 1, or 2). Default: 0
options.tags	object	Custom tags for metrics (key-value pairs)

Client.subscribeAsync( topic, [options] )

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

Client.subscribeAsync()

Subscribe to topics asynchronously. Returns a promise that resolves when the subscription is complete.

Signature

await client.subscribeAsync(topic, options)

Parameters

Parameter	Type	Description
topic	string \| string[]	Topic or array of topics to subscribe to
options	object	Optional subscription configuration
options.qos	number	Quality of Service level (0, 1, or 2). Default: 0
options.tags	object	Custom tags for metrics (key-value pairs)

Returns

A promise that resolves when the subscription is successfully completed.

Client.unsubscribe( topics, [options] )

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

Client.unsubscribe()

Unsubscribe from topics synchronously.

Signature

client.unsubscribe(topics, options)

Parameters

Parameter	Type	Description
topics	string \| string[]	Topic or array of topics to unsubscribe from
options	object	Optional unsubscribe configuration
options.tags	object	Custom tags for metrics (key-value pairs)

Client.unsubscribeAsync( topics, [options] )

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

Client.unsubscribeAsync()

Unsubscribe from topics asynchronously.

Signature

await client.unsubscribeAsync(topics, options)

Parameters

Parameter	Type	Description
topics	string \| string[]	Topic or array of topics to unsubscribe from
options	object	Optional unsubscribe configuration
options.tags	object	Custom tags for metrics (key-value pairs)

Returns

A promise that resolves when the unsubscription is complete.

Client.publish( topic, payload, [options] )

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

Client.publish()

Publish a message synchronously.

Signature

client.publish(topic, payload, options)

Parameters

Parameter	Type	Description
topic	string	Topic to publish to
payload	string \| ArrayBuffer	Message payload (string or binary data)
options	object	Optional publish configuration
options.qos	number	Quality of Service level (0, 1, or 2). Default: 0
options.retain	boolean	Whether the message should be retained by the broker. Default: false
options.tags	object	Custom tags for metrics (key-value pairs)

Client.publishAsync( topic, payload, [options] )

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

Client.publishAsync()

Publish a message asynchronously. Returns a promise that resolves when the message is published.

Signature

await client.publishAsync(topic, payload, options)

Parameters

Parameter	Type	Description
topic	string	Topic to publish to
payload	string \| ArrayBuffer	Message payload (string or binary data)
options	object	Optional publish configuration
options.qos	number	Quality of Service level (0, 1, or 2). Default: 0
options.retain	boolean	Whether the message should be retained by the broker. Default: false
options.tags	object	Custom tags for metrics (key-value pairs)

Returns

A promise that resolves when the message is successfully published.

Client.on( event, listener )

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

Client.on()

The on() method registers event handlers for various MQTT client lifecycle and message events. All event handlers execute in the context of the k6 VU event loop.

Signature

client.on(event, listener)

Parameters

Parameter	Type	Description
event	string	Event name (`connect`, `message`, `end`, `reconnect`, `error`)
listener	function	Callback function to handle the event

Events

connect

Triggered when the client successfully connects to the broker.

Signature

client.on("connect", () => {
  // Connection established
})

message

Triggered when a message is received on a subscribed topic.

Signature

client.on("message", (topic, payload) => {
  // Handle received message
})

Parameters

Parameter	Type	Description
topic	string	The topic the message was received on
payload	ArrayBuffer	The message payload as binary data

end

Triggered when the client disconnects from the broker.

Signature

client.on("end", () => {
  // Connection closed
})

reconnect

Triggered when the client attempts to reconnect to the broker.

Signature

client.on("reconnect", () => {
  // Reconnection attempt
})

error

Triggered when an error occurs during any MQTT operation.

Signature

client.on("error", (error) => {
  // Handle error
})

Parameters

Parameter	Type	Description
error	object	Error object
error.name	string	Always “MQTTError”
error.message	string	Error description
error.method	string	The method where the error occurred

Client.end( [options] )

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

Client.end()

Disconnect from the broker synchronously. When the disconnection is complete, the end event is triggered.

Signature

client.end(options)

Parameters

Parameter	Type	Description
options	object	Optional disconnect configuration
options.tags	object	Custom tags for metrics (key-value pairs)

Client.endAsync( [options] )

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

Client.endAsync()

Disconnect from the broker asynchronously. Returns a promise that resolves when the disconnection is complete.

Signature

await client.endAsync(options)

Parameters

Parameter	Type	Description
options	object	Optional disconnect configuration
options.tags	object	Custom tags for metrics (key-value pairs)

Returns

A promise that resolves when the client is successfully disconnected.