Skip to main content
To configure a gRPC monitor using code, learn more about the gRPC Monitor Construct.

​
Basic Setup

Configure your gRPC monitor by specifying the target service and monitoring mode:
  • Host: The hostname or IP address of the gRPC server (e.g. grpc.example.com or 10.0.0.1). Do not include a scheme or port.
  • Port: The port the gRPC server is listening on (e.g. 50051)
  • IP family: Choose between IPv4 (default) or IPv6
  • TLS: Whether to use TLS encryption for the connection (default: enabled). Disable for plaintext connections.
  • Skip SSL verification: Skip TLS certificate validation. Useful for servers with self-signed certificates in non-production environments.

​
Monitoring Mode

Choose between two monitoring modes:

​
BEHAVIOR Mode (default)

Invokes a unary gRPC method and asserts on the response. Requires:
  • Method: The fully-qualified method name in package.Service/Method format (e.g. mypackage.MyService/GetUser)
  • Service definition: How the method schema is resolved:
    • Reflection (default): The runner discovers the method using gRPC server reflection. Requires reflection to be enabled on the server.
    • Proto file: Provide the .proto file content inline. The runner compiles it locally — no server reflection required.
  • Request message: Optional JSON-encoded payload sent as the gRPC request body
  • Metadata: Optional key/value pairs sent as gRPC request headers (e.g. authorization: Bearer {{MY_TOKEN}})

​
HEALTH Mode

Calls grpc.health.v1.Health/Check using the standard gRPC health-check protocol. Useful for monitoring overall server health without invoking a specific application method.
  • Service (optional): The name of the service to check. Leave empty to query overall server health.

​
Assertions

Use assertions to validate gRPC responses and ensure your service meets availability and performance expectations. You can create assertions based on:
  • Response time: Assert that the total gRPC call duration (including DNS and connection) is within a threshold
  • gRPC status code: Assert on the numeric gRPC status code. Common values: 0 (OK), 1 (CANCELLED), 2 (UNKNOWN), 4 (DEADLINE_EXCEEDED), 14 (UNAVAILABLE). See the gRPC status codes reference.
  • Health check status (HEALTH mode): Assert on the health status reported by the server. In the UI you select the status by name (SERVING, NOT_SERVING, UNKNOWN, SERVICE_UNKNOWN); the assertion target is stored and evaluated as the status’s numeric enum value (UNKNOWN=0, SERVING=1, NOT_SERVING=2, SERVICE_UNKNOWN=3), so via the API or CLI use the number (e.g. 1 for SERVING). Only equals / not-equals comparisons are supported.
  • Response message (BEHAVIOR mode): Assert against the JSON response body using a JSON path expression. For example:
    • $.status → assert on a top-level field
    • $.result.id → assert on a nested field
    • Learn more about JSON path assertions: JSON responses with JSON path
  • Response metadata: Assert against response metadata (header) values returned by the server, identified by key
For more details, see our documentation on Assertions.

​
Response Time Limits

Set performance thresholds for your gRPC service:
  • Degraded After: Time threshold (in milliseconds) after which the check is marked as degraded but not failed. Use for early performance warnings without triggering failure alerts.
  • Failed After: Time threshold after which the check is marked as failed. Use for hard latency limits that should trigger alerts.
The maximum allowed threshold is 180,000 ms (3 minutes), matching the maximum call timeout.

​
Frequency

Set how often the monitor runs (every 10 seconds to 24 hours).

​
Scheduling & Locations

  • Strategy: Choose between round-robin or parallel execution. Learn more about scheduling strategies
  • Locations: Select public or private locations to run the monitor from

​
Additional Settings