TcpMonitor Construct

Learn more about TCP Monitors in the TCP monitor overview.

Use TCP Monitors to verify connectivity and response times of your TCP services. The examples below show how to configure monitoring for different types of services.

Prerequisites

Before creating TCP Monitors, ensure you have:

An initialized Checkly CLI project
Network access to the TCP services you want to monitor
Knowledge of the target hostname and port number
Understanding of the expected response format (if sending data)

For additional setup information, see CLI overview.

import { TcpAssertionBuilder, TcpMonitor } from "checkly/constructs"

new TcpMonitor("database-tcp-1", {
  name: "Database Connection Check",
  description: "Verifies **PostgreSQL** on `db.example.com:5432` accepts connections.",
  activated: true,
  maxResponseTime: 5000,
  degradedResponseTime: 2000,
  request: {
    hostname: "db.example.com",
    port: 5432,
    ipFamily: "IPv4",
    assertions: [TcpAssertionBuilder.responseTime().lessThan(1000)],
  },
})

import { Frequency, TcpAssertionBuilder, TcpMonitor } from "checkly/constructs"

new TcpMonitor("redis-tcp-1", {
  name: "Redis Service Check",
  description: "Verifies **Redis service** is reachable and responsive.",
  activated: true,
  frequency: Frequency.EVERY_5M,
  locations: ["us-east-1", "eu-west-1"],
  maxResponseTime: 3000,
  degradedResponseTime: 1500,
  tags: ["redis", "cache", "critical"],
  request: {
    hostname: "redis.example.com",
    port: 6379,
    ipFamily: "IPv4",
    data: "PING\r\n",
    assertions: [
      TcpAssertionBuilder.responseTime().lessThan(500),
      TcpAssertionBuilder.responseData().contains("PONG"),
    ],
  },
})

Configuration

The TCP Monitoring configuration consists of specific TCP monitoring options and inherited general monitoring options.

TCP Monitor
General Monitor

Parameter	Type	Required	Default	Description
`request`	`object`	✅	-	TCP connection configuration object
`degradedResponseTime`	`number`	❌	`4000`	Response time threshold in milliseconds for degraded status
`maxResponseTime`	`number`	❌	`5000`	Maximum response time in milliseconds before marking as failed

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

`TcpMonitor` Options

request

object

required

TCP connection configuration that defines the hostname, port, and optional data to send.Usage:

new TcpMonitor("tcp-monitor", {
  name: "Database TCP Check",
  request: {
    hostname: "db.example.com",
    port: 5432,
    assertions: [TcpAssertionBuilder.responseTime().lessThan(1000)],
  },
})

Parameters:

Parameter	Type	Required	Default	Description
`hostname`	`string`	✅	-	The hostname to connect to (without scheme or port)
`port`	`number`	✅	-	The port number for the TCP connection
`ipFamily`	`string`	❌	`'IPv4'`	IP family: `'IPv4'` \| `'IPv6'`
`data`	`string`	❌	-	Data to send to the target host
`assertions`	`TcpAssertion[]`	❌	`[]`	Response assertions using `TcpAssertionBuilder`

Examples:

Database Connection
Redis with Commands
IPv6 Connection

new TcpMonitor("database-check", {
  name: "Database Connectivity",
  request: {
    hostname: "postgres.example.com",
    port: 5432,
    ipFamily: "IPv4",
    assertions: [TcpAssertionBuilder.responseTime().lessThan(1000)],
  },
})

new TcpMonitor("redis-ping", {
  name: "Redis PING Test",
  request: {
    hostname: "cache.example.com",
    port: 6379,
    data: "PING\r\n",
    assertions: [
      TcpAssertionBuilder.responseTime().lessThan(500),
      TcpAssertionBuilder.responseData().contains("PONG"),
    ],
  },
})

new TcpMonitor("ipv6-service", {
  name: "IPv6 Service Check",
  request: {
    hostname: "2001:db8::1",
    port: 80,
    ipFamily: "IPv6",
    assertions: [TcpAssertionBuilder.responseTime().lessThan(2000)],
  },
})

Use cases: Database connectivity, cache service monitoring, custom TCP service validation.

degradedResponseTime

number

default:"4000"

Response time threshold in milliseconds for marking the monitor as degraded (warning state).Usage:

new TcpMonitor("tiered-monitoring", {
  name: "Tiered Monitoring",
  degradedResponseTime: 1000, // Warning at 1 second
  maxResponseTime: 3000, // Fail at 3 seconds
  request: {
    hostname: "service.example.com",
    port: 3306,
  },
})

Examples:

// Progressive performance alerts
new TcpMonitor("mysql-performance", {
  name: "MySQL Performance Monitoring",
  degradedResponseTime: 800, // Warn at 800ms
  maxResponseTime: 2000, // Fail at 2s
  request: {
    hostname: "mysql.example.com",
    port: 3306,
    assertions: [TcpAssertionBuilder.responseTime().lessThan(2000)],
  },
})

Use cases: Early performance warnings, gradual degradation detection.

maxResponseTime

number

default:"5000"

Maximum response time in milliseconds before the monitor is marked as failed.Usage:

new TcpMonitor("fast-db", {
  name: "Fast DB Connection",
  maxResponseTime: 2000, // 2 seconds max
  request: {
    hostname: "fast-db.example.com",
    port: 5432,
  },
})

Examples:

// Low-latency database requirement
new TcpMonitor("performance-db", {
  name: "Performance Database",
  maxResponseTime: 1000, // Fail at 1 second
  degradedResponseTime: 500, // Warning at 500ms
  request: {
    hostname: "db.example.com",
    port: 5432,
  },
})

// Service with higher tolerance
new TcpMonitor("batch-service", {
  name: "Batch Processing Service",
  maxResponseTime: 10000, // 10 seconds
  request: {
    hostname: "batch.example.com",
    port: 8080,
  },
})

Use cases: Performance monitoring, SLA compliance, connection timeout management.

`TcpMonitor` Assertions

To define assertions for the request of an TcpMonitor you should use the TcpAssertionBuilder. The following sources are available for TCP monitor assertions:

responseTime(): Assert the total response time of the TCP request
responseData(): Assert the value in the response data

Here are some examples:

Assert the total response time of the TCP request

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

Asserting the value in the response

TcpAssertionBuilder.responseData().contains('ping')
// Equivalent to:
{ source: 'RESPONSE_DATA', comparison: 'CONTAINS', target: 'ping' }

Learn more in our docs on Assertions.

General Monitor Options

name

string

required

Friendly name for your TCP monitor that will be displayed in the Checkly dashboard and used in notifications.Usage:

new TcpMonitor('my-tcp-monitor', {
  name: 'Database Connection Monitor'
  /* More options ... */
})

frequency

Frequency

How often the TCP monitor should run. Use the Frequency enum to set the check interval.Usage:

import { Frequency } from 'checkly/constructs'

new TcpMonitor("my-monitor", {
  frequency: Frequency.EVERY_2M,
  /* More options ... */
})

Examples:

Critical Services
Standard Services
Background Services

// Database connectivity (high frequency)
new TcpMonitor("critical-db", {
  name: "Critical Database",
  frequency: Frequency.EVERY_1M, // Every minute
  /* More options ... */
})

// Application service (standard frequency)
new TcpMonitor("app-service", {
  name: "Application Service",
  frequency: Frequency.EVERY_5M, // Every 5 minutes
  /* More options ... */
})

// Background service (low frequency)
new TcpMonitor("background-service", {
  name: "Background Processing",
  frequency: Frequency.EVERY_15M, // Every 15 minutes
  /* 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 where the TCP monitor should run from. Multiple locations provide geographic coverage.Usage:

new TcpMonitor('global-monitor', {
  locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1']
})

Examples:

Multi-Region Database
Regional Service

// Database replication monitoring
new TcpMonitor("global-db", {
  name: "Global Database Connectivity",
  frequency: Frequency.EVERY_2M,
  locations: [
    "us-east-1", // N. Virginia
    "eu-west-1", // Ireland
    "ap-southeast-1", // Singapore
  ],
  request: {
    hostname: "db.example.com",
    port: 5432,
  },
})

// Regional service monitoring
new TcpMonitor("eu-service", {
  name: "European Service Monitor",
  frequency: Frequency.EVERY_5M,
  locations: ["eu-west-1", "eu-central-1"],
  request: {
    hostname: "db.example.com",
    port: 5432,
  },
})

Use cases: Global connectivity testing, regional service monitoring, network latency analysis.

activated

boolean

default:"true"

Whether the TCP monitor is enabled and will run according to its schedule.Usage:

new TcpMonitor('my-monitor', {
  activated: false // Disabled monitor
})

Examples:

// Temporarily disable a monitor
new TcpMonitor("maintenance-db", {
  name: "Database Under Maintenance",
  activated: false,
  request: {
    hostname: "maint-db.example.com",
    port: 5432,
  },
})

Examples

new TcpMonitor("postgres-check", {
  name: "PostgreSQL Connection",
  frequency: Frequency.EVERY_5M,
  maxResponseTime: 5000,
  degradedResponseTime: 2000,
  tags: ["database", "postgres"],
  request: {
    hostname: "db.example.com",
    port: 5432,
    assertions: [TcpAssertionBuilder.responseTime().lessThan(1000)],
  },
})

new TcpMonitor("redis-check", {
  name: "Redis Connectivity",
  frequency: Frequency.EVERY_2M,
  maxResponseTime: 2000,
  degradedResponseTime: 1000,
  tags: ["cache", "redis"],
  request: {
    hostname: "cache.example.com",
    port: 6379,
    data: "PING\r\n",
    assertions: [
      TcpAssertionBuilder.responseTime().lessThan(500),
      TcpAssertionBuilder.responseData().contains("PONG"),
    ],
  },
})

new TcpMonitor("smtp-check", {
  name: "SMTP Server Check",
  frequency: Frequency.EVERY_10M,
  maxResponseTime: 10000,
  degradedResponseTime: 5000,
  tags: ["email", "smtp"],
  request: {
    hostname: "mail.example.com",
    port: 587,
    assertions: [
      TcpAssertionBuilder.responseTime().lessThan(3000),
      TcpAssertionBuilder.responseData().contains("220"),
    ],
  },
})

new TcpMonitor("ssh-check", {
  name: "SSH Connectivity",
  frequency: Frequency.EVERY_15M,
  maxResponseTime: 5000,
  degradedResponseTime: 2000,
  tags: ["ssh", "server"],
  request: {
    hostname: "server.example.com",
    port: 22,
    assertions: [
      TcpAssertionBuilder.responseTime().lessThan(1000),
      TcpAssertionBuilder.responseData().contains("SSH"),
    ],
  },
})

new TcpMonitor("app-port-check", {
  name: "Custom Application Port",
  frequency: Frequency.EVERY_5M,
  maxResponseTime: 3000,
  degradedResponseTime: 1500,
  tags: ["application", "custom-port"],
  request: {
    hostname: "app.example.com",
    port: 8080,
    data: "HEALTH\n",
    assertions: [
      TcpAssertionBuilder.responseTime().lessThan(1000),
      TcpAssertionBuilder.responseData().contains("OK"),
    ],
  },
})

new TcpMonitor("blocked-port-check", {
  name: "Verify Port is Blocked",
  frequency: Frequency.EVERY_30M,
  maxResponseTime: 5000,
  degradedResponseTime: 2000,
  tags: ["security", "firewall"],
  request: {
    hostname: "secure.example.com",
    port: 23, // Telnet port that should be blocked
    assertions: [TcpAssertionBuilder.responseTime().lessThan(5000)],
  },
})

When sending data to services, ensure you use proper protocol formatting. For example, Redis commands should end with \r\n.

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

Configuration

`TcpMonitor` Options

`TcpMonitor` Assertions

General Monitor Options

Examples

​Configuration

​TcpMonitor Options

​TcpMonitor Assertions

​General Monitor Options

​Examples

Configuration

`TcpMonitor` Options

`TcpMonitor` Assertions

General Monitor Options

Examples