Client on Grafana Labs

Client.load(importPaths, ...protoFiles)

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

Client.load(importPaths, …protoFiles)

Loads and parses the protocol buffer descriptors so they are available to the client to marshal/unmarshal the correct request and response data structures for the RPC schema.

Must be called within the init phase.

Parameter	Type	Description
importPaths	Array<string> \| `null`	The paths used to search for dependencies that are referenced in import statements in proto source files. If no import paths are provided then “.” (current directory) is assumed to be the only import path.
protoFiles	Array<string>	Rest parameters for the list of proto files to load/parse.

Examples

import grpc from 'k6/net/grpc';

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

import grpc from 'k6/net/grpc';

const client = new grpc.Client();

client.load(
  ['../googleapis/google'],
  'spanner/admin/instance/v1/spanner_instance_admin.proto',
  'spanner/admin/instance/v1/spanner_instance_admin.proto',
  'spanner/v1/spanner.proto'
);

Client.loadProtoset(protosetPath)

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

Client.loadProtoset(protosetPath)

Loads and parses the protoset file (serialized FileDescriptor set) so they are available to the client to marshal/unmarshal the correct request and response data structures for the RPC schema.

Must be called within the init phase.

Parameter	Type	Description
protosetPath	string	The path of the protoset file. If no import paths are provided then “.” (current directory) is assumed to be the only import path.

Examples

import grpc from 'k6/net/grpc';

const client = new grpc.Client();
client.loadProtoset('./dummy.protoset');

Client.connect(address [,params])

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

Client.connect(address [,params])

Opens a connection to a gRPC server; will block until a connection is made or a connection error is thrown. Cannot be called during the init phase.

See Client.close() to close the connection.

Parameter	Type	Description
address	string	The address of the gRPC server. Should be in the form: `host:port` with no protocol prefix e.g. `grpc.k6.io:443`. The host must be a literal IP address, or a host name that can be resolved to IP addresses. The port must be a literal port number or a service name e.g. `:443` or `:https`. If the host is a literal IPv6 address it must be enclosed in square brackets, as in `[2001:db8::1]:80` or `[fe80::1%zone]:80`.
params (optional)	object	ConnectParams object containing additional connect parameters.

ConnectParams

Name	Type	Description
`ConnectParams.plaintext`	bool	If `true` will connect to the gRPC server using plaintext i.e. insecure. Defaults to `false` i.e. secure via TLS.
`ConnectParams.reflect`	boolean	Whether to use the gRPC server reflection protocol when connecting.
`ConnectParams.reflectMetadata`	object	Object with key-value pairs representing custom metadata the user would like to add to the reflection request.
`ConnectParams.timeout`	string / number	Connection timeout to use. Default timeout is `"60s"`. The type can also be a number, in which case k6 interprets it as milliseconds, e.g., `60000` is equivalent to `"60s"`.
`ConnectParams.maxReceiveSize`	number	Sets the maximum message size in bytes the client can receive. Defaults to `grpc-go` default, which is 4MB.
`ConnectParams.maxSendSize`	number	Sets the maximum message size in bytes the client can send. Defaults to `grpc-go` default, which is approximately 2GB.
`ConnectParams.tls` (optional)	object	TLS settings of the connection. Defaults to `null`.

TLS

TLS settings of the connection. If not defined, the main TLS config from options will be used.

Name	Type	Description
`tls.cert`	string	PEM formatted client certificate.
`tls.key`	string	PEM formatted client private key.
`tls.password`	string	Password for decrypting the client’s private key.
`tls.cacerts`	string / array	PEM formatted strings of the certificate authorities.

Examples

import grpc from 'k6/net/grpc';

const client = new grpc.Client();

export default () => {
  client.connect('localhost:8080');
};

import grpc from 'k6/net/grpc';

const client = new grpc.Client();

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

import grpc from 'k6/net/grpc';
import { check } from 'k6';
import { SharedArray } from 'k6/data';
import exec from 'k6/execution';

// note: the services in this example don't exist. If you would like
// to run this example, make sure to replace the URLs, and
// the cacerts, cert, key, and password variables.
const grpcArgs = new SharedArray('grpc', () => {
  // Using SharedArray here so that not every VU gets a copy of every certificate a key
  return [
    {
      host: 'foo1.grpc-quickpizza.grafana.com:443',
      plaintext: false,
      params: {
        tls: {
          cacerts: [open('cacerts0.pem')],
          cert: open('cert0.pem'),
          key: open('key0.pem'),
        },
      },
    },
    {
      host: 'foo2.grpc-quickpizza.grafana.com:443',
      params: {
        plaintext: false,
        tls: {
          cacerts: open('cacerts1.pem'),
          cert: open('cert1.pem'),
          key: open('key1.pem'),
          password: 'cert1-passphrase',
        },
      },
    },
  ];
});

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

export default () => {
  if (__ITER === 0) {
    // Take one config and use it for this one VU
    const grpcArg = grpcArgs[exec.vu.idInTest % grpcArgs.length];
    client.connect(grpcArg.host, grpcArg.params);
  }

  const response = client.invoke('quickpizza.GRPC/Status');

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

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

Client.asyncInvoke(url, request [,params])

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

Client.asyncInvoke(url, request [,params])

Asynchronously invokes an unary RPC request to the given method.

The given method to invoke must have its RPC schema previously loaded via the Client.load() function, otherwise an error will be thrown.

Client.connect() must be called first before invoking a request, otherwise an error will be thrown.

Parameter	Type	Description
url	string	The gRPC method URL to invoke, in the form `/package.Service/Method`, e.g. `/google.cloud.language.v1.LanguageService/AnalyzeSentiment`. The leading slash `/` is optional.
request	object	The canonical request object, as-per the Protobuf JSON Mapping.
params (optional)	object	Params object containing additional request parameters.

Returns

Type	Description
Promise with `Response`	gRPC Response object.

Examples

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

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

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

  client
    .asyncInvoke('main.RouteGuide/GetFeature', {
      latitude: 410248224,
      longitude: -747127767,
    })
    .then((response) => {
      check(response, { 'status is OK': (r) => r && r.status === grpc.StatusOK });
      console.log(response.message.name);
      // output: 3 Hasta Way, Newton, NJ 07860, USA

      client.close();
    });
};

Client.invoke(url, request [,params])

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

Client.invoke(url, request [,params])

Invokes an unary RPC request to the given method.

The given method to invoke must have its RPC schema previously loaded via the Client.load() function, otherwise an error will be thrown.

Client.connect() must be called first before invoking a request, otherwise an error will be thrown.

Parameter	Type	Description
url	string	The gRPC method URL to invoke, in the form `/package.Service/Method`, e.g. `/google.cloud.language.v1.LanguageService/AnalyzeSentiment`. The leading slash `/` is optional.
request	object	The canonical request object, as-per the Protobuf JSON Mapping.
params (optional)	object	Params object containing additional request parameters.

Returns

Type	Description
`Response`	gRPC Response object.

Examples

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

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

export default () => {
  client.connect('localhost:10000', { plaintext: true });
  const response = client.invoke('main.RouteGuide/GetFeature', {
    latitude: 410248224,
    longitude: -747127767,
  });
  check(response, { 'status is OK': (r) => r && r.status === grpc.StatusOK });
  console.log(response.message.name);
  // output: 3 Hasta Way, Newton, NJ 07860, USA

  client.close();
};

Client.close()

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

Client.close()

Close the connection to the gRPC service. Tear down all underlying connections.

Examples

import grpc from 'k6/net/grpc';

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

export default () => {
  client.connect('localhost:8080');
  client.close();
};

Client.healthCheck()

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

Client.healthCheck([service])

Check the health status of the gRPC service using the gRPC Health Checking protocol.

The method returns the health status of the provided service. If no service name is provided, it checks the overall server health.

The health check response includes a status field that can be one of the following constants:

HealthCheckServing: The service is healthy and serving requests
HealthCheckNotServing: The service is not serving requests
HealthCheckUnknown: The health status is unknown

Example

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

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

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

  // Check overall server health
  const res = client.healthCheck();

  check(res, {
    'server is healthy': (r) => r && r.status === grpc.StatusOK,
    'health status is serving': (r) => r && r.message.status === grpc.HealthCheckServing,
  });

  // Check specific service health
  const svcRes = client.healthCheck('my.service.Name');
  console.log('Health status:', svcRes.message.status);

  client.close();
};