TCP Port Monitoring

Monitor any host and port, and assert on what answers

Databases, message queues, mail servers, custom services. A TCP monitor connects to host:port from 22 public locations or inside your own network, optionally sends data, and asserts on the response and the response time. Defined in TypeScript, deployed from CI, alerting built in.

Start for free Book a demo

postgres.check.ts

1// postgres.check.ts

2import { TcpMonitor, TcpAssertionBuilder, Frequency } from 'checkly/constructs'

4new TcpMonitor('postgres-primary', {

5 name: 'Postgres primary',

6 frequency: Frequency.EVERY_30S,

7 locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1'],

8 // Warn at 1s, fail at 3s

9 degradedResponseTime: 1000,

10 maxResponseTime: 3000,

11 request: {

12 hostname: 'db.acme.dev',

13 port: 5432,

14 ipFamily: 'IPv4',

15 assertions: [

16 TcpAssertionBuilder.responseTime().lessThan(1000),

17 ],

18 },

19})

Trusted by teams whose infrastructure is more than HTTP

“TCP checks are working nicely for our use case. We're using them to monitor some of our critical network services.”

Matt Watkins·Release Engineering Team, The Linux Foundation

An open port tells you the socket is up. Not that the service is.

Most port checks stop at the handshake. Checkly TCP monitors finish the conversation: send the payload your service expects, assert on the reply, and time each phase of the connection from every location you run it in.

responseData().contains()

A connection is not enough

A port that accepts a SYN can still be a dead service. Send a payload after the handshake and assert on what comes back: a PONG, a 220 banner, your own health string.

dns · connect · data

Latency, split into phases

Every run records DNS lookup, TCP connect, and data transfer separately, per location. Degrade at one threshold, fail at another, and see which phase moved.

privateLocations: [...]

Public edge or inside the VPC

Run from 22 public locations, or from a Checkly Agent inside your own network for the databases and brokers that were never meant to face the internet.

Monitor the infrastructure behind your endpoints

Your API monitor can pass while the database it depends on is refusing connections from half the world. Put a TCP monitor on every port your application needs and find out first.

5432330627017

Databases

Confirm Postgres, MySQL, or MongoDB accepts connections from outside the app tier, and how long the handshake takes from each region.

637956729092

Caches and message queues

Send PING to Redis and assert on PONG. Verify RabbitMQ or Kafka brokers are listening before the consumers start timing out.

587465993

Mail servers

Open SMTP submission or IMAPS, assert the 220 greeting arrives, and watch response time so a slow relay is caught before the queue backs up.

any port

Custom TCP services

Anything that speaks a line protocol. Send your own health-check payload and assert the response contains what your service should say.

should fail

Firewall and network rules

Flip "this request should fail" and a refused connection passes. Prove a port that must stay closed to the public still is, from 22 vantage points.

private location

Internal services

Run the same monitor on a Checkly Agent inside your VPC to reach hosts that are not exposed to the internet at all.

One honest limit: some public locations run on AWS, which blocks outbound port 25. Monitor SMTP on 587 or 465, or run the monitor from a private location. For plain host reachability and packet loss, Checkly also has ICMP ping monitors.

Every run, every location, every phase

A TCP result is more than up or down. Each run records the target, the state, the assertion outcome, and three timings: DNS lookup, TCP connect, and data transfer. When Singapore slows down or Sydney gets refused, you see which phase and which location before anyone opens a ticket.

Degraded and failed thresholds, so a slow handshake warns before it pages
Payload sent and response received, kept with every run
Retries with fixed, linear, or exponential backoff before an alert fires
Alerts to Slack, PagerDuty, Opsgenie, SMS, phone, webhooks, and more

When a monitor fails you can open an incident on a Checkly status page automatically, so the people waiting on that service hear it from you first.

postgres-primarydb.acme.dev:5432 · TCP · every 30s

N. Virginiaus-east-14 ms18 ms9 msresponseTime < 1000PASS

Irelandeu-west-16 ms72 ms11 msresponseTime < 1000PASS

Frankfurteu-central-15 ms81 ms10 msresponseTime < 1000PASS

Singaporeap-southeast-17 ms1,240 ms14 msdegraded > 1000 msDEGRADED

Sydneyap-southeast-29 ms··ECONNREFUSEDFAIL

4 of 5 locations connected · 1 degraded · 1 refusedalert: Sydney, 2 consecutive failures

redis.check.ts

1// redis.check.ts

2import { TcpMonitor, TcpAssertionBuilder } from 'checkly/constructs'

4new TcpMonitor('redis-cache', {

5 name: 'Redis cache (VPC)',

6 // Runs on the Checkly Agent inside your network

7 privateLocations: ['vpc-prod-eu'],

8 request: {

9 hostname: 'redis.internal.acme.dev',

10 port: 6379,

11 data: 'PING\r\n',

12 assertions: [

13 TcpAssertionBuilder.responseData().contains('PONG'),

14 TcpAssertionBuilder.responseTime().lessThan(200),

15 ],

16 },

17})

Define, test, deploy. TCP monitoring as code

The monitor is a TypeScript construct in your repo. Test it from CI, preview the deploy, apply it. Terraform and Pulumi providers cover the teams that live there instead.

Define the monitor in TypeScript

A TcpMonitor construct takes a hostname, a port, optional data to send, and assertions on response time and response data. Set degraded and failure thresholds, pick locations or a private location, and add alert channels. It lives in your repo next to the service it watches.

smtp.check.ts

1// smtp.check.ts

2import { TcpMonitor, TcpAssertionBuilder } from 'checkly/constructs'

4new TcpMonitor('smtp-relay', {

5 name: 'SMTP relay',

6 request: {

7 hostname: 'mail.acme.dev',

8 port: 587,

9 // Sent after the connection is established

10 data: 'EHLO checkly\r\n',

11 assertions: [

12 // The server greets, then acknowledges EHLO

13 TcpAssertionBuilder.responseData().contains('220'),

14 TcpAssertionBuilder.responseData().contains('250'),

15 TcpAssertionBuilder.responseTime().lessThan(1500),

16 ],

17 },

18})

Test it from CI

npx checkly test runs the monitor once from a Checkly location and reports pass or fail in the terminal. Put it in the pipeline that ships your infrastructure change and a broken port fails the build, not the on-call.

npx checkly test

$ npx checkly test
 
Running 2 checks in eu-west-1.
 
src/__checks__/postgres.check.ts
  ✔ Postgres primary (86ms)
src/__checks__/smtp.check.ts
  ✔ SMTP relay (241ms)
 
2 passed, 2 total

Deploy for continuous monitoring

deploy --preview shows exactly what will be created, updated, or deleted. deploy applies it. From then on the monitor runs on its schedule, retries on failure, and pages the channels you attached.

npx checkly deploy

$ npx checkly deploy --preview
 
Create:
    TcpMonitor: postgres-primary
    TcpMonitor: smtp-relay
 
$ npx checkly deploy

Priced per monitor, not per run

TCP monitors are uptime monitors: 10 included on Hobby, 50 on Starter, 75 on Team, more in blocks of 25. A 30-second schedule costs the same as a daily one. See pricing.

every 10s to 24h22 public locationsprivate locationsfull parity in the app

TCP port monitoring opens a TCP connection to a hostname and port on a schedule and records whether the connection succeeded and how long it took. Checkly TCP monitors go one step further: they can send data after the handshake and assert on the response, so you know the service behind the port is answering, not just that something is listening.

Anything that listens on a TCP port: Postgres, MySQL, and MongoDB databases, Redis, RabbitMQ and Kafka brokers, SMTP and IMAPS mail servers, FTP, SSH, and your own line-protocol services. For HTTP endpoints use a URL or API monitor, for DNS records a DNS monitor, and for plain host reachability an ICMP monitor.

Two things. Response time, with lessThan and greaterThan thresholds in milliseconds, and response data, with contains and notContains matches on whatever the server sends back after your optional payload. You also set two thresholds per monitor: degradedResponseTime (default 4000 ms) marks a run degraded, maxResponseTime (default 5000 ms) fails it.

From every 10 seconds to once every 24 hours, subject to the minimum interval on your plan. Monitors run from any of 22 public locations across the Americas, Europe, the Middle East, Africa, and Asia Pacific, or from private locations on your own infrastructure (Team and Enterprise plans).

Yes. Install the Checkly Agent inside your network as a private location and assign the monitor to it. The agent runs the TCP connection from inside your VPC and reports results back to Checkly, so nothing has to be opened to the public.

Yes. Enable "this request should fail" on the monitor and connection failures such as timeouts and refused ports count as passed, while a successful connection still passes. Only a failed assertion fails the check. Teams use this to confirm firewall rules and security groups are still applied.

TCP monitors are uptime monitors. Every plan includes a number of them: 10 on Hobby, 50 on Starter, 75 on Team, custom on Enterprise, with more available in blocks of 25. They are billed per monitor, not per run, so a 30-second schedule costs the same as a daily one. See the pricing page for current figures.

Put a monitor on every port that matters

Write one TcpMonitor construct, run it from CI, deploy it. The next time a database stops accepting connections, you will know before the API errors do.