> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TcpMonitor Construct

> Learn how to configure TCP monitors with the Checkly CLI.

> [!TIP]
>
> Learn more about TCP Monitors in [the TCP monitor overview](https://www.checklyhq.com/docs/detect/uptime-monitoring/tcp-monitors/overview.md).

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](https://www.checklyhq.com/docs/cli/overview.md).

```ts Basic Example theme={null}
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)],
  },
})
```

```ts Advanced Example theme={null}
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**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `request` | `object` | ✅ | - | TCP connection configuration object |
| `intent` | `CheckIntent` | ❌ | - | Structured guidance for root cause analysis and check repair. See [General Monitor Options](#general-monitor-options). |
| `degradedResponseTime` | `number` | ❌ | `4000` | Response time threshold in milliseconds for degraded status |
| `maxResponseTime` | `number` | ❌ | `5000` | Maximum response time in milliseconds before marking as failed |
| `shouldFail` | `boolean` | ❌ | `false` | Treat connection failures (e.g. timeouts or refused ports) as passed. Successful connections still pass. Only failed assertions will cause the check to fail. |

**General Monitor**

| 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` | ❌ | [`noRetries()`](https://www.checklyhq.com/docs/constructs/retry-strategy#default-retry-strategy) | 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:**

```ts theme={null}
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**

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

**Redis with Commands**

```ts theme={null}
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"),
    ],
  },
})
```

**IPv6 Connection**

```ts theme={null}
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:

```ts highlight={3} theme={null}
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:

```ts theme={null}
// 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:

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

Examples:

```ts theme={null}
// 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

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

* Asserting the value in the response

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

Learn more in our docs on [Assertions](https://www.checklyhq.com/docs/detect/assertions.md).

### 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:

```ts highlight={2} theme={null}
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:

```ts highlight={4} theme={null}
import { Frequency } from 'checkly/constructs'

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

Examples:

**Critical Services**

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

**Standard Services**

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

**Background Services**

```ts theme={null}
// 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:

```ts highlight={2} theme={null}
new TcpMonitor('global-monitor', {
  locations: ['us-east-1', 'eu-west-1', 'ap-southeast-1']
})
```

Examples:

**Multi-Region Database**

```ts theme={null}
// 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**

```ts theme={null}
// 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:

```ts highlight={2} theme={null}
new TcpMonitor('my-monitor', {
  activated: false // Disabled monitor
})
```

Examples:

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

**intent** `CheckIntent | null`

Describe what your check is intended to verify and the behavior that should be preserved. Checkly uses intent for root cause analysis across all check types. It is separate from `description` and does not replace executable assertions. Left unset, or set to `null`, the check has no intent.

> [!NOTE]
>
> Intent is used for [automatic repair](https://www.checklyhq.com/docs/resolve/automatic-check-repair.md) only for Browser and Multistep Checks.

The object accepts the following fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `goal` | `string` | Yes | The outcome your check should verify. Must contain 1–2,000 characters after trimming. |
| `constraints` | `CheckIntentConstraint[]` | No | Outcomes and guardrails that refine the goal. Omitted constraints become an empty array. |

Each constraint has a required `type` and `statement`:

* `REQUIRED_OUTCOME`: an outcome the check must verify.
* `MUST_PRESERVE`: behavior or an assertion that should be preserved when repairing the check.

Each `statement` must contain 1–1,000 characters after trimming. You can specify at most 20 constraints of each type. The CLI trims leading and trailing whitespace from the goal and statements and rejects unknown fields.

For example, configure intent on a Browser Check:

```ts theme={null}
import { BrowserCheck } from "checkly/constructs"

new BrowserCheck("dashboard-intent", {
  name: "Authenticated dashboard",
  code: {
    entrypoint: "./dashboard.spec.ts",
  },
  intent: {
    goal: "Verify that authenticated users can open the dashboard.",
    constraints: [
      {
        type: "REQUIRED_OUTCOME",
        statement: "Authentication succeeds for a valid user.",
      },
      {
        type: "MUST_PRESERVE",
        statement: "Do not remove or weaken the authentication assertion.",
      },
    ],
  },
})
```

## Examples

**Database (PostgreSQL)**

```ts theme={null}
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)],
  },
})
```

**Redis Cache**

```ts theme={null}
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"),
    ],
  },
})
```

**SMTP Server**

```ts theme={null}
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"),
    ],
  },
})
```

**SSH Server**

```ts theme={null}
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"),
    ],
  },
})
```

**Custom Application Port**

```ts theme={null}
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"),
    ],
  },
})
```

**Connection Failure Test**

```ts theme={null}
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)],
  },
})
```

> [!WARNING]
>
> When sending data to services, ensure you use proper protocol formatting. For example, Redis commands should end with `\r\n`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.