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

# TracerouteMonitor Construct

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

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

Traceroute monitors map the network path to a host hop-by-hop, measuring per-hop latency and packet loss, and detecting whether the destination is reached. Use them to monitor path stability and catch routing issues before they affect your users.

> **Prerequisites**
>
> Before creating Traceroute Monitors, ensure you have:
>
> * An initialized Checkly CLI project
> * A hostname or IP address you want to trace
> * Basic understanding of network tracing (traceroute / tracert)
>
> For additional setup information, see [CLI overview](https://www.checklyhq.com/docs/cli/overview.md).

```ts Basic Example theme={null}
import { Frequency, TracerouteMonitor } from "checkly/constructs"

new TracerouteMonitor('traceroute-api', {
  name: 'API Gateway Network Path',
  description: "Maps the network path to `api.example.com` to detect routing changes.",
  frequency: Frequency.EVERY_5M,
  request: {
    url: 'api.example.com',
  },
})
```

```ts Advanced Example theme={null}
import { Frequency, TracerouteAssertionBuilder, TracerouteMonitor } from "checkly/constructs"

new TracerouteMonitor('traceroute-db', {
  name: 'Database Routing Monitor',
  description: "Traces path to `db.example.com` with strict latency and hop assertions.",
  activated: true,
  frequency: Frequency.EVERY_10M,
  locations: ['us-east-1', 'eu-central-1'],
  degradedResponseTime: 10000,
  maxResponseTime: 20000,
  request: {
    url: 'db.example.com',
    protocol: 'TCP',
    port: 5432,
    ipFamily: 'IPv4',
    maxHops: 20,
    maxUnknownHops: 10,
    ptrLookup: true,
    timeout: 15,
    assertions: [
      TracerouteAssertionBuilder.hopCount().lessThan(15),
      TracerouteAssertionBuilder.responseTime('avg').lessThan(50),
      TracerouteAssertionBuilder.packetLoss().lessThan(5),
    ],
  },
})
```

## Configuration

Traceroute monitors have their own probe-specific settings, plus the standard monitor options shared across all check types.

**Traceroute Monitor Settings**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `request` | `object` | ✅ | - | Traceroute request configuration object |
| `degradedResponseTime` | `number` | ❌ | `10000` | Final-hop avg RTT in milliseconds at which the monitor is marked as degraded |
| `maxResponseTime` | `number` | ❌ | `20000` | Final-hop avg RTT in milliseconds at which the monitor is marked as failed |

**General Monitor Settings**

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

### `TracerouteMonitor` Options

**request** `object` *required*

Traceroute request configuration, including probe protocol, target host, and response validation.

**Usage:**

```ts theme={null}
new TracerouteMonitor('traceroute-monitor', {
  name: 'Network Path Monitor',
  request: {
    url: 'api.example.com',
    protocol: 'TCP',
    port: 443,
    assertions: [
      TracerouteAssertionBuilder.hopCount().lessThan(20),
    ],
  },
})
```

**Parameters:**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `url` | `string` | ✅ | - | Target hostname or IP address. Do not include a scheme or port |
| `protocol` | `string` | ❌ | `'TCP'` | Probe protocol: `'TCP'` \| `'UDP'` \| `'ICMP'` \| `'SCTP'` |
| `port` | `number` | ❌ | `443` (TCP) / `33434` (UDP, SCTP) | Destination port (1–65535). Defaults to `443` for TCP and to `33434` — a high, typically closed port — for UDP/SCTP, so the destination returns ICMP Destination Unreachable to confirm arrival. Ignored (and not sent) when `protocol` is `'ICMP'` |
| `ipFamily` | `string` | ❌ | `'IPv4'` | IP family: `'IPv4'` \| `'IPv6'` |
| `maxHops` | `number` | ❌ | `30` | Maximum hops to probe (1–64) |
| `maxUnknownHops` | `number` | ❌ | `15` | Maximum consecutive unresponsive hops before stopping (1–30) |
| `ptrLookup` | `boolean` | ❌ | `true` | Perform reverse-DNS (PTR) lookups on hop IPs |
| `timeout` | `number` | ❌ | `10` | Seconds to wait for the trace to complete (1–30) |
| `assertions` | `TracerouteAssertion[]` | ❌ | `[]` | Response assertions using `TracerouteAssertionBuilder` |

**degradedResponseTime** `number` (default: 10000)

Final-hop average RTT in milliseconds at which the monitor is marked as degraded (warning state). Maximum: 30,000.

**Usage:**

```ts highlight={3} theme={null}
new TracerouteMonitor("traceroute-latency-tiers", {
  name: "API Network Path",
  degradedResponseTime: 5000, // Warn when final-hop avg RTT exceeds 5 seconds
  request: {
    url: 'api.example.com',
  },
})
```

**maxResponseTime** `number` (default: 20000)

Final-hop average RTT in milliseconds at which the monitor is marked as failed. Maximum: 30,000.

**Usage:**

```ts highlight={3} theme={null}
new TracerouteMonitor("traceroute-latency-tiers", {
  name: "API Network Path",
  maxResponseTime: 15000, // Fail when final-hop avg RTT exceeds 15 seconds
  request: {
    url: 'api.example.com',
  },
})
```

### `TracerouteMonitor` Assertions

Assertions for Traceroute monitors are defined using the `TracerouteAssertionBuilder`. The following sources are available:

* `responseTime(property?)`: Validate RTT at the final responding hop. Pass `'avg'`, `'min'`, `'max'`, or `'stdDev'` as the argument to target a specific statistic; when omitted, it defaults to `'avg'`. This assertion fails when `destinationReached` is `false`
* `hopCount()`: Assert against the total number of hops recorded in the trace
* `packetLoss()`: Assert against the packet loss percentage at the last recorded hop (0–100)

Here are some examples:

* Assert that the average final-hop latency is below a threshold (default property is `avg`):

```ts theme={null}
TracerouteAssertionBuilder.responseTime().lessThan(100)
// Equivalent to:
{ source: 'RESPONSE_TIME', property: 'avg', comparison: 'LESS_THAN', target: '100' }
```

* Assert against a specific RTT property:

```ts theme={null}
TracerouteAssertionBuilder.responseTime('max').lessThan(200)
// Equivalent to:
{ source: 'RESPONSE_TIME', property: 'max', comparison: 'LESS_THAN', target: '200' }
```

* Assert on the number of hops:

```ts theme={null}
TracerouteAssertionBuilder.hopCount().lessThan(15)
// Equivalent to:
{ source: 'HOP_COUNT', comparison: 'LESS_THAN', target: '15' }
```

* Assert on packet loss at the last hop:

```ts theme={null}
TracerouteAssertionBuilder.packetLoss().lessThan(10)
// Equivalent to:
{ source: 'PACKET_LOSS', comparison: 'LESS_THAN', target: '10' }
```

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 Traceroute Monitor that will be displayed in the Checkly dashboard and used in notifications.

**Usage:**

```ts highlight={2} theme={null}
new TracerouteMonitor("my-traceroute", {
  name: "API Gateway Network Path",
  /* More options ... */
})
```

**frequency** `Frequency`

How often the Traceroute Monitor should run. Use the `Frequency` enum to set the check interval.

**Usage:**

```ts highlight={3} theme={null}
new TracerouteMonitor("my-traceroute", {
  name: "API Gateway Network Path",
  frequency: Frequency.EVERY_5M,
  /* More options ... */
})
```

**Available frequencies**: `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`. Traceroute monitors do not support sub-30-second frequencies (`EVERY_10S` / `EVERY_20S`).

**locations** `string[]` (default: \[])

Array of [public location codes](https://www.checklyhq.com/docs/concepts/locations.md#public-locations) where the Traceroute Monitor should run from. Use `privateLocations` for [private locations](https://www.checklyhq.com/docs/platform/private-locations/overview.md). Multiple locations help detect regional routing differences.

**Usage:**

```ts highlight={3} theme={null}
new TracerouteMonitor("global-path-monitor", {
  name: "API Path from Multiple Regions",
  locations: ["us-east-1", "eu-central-1", "ap-southeast-1"],
  request: {
    url: 'api.example.com',
  },
})
```

**activated** `boolean` (default: true)

Whether the Traceroute Monitor is enabled and will run according to its schedule.

**Usage:**

```ts highlight={3} theme={null}
new TracerouteMonitor("my-traceroute", {
  name: "API Gateway Network Path",
  activated: false, // Disabled monitor
  request: {
    url: 'api.example.com',
  },
})
```


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