k6/net/grpc on Grafana Labs

Client

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

Client

Client is a gRPC client that can interact with a gRPC server.

Method	Description
Client.load(importPaths, …protoFiles)	Loads and parses the given protocol buffer definitions to be made available for RPC requests.
Client.loadProtoset(protosetPath)	Loads and parses the given protoset file to be made available for RPC requests.
Client.connect(address [,params])	Opens a connection to the given gRPC server.
Client.invoke(url, request [,params])	Makes an unary RPC for the given service/method and returns a Response.
Client.healthCheck([service])	Check the status of the service using the Health Checking protocol.
Client.close()	Close the connection to the gRPC service.

Examples

import grpc from 'k6/net/grpc';

const client = new grpc.Client();
// Download quickpizza.proto for grpc-quickpizza.grafana.com, located at:
// https://raw.githubusercontent.com/grafana/quickpizza/refs/heads/main/proto/quickpizza.proto
// and put it in the same folder as this script.
client.load(null, 'quickpizza.proto');

export default () => {
  client.connect('grpc-quickpizza.grafana.com:443', { timeout: '5s' });

  const response = client.invoke('quickpizza.GRPC/RatePizza', {
    ingredients: ['Tomatoes', 'Cheese'],
    dough: 'Thin',
  });
  console.log(response.message.starsRating); // should print a number between 1-5

  client.close();
};

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

const client = new grpc.Client();
client.load([], 'authorization.proto', 'route_guide.proto');

export function setup() {
  client.connect('auth.googleapis.com:443');
  const resp = client.invoke('google.cloud.authorization.v1.AuthService/GetAccessToken', {
    username: 'john.smith@k6.io',
    password: 'its-a-secret',
  });
  client.close();
  return resp.message.accessToken;
}

export default (token) => {
  client.connect('route.googleapis.com:443');
  const metadata = {
    authorization: `bearer ${token}`,
  };
  const response = client.invoke(
    'google.cloud.route.v1.RoutingService/GetFeature',
    {
      latitude: 410248224,
      longitude: -747127767,
    },
    { metadata }
  );
  check(response, { 'status is OK': (r) => r && r.status === grpc.StatusOK });
  client.close();
};

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

const client = new grpc.Client();
client.load([], 'language_service.proto');

export default () => {
  if (__ITER == 0) {
    client.connect('language.googleapis.com:443');
  }
  const response = client.invoke('google.cloud.language.v1.LanguageService/AnalyzeSentiment', {});
  check(response, { 'status is OK': (r) => r && r.status === grpc.StatusOK });
  // Do NOT close the client
};

Params

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

Params

Params is an object used by the gRPC methods that generate RPC requests. Params contains request-specific options like headers that should be inserted into the request.

Name	Type	Description
`Params.authority`	string	Specifies the value of the :authority pseudo-header and as the server name in authentication handshake. If missing this is derived from the hostname.
`Params.discardResponseMessage`	boolean	Specify if response messages should be discarded. This reduces the amount of memory required, and the amount of garbage collection, which reduces the load on the testing machine and can help produce more reliable test results. Default is `false`.
`Params.metadata`	object	Object with key-value pairs representing custom metadata the user would like to add to the request. Values of keys ending with `-bin` will be treated as binary data.
`Params.tags`	object	Key-value pairs where the keys are names of tags and the values are tag values. Response time metrics generated as a result of the request will have these tags added to them, allowing the user to filter out those results specifically, when looking at results data.
`Params.timeout`	string / number	Request timeout to use. Default timeout is 60 seconds (`"60s"`). The type can also be a number, in which case k6 interprets it as milliseconds, e.g., `60000` is equivalent to `"60s"`.

Example of custom metadata headers and tags

import grpc from 'k6/net/grpc';

const client = new grpc.Client();
client.load([], 'route_guide.proto');

export default function () {
  const req = {
    latitude: 410248224,
    longitude: -747127767,
  };
  const params = {
    metadata: {
      'x-my-header': 'k6test',
      'x-my-header-bin': new Uint8Array([1, 2, 3]),
    },
    tags: { k6test: 'yes' },
  };
  const response = client.invoke('main.RouteGuide/GetFeature', req, params);
}

Response

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

Response

Name	Type	Description
`Response.status`	number	The response gRPC status code. Use the gRPC status constants to check equality.
`Response.message`	object	The successful protobuf message, serialized to JSON. Will be `null` if `status !== grpc.StatusOK`.
`Response.headers`	object	Key-value pairs representing all the metadata headers returned by the gRPC server.
`Response.trailers`	object	Key-value pairs representing all the metadata trailers returned by the gRPC server.
`Response.error`	object	If `status !== grpc.StatusOK` then the error protobuf message, serialized to JSON; otherwise `null`.

Example

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

const client = new grpc.Client();
client.load(null, 'quickpizza.proto');

export default () => {
  client.connect('grpc-quickpizza.grafana.com:443', {
    // plaintext: false
  });

  const data = { ingredients: ['Cheese'], dough: 'Thick' };
  const response = client.invoke('quickpizza.GRPC/RatePizza', data);

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

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

Stream

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

Stream

Using a gRPC client creates a stream. The client should be connected to the server (client.connect called) before creating a stream.

Class/Method	Description
Stream(client, url, [,params])	Using a connected gRPC client and the method’s URL creates a stream. Optionally, you can pass `params` for additional configuration options like tags, metadata, etc.
Stream.write(message)	Writes a message to the stream.
Stream.on(event, handler)	Sets up handler functions for various events on the gRPC stream.
Stream.end()	Signals to the server that the client has finished sending.
EventHandler	The handler function for various events on the gRPC stream.
Metadata	The metadata of a gRPC stream’s message.

Examples

A k6 script that sends several randomly chosen points from the pre-generated feature database with a variable delay in between. Prints the statistics when they are sent from the server.

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

const COORD_FACTOR = 1e7;

const GRPC_ADDR = __ENV.GRPC_ADDR || '127.0.0.1:10000';
const GRPC_PROTO_PATH = __ENV.GRPC_PROTO_PATH || '../../grpc_server/route_guide.proto';

const client = new Client();
client.load([], GRPC_PROTO_PATH);

// a sample DB of points
const DB = [
  {
    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',
  },
  {
    location: { latitude: 419611318, longitude: -746524769 },
    name: '287 Flugertown Road, Livingston Manor, NY 12758, USA',
  },
  {
    location: { latitude: 406109563, longitude: -742186778 },
    name: '4001 Tremley Point Road, Linden, NJ 07036, USA',
  },
  {
    location: { latitude: 416802456, longitude: -742370183 },
    name: '352 South Mountain Road, Wallkill, NY 12589, USA',
  },
  {
    location: { latitude: 412950425, longitude: -741077389 },
    name: 'Bailey Turn Road, Harriman, NY 10926, USA',
  },
  {
    location: { latitude: 412144655, longitude: -743949739 },
    name: '193-199 Wawayanda Road, Hewitt, NJ 07421, USA',
  },
];

export default () => {
  if (__ITER == 0) {
    client.connect(GRPC_ADDR, { plaintext: true });
  }

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

  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', (err) => {
    console.log('Stream Error: ' + JSON.stringify(err));
  });

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

  // send 5 random items
  for (let i = 0; i < 5; i++) {
    const point = DB[Math.floor(Math.random() * DB.length)];
    pointSender(stream, point);
  }

  // close the client stream
  stream.end();

  sleep(1);
};

const pointSender = (stream, point) => {
  console.log(
    'Visiting point ' +
      point.name +
      ' ' +
      point.location.latitude / COORD_FACTOR +
      ', ' +
      point.location.longitude / COORD_FACTOR
  );

  // send the location to the server
  stream.write(point.location);

  sleep(0.5);
};

A k6 script that sends a rectangle message and results (features) are streamed back to the client.

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

const COORD_FACTOR = 1e7;

const GRPC_ADDR = __ENV.GRPC_ADDR || '127.0.0.1:10000';
const GRPC_PROTO_PATH = __ENV.GRPC_PROTO_PATH || '../../grpc_server/route_guide.proto';

const client = new Client();

client.load([], GRPC_PROTO_PATH);

export default () => {
  client.connect(GRPC_ADDR, { plaintext: true });

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

  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('end', function () {
    // The server has finished sending
    client.close();
    console.log('All done');
  });

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

  // send a message to the server
  stream.write({
    lo: {
      latitude: 400000000,
      longitude: -750000000,
    },
    hi: {
      latitude: 420000000,
      longitude: -730000000,
    },
  });

  sleep(0.5);
};

The preceding examples use a demo server, which you can run with the following command (Golang should be installed) in k6 repository’s root:

go run -mod=mod examples/grpc_server/*.go

Constants

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

Constants

Define constants to distinguish between gRPC Response statuses.

Constant	Description
`StatusOK`	OK is returned on success.
`StatusCanceled`	Canceled indicates the operation was canceled (typically by the caller).
`StatusUnknown`	Unknown error.
`StatusInvalidArgument`	InvalidArgument indicates the client specified an invalid argument.
`StatusDeadlineExceeded`	DeadlineExceeded means operation expired before completion.
`StatusNotFound`	NotFound means some requested entity (e.g., file or directory) was not found.
`StatusAlreadyExists`	AlreadyExists means an attempt to create an entity failed because one already exists.
`StatusPermissionDenied`	PermissionDenied indicates the caller does not have permission to execute the specified operation.
`StatusResourceExhausted`	ResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
`StatusFailedPrecondition`	FailedPrecondition indicates operation was rejected because the system is not in a state required for the operation’s execution.
`StatusAborted`	Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.
`StatusOutOfRange`	OutOfRange means operation was attempted past the valid range. E.g., seeking or reading past end of file.
`StatusUnimplemented`	Unimplemented indicates operation is not implemented or not supported/enabled in this service.
`StatusInternal`	Internal errors. Means some invariants expected by the underlying system have been broken.
`StatusUnavailable`	Unavailable indicates the service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
`StatusDataLoss`	DataLoss indicates unrecoverable data loss or corruption.
`StatusUnauthenticated`	Unauthenticated indicates the request does not have valid authentication credentials for the operation.

Example

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

const client = new grpc.Client();
client.load(null, 'quickpizza.proto');

export default () => {
  client.connect('grpc-quickpizza.grafana.com:443', {
    // plaintext: false
  });

  const data = { ingredients: ['Cheese'], dough: 'Thick' };
  const response = client.invoke('quickpizza.GRPC/RatePizza', data);

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

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