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.
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",
  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.
ParameterTypeRequiredDefaultDescription
requestobject✅-TCP connection configuration object
degradedResponseTimenumber❌4000Response time threshold in milliseconds for degraded status
maxResponseTimenumber❌5000Maximum response time in milliseconds before marking as failed

​
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:
ParameterTypeRequiredDefaultDescription
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:
new TcpMonitor("database-check", {
  name: "Database Connectivity",
  request: {
    hostname: "postgres.example.com",
    port: 5432,
    ipFamily: "IPv4",
    assertions: [TcpAssertionBuilder.responseTime().lessThan(1000)],
  },
})
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.

​
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:
// Database connectivity (high frequency)
new TcpMonitor("critical-db", {
  name: "Critical Database",
  frequency: Frequency.EVERY_1M, // Every minute
  /* 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:
// 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,
  },
})
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)],
  },
})
When sending data to services, ensure you use proper protocol formatting. For example, Redis commands should end with \r\n.