GrpcMonitor Construct

Learn more about gRPC Monitors in the gRPC monitor overview.

Use gRPC Monitors to verify that your gRPC services are reachable, responding correctly, and meeting performance expectations. Monitors run in two modes:

BEHAVIOR — Invokes a unary gRPC method and asserts on the response
HEALTH — Queries the standard grpc.health.v1.Health/Check endpoint

Prerequisites

Before creating gRPC Monitors, ensure you have:

An initialized Checkly CLI project
The hostname and port of the gRPC service you want to monitor
In BEHAVIOR mode: the fully-qualified method name and a service definition. Use server reflection, an inline .proto file, or a compiled FlatBuffers .bfbs schema.
For FlatBuffers: install the flatc compiler

For additional setup information, see CLI overview.

import { Frequency, GrpcAssertionBuilder, GrpcMonitor } from "checkly/constructs"

new GrpcMonitor('grpc-health-1', {
  name: 'My Service Health Check',
  description: "Checks that **my-service** reports `SERVING` via the gRPC health protocol.",
  frequency: Frequency.EVERY_1M,
  request: {
    url: 'grpc.example.com',
    port: 50051,
    grpcConfig: {
      mode: 'HEALTH',
      tls: true,
      service: 'my.package.MyService',
    },
    assertions: [
      GrpcAssertionBuilder.healthCheckStatus().equals(1), // 1 = SERVING
      GrpcAssertionBuilder.responseTime().lessThan(500),
    ],
  },
})

import { Frequency, GrpcAssertionBuilder, GrpcMonitor } from "checkly/constructs"

new GrpcMonitor('grpc-behavior-1', {
  name: 'User Service GetUser',
  description: "Invokes `GetUser` on **user-service** and asserts the response.",
  activated: true,
  frequency: Frequency.EVERY_5M,
  locations: ['us-east-1', 'eu-west-1'],
  maxResponseTime: 3000,
  degradedResponseTime: 1500,
  request: {
    url: 'grpc.example.com',
    port: 50051,
    grpcConfig: {
      mode: 'BEHAVIOR',
      tls: true,
      serviceDefinition: 'REFLECTION',
      method: 'users.UserService/GetUser',
      message: '{"userId": "health-probe"}',
      metadata: [{ key: 'authorization', value: 'Bearer {{GRPC_TOKEN}}' }],
    },
    assertions: [
      GrpcAssertionBuilder.statusCode().equals(0),
      GrpcAssertionBuilder.responseTime().lessThan(1000),
      GrpcAssertionBuilder.responseMessage('$.name').notEmpty(),
    ],
  },
})

Use a FlatBuffers schema

Checkly consumes a compiled binary FlatBuffers schema (.bfbs), not the source .fbs file. Compile your schema locally:

Terminal

flatc -b --schema --bfbs-builtins schema.fbs

The command creates schema.bfbs. The --bfbs-builtins flag preserves attributes used for streaming and nested FlatBuffers fields. Load that binary file as base64 in your monitor:

grpc-flatbuffers.check.ts

import { readFileSync } from 'node:fs'
import { GrpcAssertionBuilder, GrpcMonitor } from 'checkly/constructs'

new GrpcMonitor('grpc-flatbuffers', {
  name: 'FlatBuffers gRPC service',
  request: {
    url: 'grpc.example.com',
    port: 443,
    grpcConfig: {
      mode: 'BEHAVIOR',
      tls: true,
      encoding: 'FLATBUFFERS',
      bfbsContent: readFileSync('schema.bfbs').toString('base64'),
      method: 'example.Greeter/Greet',
      message: JSON.stringify({ name: 'Checkly' }),
    },
    assertions: [
      GrpcAssertionBuilder.statusCode().equals(0),
      GrpcAssertionBuilder.responseTime().lessThan(1000),
    ],
  },
})

Do not set serviceDefinition or protoContent for FlatBuffers. The compiled bfbsContent provides the service definition.

Recompile the .fbs source whenever it changes. Checkly uploads the compiled .bfbs content and does not compile the source schema during a test or deployment.

Configuration

gRPC monitors have their own gRPC-specific settings, plus the standard monitor options shared across all check types.

gRPC Monitor Settings
General Monitor Settings

Parameter	Type	Required	Default	Description
`request`	`object`	✅	-	gRPC request configuration object
`degradedResponseTime`	`number`	❌	`10000`	Response time in milliseconds at which the monitor is marked as degraded
`maxResponseTime`	`number`	❌	`20000`	Response time in milliseconds at which the monitor is marked as failed (max 180,000)

Property	Type	Required	Default	Description
`name`	`string`	✅	-	Friendly name for your monitor
`description`	`string`	❌	`null`	A description of the monitor. Supports markdown. Max 500 characters
`activated`	`boolean`	❌	`true`	Whether the monitor is enabled
`alertChannels`	`Array<AlertChannel \| AlertChannelRef>`	❌	`[]`	Array of AlertChannel objects for notifications
`alertEscalationPolicy`	`AlertEscalationPolicy`	❌	-	Advanced alert escalation settings
`frequency`	`Frequency`	❌	`EVERY_10M`	How often to run your monitor
`group`	`CheckGroupV1` `CheckGroupV2`	❌	-	The CheckGroup this monitor belongs to
`locations`	`string[]`	❌	`[]`	Array of public location codes
`privateLocations`	`string[]`	❌	`[]`	Array of Private Location slugs
`muted`	`boolean`	❌	`false`	Whether alert notifications are muted
`tags`	`string[]`	❌	`[]`	Array of tags to organize monitors
`testOnly`	`boolean`	❌	`false`	Only run with test, not during deploy
`retryStrategy`	`RetryStrategy`	❌	-	Strategy for configuring retries
`runParallel`	`boolean`	❌	`false`	Run monitors in parallel or round-robin
`triggerIncident`	`IncidentTrigger`	❌	-	Create and resolve an incident based on the check’s alert configuration

`GrpcMonitor` Options

object

required

gRPC connection and call configuration.Usage:

new GrpcMonitor('grpc-monitor', {
  name: 'My gRPC Service',
  request: {
    url: 'grpc.example.com',
    port: 50051,
    grpcConfig: {
      mode: 'HEALTH',
      tls: true,
    },
    assertions: [
      GrpcAssertionBuilder.healthCheckStatus().equals(1), // 1 = SERVING
    ],
  },
})

Parameters:

Parameter	Type	Required	Default	Description
`url`	`string`	✅	-	Hostname or IP of the gRPC server. No scheme or port.
`port`	`number`	✅	-	Port the gRPC server listens on (1–65535)
`grpcConfig`	`object`	✅	-	gRPC-specific call configuration (see below)
`ipFamily`	`string`	❌	`'IPv4'`	IP family: `'IPv4'` \| `'IPv6'`
`skipSSL`	`boolean`	❌	`false`	Skip TLS certificate validation when `tls` is enabled
`timeout`	`number`	❌	`60`	Seconds to wait for the gRPC call to complete (1–180)
`assertions`	`GrpcAssertion[]`	❌	`[]`	Response assertions using `GrpcAssertionBuilder`

object

required

gRPC-specific call configuration nested inside request.Parameters:

Parameter	Type	Required	Default	Description
`mode`	`string`	❌	`'BEHAVIOR'`	Monitoring mode: `'BEHAVIOR'` \| `'HEALTH'`
`tls`	`boolean`	❌	`true`	Use TLS for the connection. Set to `false` for plaintext.
`metadata`	`Array<{key: string, value: string}>`	❌	`[]`	gRPC metadata (request headers) sent with the call
`encoding`	`string`	❌	`'PROTOBUF'`	Request and response encoding: `'PROTOBUF'` \| `'FLATBUFFERS'`. BEHAVIOR mode only.
`method`	`string`	BEHAVIOR	-	Fully-qualified method: `package.Service/Method`. Required in BEHAVIOR mode.
`serviceDefinition`	`string`	❌	`'REFLECTION'`	How to resolve the method schema: `'REFLECTION'` \| `'PROTO_FILE'`. BEHAVIOR mode only.
`protoContent`	`string`	❌	-	Inline `.proto` file content. Required when `serviceDefinition` is `'PROTO_FILE'`.
`bfbsContent`	`string`	FLATBUFFERS	-	Base64-encoded compiled `.bfbs` schema. Required when `encoding` is `'FLATBUFFERS'`.
`message`	`string`	❌	-	JSON-encoded request payload. BEHAVIOR mode only.
`service`	`string`	❌	-	Service name to health-check. HEALTH mode only. Leave empty to query overall server health.

number

default:"10000"

Response time in milliseconds at which the monitor is marked as degraded (warning state). Maximum: 180,000.Usage:

new GrpcMonitor('grpc-thresholds', {
  name: 'gRPC Latency Thresholds',
  degradedResponseTime: 1500,
  maxResponseTime: 3000,
  request: {
    url: 'grpc.example.com',
    port: 50051,
    grpcConfig: { mode: 'HEALTH' },
  },
})

number

default:"20000"

Response time in milliseconds at which the monitor is marked as failed. Maximum: 180,000.Usage:

new GrpcMonitor('grpc-thresholds', {
  name: 'gRPC Latency Thresholds',
  maxResponseTime: 3000,
  request: {
    url: 'grpc.example.com',
    port: 50051,
    grpcConfig: { mode: 'HEALTH' },
  },
})

`GrpcMonitor` Assertions

Use GrpcAssertionBuilder to define assertions for the request of a GrpcMonitor. The following sources are available:

responseTime(): Assert the total response time (DNS + connect + call) in milliseconds
statusCode(): Assert the numeric gRPC status code (0 = OK, 14 = UNAVAILABLE, etc.)
healthCheckStatus(): Assert the health status by its numeric value (HEALTH mode). The runner evaluates this as a number — not a string. Enum mapping: UNKNOWN=0, SERVING=1, NOT_SERVING=2, SERVICE_UNKNOWN=3
responseMessage(property?): Assert against the JSON response body (BEHAVIOR mode), with an optional JSON path (e.g. '$.name')
textBody(property?): Assert against the raw response body as text
responseMetadata(property?): Assert against response metadata (header) values returned by the server, identified by key

Here are some examples:

Assert the call returns gRPC OK (code 0):

GrpcAssertionBuilder.statusCode().equals(0)
// Equivalent to:
{ source: 'GRPC_STATUS_CODE', comparison: 'EQUALS', target: '0' }

Assert the health check reports SERVING (numeric target required — the runner does not accept string labels):

GrpcAssertionBuilder.healthCheckStatus().equals(1) // UNKNOWN=0, SERVING=1, NOT_SERVING=2, SERVICE_UNKNOWN=3
// Equivalent to:
{ source: 'GRPC_HEALTHCHECK_STATUS', comparison: 'EQUALS', target: '1' }

Assert a specific field in the JSON response body:

GrpcAssertionBuilder.responseMessage('$.userId').notEmpty()
// Equivalent to:
{ source: 'GRPC_RESPONSE', property: '$.userId', comparison: 'NOT_EMPTY', target: '' }

Assert the total response time:

GrpcAssertionBuilder.responseTime().lessThan(500)
// Equivalent to:
{ source: 'RESPONSE_TIME', comparison: 'LESS_THAN', target: '500' }

Assert a response metadata header value:

GrpcAssertionBuilder.responseMetadata('content-type').contains('grpc')
// Equivalent to:
{ source: 'GRPC_METADATA', property: 'content-type', comparison: 'CONTAINS', target: 'grpc' }

Learn more in our docs on Assertions.

General Monitor Options

string

required

Friendly name for your gRPC Monitor displayed in the Checkly dashboard and used in notifications.Usage:

new GrpcMonitor('my-grpc-monitor', {
  name: 'User Service Health',
  /* More options ... */
})

Frequency

How often the gRPC Monitor should run. Use the Frequency enum to set the check interval.Usage:

new GrpcMonitor('my-grpc-monitor', {
  name: 'User Service Health',
  frequency: Frequency.EVERY_1M,
  /* More options ... */
})

Available frequencies: EVERY_10S, EVERY_20S, EVERY_30S, EVERY_1M, EVERY_2M, EVERY_5M, EVERY_10M, EVERY_15M, EVERY_30M, EVERY_1H, EVERY_2H, EVERY_3H, EVERY_6H, EVERY_12H, EVERY_24H

string[]

default:"[]"

Array of public location codes where the gRPC Monitor runs from. Multiple locations provide geographic coverage.Usage:

new GrpcMonitor('global-grpc-monitor', {
  name: 'Global gRPC Health',
  locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],
  /* More options ... */
})

boolean

default:"true"

Whether the gRPC Monitor is enabled and will run according to its schedule.Usage:

new GrpcMonitor('my-grpc-monitor', {
  name: 'User Service Health',
  activated: false,
  /* More options ... */
})

Examples

Health check
Unary method (proto file)
Authenticated with metadata

import { Frequency, GrpcAssertionBuilder, GrpcMonitor } from "checkly/constructs"

new GrpcMonitor('auth-health', {
  name: 'Auth Service Health',
  frequency: Frequency.EVERY_1M,
  locations: ['us-east-1', 'eu-west-1'],
  request: {
    url: 'auth.internal.example.com',
    port: 50051,
    grpcConfig: {
      mode: 'HEALTH',
      tls: true,
      service: 'auth.AuthService',
    },
    assertions: [
      GrpcAssertionBuilder.healthCheckStatus().equals(1), // 1 = SERVING
      GrpcAssertionBuilder.responseTime().lessThan(500),
    ],
  },
})

import { Frequency, GrpcAssertionBuilder, GrpcMonitor } from "checkly/constructs"

new GrpcMonitor('order-get-order', {
  name: 'Order Service GetOrder',
  frequency: Frequency.EVERY_5M,
  maxResponseTime: 5000,
  degradedResponseTime: 2000,
  request: {
    url: 'orders.example.com',
    port: 443,
    grpcConfig: {
      mode: 'BEHAVIOR',
      tls: true,
      serviceDefinition: 'PROTO_FILE',
      protoContent: `syntax = "proto3";
package orders;
service OrderService { rpc GetOrder (GetOrderRequest) returns (Order); }
message GetOrderRequest { string order_id = 1; }
message Order { string order_id = 1; string status = 2; }`,
      method: 'orders.OrderService/GetOrder',
      message: '{"orderId": "probe-001"}',
    },
    assertions: [
      GrpcAssertionBuilder.statusCode().equals(0),
      GrpcAssertionBuilder.responseMessage('$.status').notEmpty(),
    ],
  },
})

import { Frequency, GrpcAssertionBuilder, GrpcMonitor } from "checkly/constructs"

new GrpcMonitor('secure-grpc', {
  name: 'Secure gRPC Service',
  frequency: Frequency.EVERY_2M,
  request: {
    url: 'secure-grpc.example.com',
    port: 443,
    grpcConfig: {
      mode: 'HEALTH',
      tls: true,
      metadata: [
        { key: 'authorization', value: 'Bearer {{GRPC_API_TOKEN}}' },
        { key: 'x-tenant-id', value: '{{TENANT_ID}}' },
      ],
    },
    assertions: [
      GrpcAssertionBuilder.healthCheckStatus().equals(1), // 1 = SERVING
    ],
  },
})

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

Use a FlatBuffers schema

Configuration

`GrpcMonitor` Options

`GrpcMonitor` Assertions

General Monitor Options

Examples

​Use a FlatBuffers schema

​Configuration

​GrpcMonitor Options

​GrpcMonitor Assertions

​General Monitor Options

​Examples

Use a FlatBuffers schema

Configuration

`GrpcMonitor` Options

`GrpcMonitor` Assertions

General Monitor Options

Examples