Protocols on Grafana Labs

HTTP/2

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

HTTP/2

Overview

HTTP/2.0 is the latest version of the HTTP protocol. It improves significantly upon HTTP/1. Most importantly, it introduces a binary wire protocol with multiplexed streams over a single TCP connection. This solves a long-standing performance issue with HTTP/1.1: head-of-line blocking.

Well, it at least partially solves it. The TCP congestion control mechanisms can interfere with the intended independent nature of the multiplexed streams in cases of lost/dropped packets and retransmission/reassembly. The full solution is to run HTTP/2.0 over UDP, as Google implemented with QUIC.

Additional features of HTTP/2.0

Builtin compression of HTTP headers
Server push
Pipelining of requests
Prioritization of requests

Load testing HTTP/2 with k6

When you make HTTP requests in k6, k6 automatically upgrades the connection to HTTP/2.0 if the server supports it, just like your web browser would.

To check what protocol was used for a particular request, refer to the proto property of the response object.

import http from 'k6/http';
import { check, sleep } from 'k6';

export default function () {
  const res = http.get('https://quickpizza.grafana.com');
  check(res, {
    'protocol is HTTP/2': (r) => r.proto === 'HTTP/2.0',
  });
  sleep(1);
}

To see the values that the r.proto field can have, refer to the documentation for k6 HTTP.

WebSockets

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

WebSockets

Overview

WebSocket is a protocol that provides full-duplex communication channels over a single TCP connection. It is commonly used by single-page apps (SPAs) and mobile apps, to add server-push based functionality, which usually improves performance in polling-based solutions.

Load testing WebSockets with k6

Note
The k6/websockets module provides a more standard API than k6/ws. It implements the WebSockets API living standard and uses a global event loop instead of a local one for better performance.

We recommend using k6/websockets for new tests. The k6/experimental/websockets module has been deprecated.

Comparing HTTP-based tests to WebSocket ones, you’ll find differences in both structure and inner workings. The primary difference is that instead of continuously looping the main function (export default function () { ... }) over and over, each VU is now runs an asynchronous event loop.

The basic structure of a WebSocket test looks like this:

import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'wss://echo.websocket.org';
  const params = { tags: { my_tag: 'hello' } };

  const res = ws.connect(url, params, function (socket) {
    socket.on('open', () => console.log('connected'));
    socket.on('message', (data) => console.log('Message received: ', data));
    socket.on('close', () => console.log('disconnected'));
  });

  check(res, { 'status is 101': (r) => r && r.status === 101 });
}

In this example, the connect() method takes a “run” function as its third parameter. That function should accept a Socket object as its only parameter. The run function forms the basis of the asynchronous event loop.

When the WebSocket connection is created, the run function will be immediately called, all code inside it will be executed (usually code to set up event handlers), and then blocked until the WebSocket connection is closed (by the remote host or by using socket.close()).

Error handling

To catch errors happen during the life of a WebSocket connection, attach a handler to the “error” event:

import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'wss://echo.websocket.org';
  const params = { tags: { my_tag: 'hello' } };

  const res = ws.connect(url, params, function (socket) {
    socket.on('open', function open() {
      // ...
    });

    socket.on('error', function (e) {
      if (e.error() != 'websocket: close sent') {
        console.log('An unexpected error occured: ', e.error());
      }
    });
  });

  check(res, { 'status is 101': (r) => r && r.status === 101 });
}

Timers

To schedule a recurring action, use the socket.setInterval to specify a function to call at a particular interval.

import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'wss://echo.websocket.org';
  const params = { tags: { my_tag: 'hello' } };

  const res = ws.connect(url, params, function (socket) {
    socket.on('open', function open() {
      console.log('connected');

      socket.setInterval(function timeout() {
        socket.ping();
        console.log('Pinging every 1sec (setInterval test)');
      }, 1000);
    });

    socket.on('ping', () => console.log('PING!'));
    socket.on('pong', () => console.log('PONG!'));
    socket.on('close', () => console.log('disconnected'));
  });

  check(res, { 'status is 101': (r) => r && r.status === 101 });
}

Timeouts

To add a timeout to the WebSocket connection, pass both a handler function and a timeout value (in milliseconds) to the socket.setTimeout function.

import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'wss://echo.websocket.org';
  const params = { tags: { my_tag: 'hello' } };

  const res = ws.connect(url, params, function (socket) {
    socket.on('open', () => console.log('connected'));
    socket.on('close', () => console.log('disconnected'));

    socket.setTimeout(function () {
      console.log('2 seconds passed, closing the socket');
      socket.close();
    }, 2000);
  });

  check(res, { 'status is 101': (r) => r && r.status === 101 });
}

In the preceding example, the timeout will close the WebSocket connection after 2 seconds.

Multiple event handlers

You can attach multiple handler functions to an event:

import ws from 'k6/ws';
import { check } from 'k6';

export default function () {
  const url = 'wss://echo.websocket.org';
  const params = { tags: { my_tag: 'hello' } };

  const response = ws.connect(url, params, function (socket) {
    socket.on('open', function open() {
      console.log('connected');
      socket.send(Date.now());

      socket.setInterval(function timeout() {
        socket.ping();
        console.log('Pinging every 1sec (setInterval test)');
      }, 1000);
    });

    socket.on('ping', () => console.log('PING!'));
    socket.on('pong', () => console.log('PONG!'));
    socket.on('pong', () => {
      // Multiple event handlers on the same event
      console.log('OTHER PONG!');
    });

    socket.on('close', () => console.log('disconnected'));

    socket.on('error', (e) => {
      if (e.error() != 'websocket: close sent') {
        console.log('An unexpected error occurred: ', e.error());
      }
    });

    socket.setTimeout(function () {
      console.log('2 seconds passed, closing the socket');
      socket.close();
    }, 2000);
  });

  check(response, { 'status is 101': (r) => r && r.status === 101 });
}

gRPC

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

gRPC

Overview

gRPC is a lightweight, open-source RPC framework. It was originally developed by Google, with version 1.0 released in August 2016. Since then, it’s gained much attention and wide adoption.

Whereas JSON transmits as human-readable text, gRPC is binary. The binary format makes data transfer faster and more compact. In the benchmarks we’ve seen, gRPC has proved much faster than REST, gRPC’s more traditional, JSON-based counterpart. The messages and services used for gRPC are described in .proto files, containing definitions for Protocol Buffers (protobuf).

Load testing gRPC services with k6

Starting on k6 v0.49.0, k6 supports unary gRPC requests and streaming as part of the k6/net/grpc core module.

gRPC definitions

Before interacting with a gRPC service, k6 needs to learn the definitions of the messages and services.

One way to do that is to explicitly use the Client.load() method and load the client definitions from the local file system. The method accepts a list of import paths and a list of .proto files. k6 then loads all the definitions from the files and their dependencies.

import { Client } from 'k6/net/grpc';

const client = new Client();
client.load(['definitions'], 'hello.proto');

Alternatively, you can dynamically load the definitions by using the gRPC reflection protocol. To enable reflection, you can pass the reflect: true option to Client.connect(). k6 then loads all the definitions from the server and their dependencies.

This option is only possible if the server has been instrumented with reflection support.

import { Client } from 'k6/net/grpc';

const client = new Client();
client.connect('127.0.0.1:10000', { reflect: true });

Unary gRPC requests

Unary calls work the same way as regular HTTP requests. A single request is sent to a server, and the server replies with a single response.

import { Client, StatusOK } from 'k6/net/grpc';
import { check, sleep } from 'k6';

const client = new Client();
client.load(['definitions'], 'hello.proto');

export default () => {
  client.connect('127.0.0.1:10000', {});

  const data = { greeting: 'Bert' };
  const response = client.invoke('hello.HelloService/SayHello', data);

  check(response, {
    'status is OK': (r) => r && r.status === StatusOK,
  });

  console.log(JSON.stringify(response.message));

  client.close();
  sleep(1);
};

Streaming requires async functions

gRPC streaming relies on event handlers (stream.on) to process messages. In JavaScript, event handlers can only run when the call stack is empty. If your default function is synchronous, event handlers can only fire after it returns.

To let event handlers run during test execution, declare the default function as async and use a Promise to wait for the stream to complete. All of the streaming examples on this page follow this pattern.

Server gRPC streaming

In server streaming mode, the client sends a single request to the server, and the server replies with multiple responses.

The following example demonstrates server streaming:

import { Client, Stream } from 'k6/net/grpc';

const COORD_FACTOR = 1e7;

const client = new Client();

export default async function () {
  if (__ITER == 0) {
    client.connect('127.0.0.1:10000', { plaintext: true, reflect: true });
  }

  const stream = new Stream(client, 'main.FeatureExplorer/ListFeatures', null);

  await new Promise((resolve, reject) => {
    stream.on('data', function (feature) {
      console.log(
        `Found feature called "${feature.name}" at ${feature.location.latitude / COORD_FACTOR}, ${
          feature.location.longitude / COORD_FACTOR
        }`
      );
    });

    stream.on('error', function (e) {
      reject(e);
    });

    stream.on('end', function () {
      client.close();
      console.log('All done');
      resolve();
    });

    stream.write({
      lo: {
        latitude: 400000000,
        longitude: -750000000,
      },
      hi: {
        latitude: 420000000,
        longitude: -730000000,
      },
    });
  });
}

In this example, k6 connects to a gRPC server, creates a stream, and sends a message with latitude and longitude coordinates. The async default function wraps the stream logic in a Promise, which lets event handlers fire while the function awaits. When the server finishes sending data, the end handler closes the client and resolves the promise.

Client gRPC streaming

The client streaming mode is the opposite of the server streaming mode. The client sends multiple requests to the server, and the server replies with a single response.

The following example demonstrates client streaming:

import { Client, Stream } from 'k6/net/grpc';

const COORD_FACTOR = 1e7;
const client = new Client();

const points = [
  {
    location: { latitude: 407838351, longitude: -746143763 },
    name: 'Patriots Path, Mendham, NJ 07945, USA',
  },
  {
    location: { latitude: 408122808, longitude: -743999179 },
    name: '101 New Jersey 10, Whippany, NJ 07981, USA',
  },
  {
    location: { latitude: 413628156, longitude: -749015468 },
    name: 'U.S. 6, Shohola, PA 18458, USA',
  },
  {
    location: { latitude: 419999544, longitude: -740371136 },
    name: '5 Conners Road, Kingston, NY 12401, USA',
  },
  {
    location: { latitude: 414008389, longitude: -743951297 },
    name: 'Mid Hudson Psychiatric Center, New Hampton, NY 10958, USA',
  },
];

export default async function () {
  if (__ITER == 0) {
    client.connect('127.0.0.1:10000', { plaintext: true, reflect: true });
  }

  const stream = new Stream(client, 'main.RouteGuide/RecordRoute');

  await new Promise((resolve, reject) => {
    stream.on('data', (stats) => {
      console.log(`Finished trip with ${stats.pointCount} points`);
      console.log(`Passed ${stats.featureCount} features`);
      console.log(`Travelled ${stats.distance} meters`);
      console.log(`It took ${stats.elapsedTime} seconds`);
    });

    stream.on('error', (e) => {
      reject(e);
    });

    stream.on('end', () => {
      client.close();
      console.log('All done');
      resolve();
    });

    for (let i = 0; i < 3; i++) {
      const point = points[Math.floor(Math.random() * points.length)];
      console.log(
        `Visiting point ${point.name} ${point.location.latitude / COORD_FACTOR}, ${
          point.location.longitude / COORD_FACTOR
        }`
      );
      stream.write(point.location);
    }

    stream.end();
  });
}

In this example, k6 connects to a gRPC server, creates a stream, and sends three random points. The code wraps the stream logic in a Promise, the same pattern as the server streaming example. The server responds with trip statistics, and the end handler closes the client and resolves the promise.

Bidirectional gRPC streaming

In bi-directional streaming mode, the client and the server may send multiple messages.

From the API perspective, it combines the client and server streaming modes, so the code is similar to the examples above.

Streaming error handling

To catch errors that occur during streaming, you can use the error event handler.

The handler receives an error object.

import { Client, Stream } from 'k6/net/grpc';

const client = new Client();
const stream = new Stream(client, 'main.RouteGuide/RecordRoute');

stream.on('error', function (e) {
  // An error has occurred and the stream has been closed.
  console.log('Error: ' + JSON.stringify(e));
});

Protocol Buffers JSON Mapping

It’s important to note how k6 handles requests and messages. First, it tries to marshal the request/message in JSON format. Then, k6 uses the protojson package to encode or decode to a Protobuf message.

A limitation during this process is that the object you pass as a request/message must be serializable. That means structs like Map don’t work.

The benefit of using protojson is the canonical JSON encoding support. The Protocol Buffers documentation describes this mapping. Also note that according to ProtoJSON docs, the JSON value of a non-numeric float (e.g. NaN or Infinity) will be their equivalent string representation.

Examples

For instance, if you import "google/protobuf/wrappers.proto" and your proto-definitions look like this:

syntax = "proto3";

package testing;

import "google/protobuf/wrappers.proto";

service Service {
   rpc SayHey(google.protobuf.StringValue) returns (google.protobuf.StringValue);
   rpc DoubleInteger(google.protobuf.Int64Value) returns (google.protobuf.Int64Value);
}

When passing a message, you should use a string or an integer, not an object. As a result, you will receive a type that has already been marshaled.

import { Client } from 'k6/net/grpc';
const client = new Client();

// an example of passing a string
const respString = client.invoke('testing.Service/SayHey', 'John');
if (respString.message !== 'hey John') {
  throw new Error("expected to get 'hey John', but got a " + respString.message);
}

// an example of passing an integer
const respInt = client.invoke('testing.Service/DoubleInteger', '3');
if (respInt.message !== '6') {
  throw new Error("expected to get '6', but got a " + respInt.message);
}

Another example could be usage of oneof. Let’s say you have a proto-definition like this:

syntax = "proto3";

package testing;

service Service {
   rpc Test(Foo)  returns (Foo) {}
}

message Foo {
   oneof Bar {
     string code = 1;
     uint32 id = 2;
   }
}

In this case, you should pass an object either with code or id fields.

import { Client } from 'k6/net/grpc';
const client = new Client();

// calling RPC with filled code field
const respWithCode = client.invoke('testing.Service/Test', { code: 'abc-123' });

// calling RPC with filled id field
const respWithID = client.invoke('testing.Service/Test', { id: 123 });

Health Checking protocol

There is a dedicated support for the Health Checking protocol, which provides a standard way to check if a gRPC service is healthy and ready to serve requests. It eliminates the need to use the generic invoke method for health checks.

The Client.healthCheck() method implements this protocol and returns the health status of the specified service. If no service name is provided, it checks the overall server health.

SSL/TLS

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

SSL/TLS

Transport Layer Security (TLS), the successor of Secure Socket Layer (SSL), is the mechanism through which encrypted connections can be established between clients and servers on the web and through which data can flow with integrity intact.

Simplified, TLS is made possible by using a Public Key Infrastructure (PKI) involving private cryptographic keys, certificates of ownership (public, signed with private key), and certificate authorities (CAs, issuing and asserting the validity of issued certificates).

The entire system depends on the functioning operation of the CAs. The system trusts that the cryptographic keys that CAs use to sign certificates of ownership to site/domain owners are kept secret. It also depends on the domain owners’ ability to keep their private cryptographic keys secret.

If they fail to do so, they have to report the leak to the CA that issued the certificate. After this disclosure, the CA can revoke the certificate and, in doing so, let browsers and other clients know of the changes through the Online Certificate Status Protocol (OCSP).

TLS in k6

By default and without any special configuration, k6 connects and talks to servers over TLS. You just need to make sure that you specify your request URLs with the https scheme.

K6 supports the following TLS functionalities. Each is worth discussing in more detail:

TLS client certificates
TLS version and ciphers (restricting as well as checking what was used for a HTTP request by checking response object properties)
Online Certificate Status Protocol (OCSP)
AIA fetching for missing intermediates (opt-in via tlsAIAFetch, for servers that rely on Authority Information Access rather than bundling the full chain)
Response.timings.tls_handshaking