Port (TCP) monitors

A Port (TCP) monitor answers one question on a schedule: can a TCP connection be opened to this host and port right now? If the connection succeeds, the service is up. If it's refused or times out — twice in a row — the monitor goes Down, an incident opens, and your alerts fire.

Use it for anything that listens on a socket but doesn't speak HTTP:

• Databases — PostgreSQL (5432), MySQL/MariaDB (3306), MongoDB (27017)
• Mail — SMTP (25, 465, 587), IMAP (993)
• Caches and queues — Redis (6379), RabbitMQ (5672)
• Game and custom servers — Minecraft (25565), or any bespoke TCP service
• SSH (22) — to know a box is reachable at all

If the service does speak HTTP, prefer an HTTP uptime monitor — it can validate status codes and content, not just reachability. A port check confirms something is accepting connections; it can't tell you the service behind the port is healthy.

Create a port monitor

1. Go to /monitors and click to create a monitor (or open /monitors/create directly).
2. Fill in the shared fields:
   • Project — which project the monitor belongs to.
   • Name — a label, e.g. "Primary Postgres".
   • Type — choose Port. The type is fixed after creation.
   • Target — the host to probe, e.g. db1.example.com. A full URL also works — CompleteStatus extracts the host part.
   • Check interval — every 1 minute up to every day, subject to your plan's minimum.
   • Ownership attestation — tick "I'm authorized to monitor this target."
3. Fill in the port-specific fields and save. The first check runs on the next scheduler tick.

Port-specific fields

• Port (required) — the TCP port to test, 1–65535. E.g. 5432 for PostgreSQL.
• Host override (optional) — probe a different host than the monitor's target. Leave it blank to use the target host. Useful when the monitor is named after a service but the socket lives elsewhere, e.g. target example.com with the database on db.example.com.

That's the whole configuration — one host, one port.

How a check runs

1. The host is resolved through the SSRF guard: DNS is resolved first, and hosts that resolve to private, link-local or internal addresses are rejected before any connection is attempted.
2. CompleteStatus opens a plain TCP connection to the resolved IP on your configured port, with a 10-second connect timeout (the whole check is time-boxed to 30 seconds).
3. If the connection fails, it is retried once within the same check before the check counts as a failure.
4. The connection is closed immediately. No payloads are sent.

Up means the socket connected — nothing more. A database that accepts connections but rejects every query still shows as up; pair the port check with application-level monitoring (a heartbeat on a job that actually queries it) if you need that depth.

The single-port guardrail

CompleteStatus is not a port scanner and cannot be used as one. Each port monitor probes exactly one operator-configured port on one host — it never sweeps ranges, enumerates services, or fingerprints what's listening. The host is validated against internal network ranges on every check, so monitors can't be pointed at infrastructure you don't control. To watch several ports on the same host, create one monitor per port.

Reading the results

The monitor page shows a TCP port panel for the latest check:

• Reachability — Connected or Unreachable.
• Port — the port that was probed.
• Connect latency — how long the TCP handshake took, in milliseconds. This feeds the latency chart, so a service that starts accepting connections slowly (e.g. a database under load) shows up as a rising latency trend before it goes down.
• On failure, the raw connection error is shown — e.g. Connection refused (nothing listening) or a timeout (host unreachable or a firewall silently dropping packets).

Alerting

Port checks feed the same state machine as every other monitor type: two consecutive failures are required to confirm DOWN. The first refused or timed-out check is recorded as unconfirmed; if the next check also fails, the monitor goes Down, an incident opens with the connection error as its cause, and your down alert rules fire. The first successful connection afterwards flips the monitor back to Up, resolves the incident, and sends recovery alerts.

Route alerts by adding an alert rule on the monitor page — pick a channel, tick down and up, set a cooldown. See Alert channels for setting up email, Slack, webhooks and more.

Troubleshooting

• Works from your machine, fails from CompleteStatus — a firewall is almost always the reason. Database and cache ports are commonly restricted to known IPs. Allowlist the CompleteStatus probe's IP address in your firewall or security group, or expose the service through a bastion you're comfortable monitoring.
• Timeouts instead of refusals — a timeout usually means a firewall is dropping packets silently or the host is unreachable; connection refused means the host answered but nothing is listening on that port. The distinction narrows down where to look: network path versus the service itself.
• "Blocked" or SSRF errors — the host resolved to a private or internal address (e.g. 10.x.x.x, 192.168.x.x). CompleteStatus refuses to probe private networks by design. For services on a private network, monitor from the inside instead: a heartbeat monitor pinged by a local script that checks the port is the right pattern.
• Flapping between up and down — a service at its connection limit accepts some connections and refuses others. The single in-check retry absorbs one-off blips, but persistent flapping is a real capacity signal, not monitoring noise.

Related guides

• HTTP uptime monitors — the state machine and incident lifecycle in full.
• Cron and heartbeat monitors — for services on private networks that can't be probed from outside.
• Alert channels — where alerts go and how to configure them.
• TCP port monitoring — watching the services that aren't websites, on the blog.
• Ping vs HTTP checks — what "up" actually means at each layer.