> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GrpcMonitor Construct

> Learn how to configure gRPC monitors with the Checkly CLI.

> [!TIP]
>
> Learn more about gRPC Monitors in [the gRPC monitor overview](https://www.checklyhq.com/docs/detect/uptime-monitoring/grpc-monitors/overview.md).

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 either server reflection enabled on the target or an inline `.proto` file
>
> For additional setup information, see [CLI overview](https://www.checklyhq.com/docs/cli/overview.md).

```ts HEALTH Mode theme={null}
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),
    ],
  },
})
```

```ts BEHAVIOR Mode theme={null}
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(),
    ],
  },
})
```

## Configuration

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

**gRPC Monitor Settings**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `request` | `object` | ✅ | - | gRPC request configuration object |
| `intent` | `CheckIntent` | ❌ | - | Structured guidance for root cause analysis and check repair. See [General Monitor Options](#general-monitor-options). |
| `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) |

**General Monitor Settings**

| 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` | ❌ | [`noRetries()`](https://www.checklyhq.com/docs/constructs/retry-strategy#default-retry-strategy) | 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

**request** `object` *required*

gRPC connection and call configuration.

**Usage:**

```ts theme={null}
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` |

**request.grpcConfig** `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 |
| `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'`. |
| `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. |

**degradedResponseTime** `number` (default: 10000)

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

**Usage:**

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

**maxResponseTime** `number` (default: 20000)

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

**Usage:**

```ts highlight={3} theme={null}
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):

```ts theme={null}
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):

```ts theme={null}
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:

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

* Assert the total response time:

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

* Assert a response metadata header value:

```ts theme={null}
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](https://www.checklyhq.com/docs/detect/assertions.md).

### General Monitor Options

**name** `string` *required*

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

**Usage:**

```ts highlight={2} theme={null}
new GrpcMonitor('my-grpc-monitor', {
  name: 'User Service Health',
  /* More options ... */
})
```

**frequency** `Frequency`

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

**Usage:**

```ts highlight={3} theme={null}
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`

**locations** `string[]` (default: \[])

Array of [public location codes](https://www.checklyhq.com/docs/concepts/locations.md#public-locations) where the gRPC Monitor runs from. Multiple locations provide geographic coverage.

**Usage:**

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

**activated** `boolean` (default: true)

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

**Usage:**

```ts highlight={3} theme={null}
new GrpcMonitor('my-grpc-monitor', {
  name: 'User Service Health',
  activated: false,
  /* More options ... */
})
```

**intent** `CheckIntent | null`

Describe what your check is intended to verify and the behavior that should be preserved. Checkly uses intent for root cause analysis across all check types. It is separate from `description` and does not replace executable assertions. Left unset, or set to `null`, the check has no intent.

> [!NOTE]
>
> Intent is used for [automatic repair](https://www.checklyhq.com/docs/resolve/automatic-check-repair.md) only for Browser and Multistep Checks.

The object accepts the following fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `goal` | `string` | Yes | The outcome your check should verify. Must contain 1–2,000 characters after trimming. |
| `constraints` | `CheckIntentConstraint[]` | No | Outcomes and guardrails that refine the goal. Omitted constraints become an empty array. |

Each constraint has a required `type` and `statement`:

* `REQUIRED_OUTCOME`: an outcome the check must verify.
* `MUST_PRESERVE`: behavior or an assertion that should be preserved when repairing the check.

Each `statement` must contain 1–1,000 characters after trimming. You can specify at most 20 constraints of each type. The CLI trims leading and trailing whitespace from the goal and statements and rejects unknown fields.

For example, configure intent on a Browser Check:

```ts theme={null}
import { BrowserCheck } from "checkly/constructs"

new BrowserCheck("dashboard-intent", {
  name: "Authenticated dashboard",
  code: {
    entrypoint: "./dashboard.spec.ts",
  },
  intent: {
    goal: "Verify that authenticated users can open the dashboard.",
    constraints: [
      {
        type: "REQUIRED_OUTCOME",
        statement: "Authentication succeeds for a valid user.",
      },
      {
        type: "MUST_PRESERVE",
        statement: "Do not remove or weaken the authentication assertion.",
      },
    ],
  },
})
```

## Examples

**Health check**

```ts theme={null}
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),
    ],
  },
})
```

**Unary method (proto file)**

```ts theme={null}
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(),
    ],
  },
})
```

**Authenticated with metadata**

```ts theme={null}
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
    ],
  },
})
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.