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.
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 . Basic Example
Advanced Example
import { TcpAssertionBuilder , TcpMonitor } from "checkly/constructs" new TcpMonitor ( "database-tcp-1" , { name: "Database Connection Check" , activated: true , maxResponseTime: 5000 , degradedResponseTime: 2000 , request: { hostname: "db.example.com" , port: 5432 , ipFamily: "IPv4" , assertions: [ TcpAssertionBuilder . responseTime (). lessThan ( 1000 )], }, })
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 requestobject✅ - TCP connection configuration object degradedResponseTimenumber❌ 4000Response time threshold in milliseconds for degraded status maxResponseTimenumber❌ 5000Maximum response time in milliseconds before marking as failed
Property Type Required Default Description namestring✅ - Friendly name for your monitor activatedboolean❌ trueWhether the monitor is enabled alertChannelsArray<AlertChannel | AlertChannelRef>❌ []Array of AlertChannel objects for notifications alertEscalationPolicyAlertEscalationPolicy❌ - Advanced alert escalation settings frequencyFrequency❌ EVERY_10MHow often to run your monitor groupCheckGroupV1 CheckGroupV2❌ - The CheckGroup this monitor belongs to locationsstring[]❌ []Array of public location codes privateLocationsstring[]❌ []Array of Private Location slugs mutedboolean❌ falseWhether alert notifications are muted tagsstring[]❌ []Array of tags to organize monitors testOnlyboolean❌ falseOnly run with test, not during deploy retryStrategyRetryStrategy❌ - Strategy for configuring retries runParallelboolean❌ falseRun monitors in parallel or round-robin
TcpMonitor OptionsTCP 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 hostnamestring✅ - The hostname to connect to (without scheme or port) portnumber✅ - The port number for the TCP connection ipFamilystring❌ 'IPv4'IP family: 'IPv4' | 'IPv6' datastring❌ - Data to send to the target host assertionsTcpAssertion[]❌ []Response assertions using TcpAssertionBuilder
Use the hostname parameter without including a scheme (like http://) or port number. Specify the port separately using the port parameter.
Define assertions using the TcpAssertionBuilder to validate both response time and response data: TcpAssertionBuilder . responseData (). contains ( "ping" ) TcpAssertionBuilder . responseTime (). lessThan ( 1000 ) TcpAssertionBuilder . responseTime (). greaterThan ( 5000 ) 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.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.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.General Monitor Options 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 ... */ }) 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_24HArray 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.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 Database (PostgreSQL)
Redis Cache
SMTP Server
SSH Server
Custom Application Port
Connection Failure Test
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.
