Skip to content

Commit 2b0cd4f

Browse files
danielpaulusdanielpaulus
authored
Merge pull request #428 from checkly/docs/traceroute-monitors
docs: add Traceroute monitor documentation
2 parents fe23fb8 + c8b0088 commit 2b0cd4f

5 files changed

Lines changed: 507 additions & 0 deletions

File tree

‎constructs/traceroute-monitor.mdx‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
---
2+
title: 'TracerouteMonitor Construct'
3+
description: 'Learn how to configure Traceroute monitors with the Checkly CLI.'
4+
sidebarTitle: 'Traceroute Monitor'
5+
canonical: 'https://www.checklyhq.com/docs/constructs/traceroute-monitor/'
6+
---
7+
8+
import GeneralMonitorOptionsTable from '/snippets/general-monitor-options-table.mdx';
9+
10+
<Tip>
11+
Learn more about Traceroute Monitors in [the Traceroute monitor overview](/detect/uptime-monitoring/traceroute-monitors/overview).
12+
</Tip>
13+
14+
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.
15+
16+
<Accordion title="Prerequisites">
17+
Before creating Traceroute Monitors, ensure you have:
18+
19+
- An initialized Checkly CLI project
20+
- A hostname or IP address you want to trace
21+
- Basic understanding of network tracing (traceroute / tracert)
22+
23+
For additional setup information, see [CLI overview](/cli/overview).
24+
</Accordion>
25+
26+
<CodeGroup>
27+
28+
```ts Basic Example
29+
import { Frequency, TracerouteMonitor } from "checkly/constructs"
30+
31+
new TracerouteMonitor('traceroute-api', {
32+
name: 'API Gateway Network Path',
33+
description: "Maps the network path to `api.example.com` to detect routing changes.",
34+
frequency: Frequency.EVERY_5M,
35+
request: {
36+
url: 'api.example.com',
37+
},
38+
})
39+
```
40+
41+
```ts Advanced Example
42+
import { Frequency, TracerouteAssertionBuilder, TracerouteMonitor } from "checkly/constructs"
43+
44+
new TracerouteMonitor('traceroute-db', {
45+
name: 'Database Routing Monitor',
46+
description: "Traces path to `db.example.com` with strict latency and hop assertions.",
47+
activated: true,
48+
frequency: Frequency.EVERY_10M,
49+
locations: ['us-east-1', 'eu-central-1'],
50+
degradedResponseTime: 10000,
51+
maxResponseTime: 20000,
52+
request: {
53+
url: 'db.example.com',
54+
protocol: 'TCP',
55+
port: 5432,
56+
ipFamily: 'IPv4',
57+
maxHops: 20,
58+
maxUnknownHops: 10,
59+
ptrLookup: true,
60+
timeout: 15,
61+
assertions: [
62+
TracerouteAssertionBuilder.hopCount().lessThan(15),
63+
TracerouteAssertionBuilder.responseTime('avg').lessThan(50),
64+
TracerouteAssertionBuilder.packetLoss().lessThan(5),
65+
],
66+
},
67+
})
68+
```
69+
70+
</CodeGroup>
71+
72+
## Configuration
73+
74+
Traceroute monitors have their own probe-specific settings, plus the standard monitor options shared across all check types.
75+
76+
<Tabs>
77+
<Tab title="Traceroute Monitor Settings">
78+
79+
| Parameter | Type | Required | Default | Description |
80+
|-----------|------|----------|---------|-------------|
81+
| `request` | `object` | ✅ | - | Traceroute request configuration object |
82+
| `degradedResponseTime` | `number` | ❌ | `10000` | Final-hop avg RTT in milliseconds at which the monitor is marked as degraded |
83+
| `maxResponseTime` | `number` | ❌ | `20000` | Final-hop avg RTT in milliseconds at which the monitor is marked as failed |
84+
85+
</Tab>
86+
<Tab title="General Monitor Settings">
87+
88+
<GeneralMonitorOptionsTable />
89+
90+
</Tab>
91+
</Tabs>
92+
93+
### `TracerouteMonitor` Options
94+
95+
<ResponseField name="request" type="object" required>
96+
97+
Traceroute request configuration, including probe protocol, target host, and response validation.
98+
99+
**Usage:**
100+
101+
```ts
102+
new TracerouteMonitor('traceroute-monitor', {
103+
name: 'Network Path Monitor',
104+
request: {
105+
url: 'api.example.com',
106+
protocol: 'TCP',
107+
port: 443,
108+
assertions: [
109+
TracerouteAssertionBuilder.hopCount().lessThan(20),
110+
],
111+
},
112+
})
113+
```
114+
115+
**Parameters:**
116+
117+
| Parameter | Type | Required | Default | Description |
118+
|-----------|------|----------|---------|-------------|
119+
| `url` | `string` | ✅ | - | Target hostname or IP address. Do not include a scheme or port |
120+
| `protocol` | `string` | ❌ | `'TCP'` | Probe protocol: `'TCP'` \| `'UDP'` \| `'ICMP'` \| `'SCTP'` |
121+
| `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'` |
122+
| `ipFamily` | `string` | ❌ | `'IPv4'` | IP family: `'IPv4'` \| `'IPv6'` |
123+
| `maxHops` | `number` | ❌ | `30` | Maximum hops to probe (1–64) |
124+
| `maxUnknownHops` | `number` | ❌ | `15` | Maximum consecutive unresponsive hops before stopping (1–30) |
125+
| `ptrLookup` | `boolean` | ❌ | `true` | Perform reverse-DNS (PTR) lookups on hop IPs |
126+
| `timeout` | `number` | ❌ | `10` | Seconds to wait for the trace to complete (1–30) |
127+
| `assertions` | `TracerouteAssertion[]` | ❌ | `[]` | Response assertions using `TracerouteAssertionBuilder` |
128+
129+
</ResponseField>
130+
131+
<ResponseField name="degradedResponseTime" type="number" default="10000">
132+
Final-hop average RTT in milliseconds at which the monitor is marked as degraded (warning state). Maximum: 30,000.
133+
134+
**Usage:**
135+
136+
```ts highlight={3}
137+
new TracerouteMonitor("traceroute-latency-tiers", {
138+
name: "API Network Path",
139+
degradedResponseTime: 5000, // Warn when final-hop avg RTT exceeds 5 seconds
140+
request: {
141+
url: 'api.example.com',
142+
},
143+
})
144+
```
145+
</ResponseField>
146+
147+
<ResponseField name="maxResponseTime" type="number" default="20000">
148+
Final-hop average RTT in milliseconds at which the monitor is marked as failed. Maximum: 30,000.
149+
150+
**Usage:**
151+
152+
```ts highlight={3}
153+
new TracerouteMonitor("traceroute-latency-tiers", {
154+
name: "API Network Path",
155+
maxResponseTime: 15000, // Fail when final-hop avg RTT exceeds 15 seconds
156+
request: {
157+
url: 'api.example.com',
158+
},
159+
})
160+
```
161+
</ResponseField>
162+
163+
### `TracerouteMonitor` Assertions
164+
165+
Assertions for Traceroute monitors are defined using the `TracerouteAssertionBuilder`. The following sources are available:
166+
167+
- `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`
168+
- `hopCount()`: Assert against the total number of hops recorded in the trace
169+
- `packetLoss()`: Assert against the packet loss percentage at the last recorded hop (0–100)
170+
171+
Here are some examples:
172+
173+
- Assert that the average final-hop latency is below a threshold (default property is `avg`):
174+
175+
```ts
176+
TracerouteAssertionBuilder.responseTime().lessThan(100)
177+
// Equivalent to:
178+
{ source: 'RESPONSE_TIME', property: 'avg', comparison: 'LESS_THAN', target: '100' }
179+
```
180+
181+
- Assert against a specific RTT property:
182+
183+
```ts
184+
TracerouteAssertionBuilder.responseTime('max').lessThan(200)
185+
// Equivalent to:
186+
{ source: 'RESPONSE_TIME', property: 'max', comparison: 'LESS_THAN', target: '200' }
187+
```
188+
189+
- Assert on the number of hops:
190+
191+
```ts
192+
TracerouteAssertionBuilder.hopCount().lessThan(15)
193+
// Equivalent to:
194+
{ source: 'HOP_COUNT', comparison: 'LESS_THAN', target: '15' }
195+
```
196+
197+
- Assert on packet loss at the last hop:
198+
199+
```ts
200+
TracerouteAssertionBuilder.packetLoss().lessThan(10)
201+
// Equivalent to:
202+
{ source: 'PACKET_LOSS', comparison: 'LESS_THAN', target: '10' }
203+
```
204+
205+
Learn more in our docs on [Assertions](/detect/assertions).
206+
207+
### General Monitor Options
208+
209+
<ResponseField name="name" type="string" required>
210+
Friendly name for your Traceroute Monitor that will be displayed in the Checkly dashboard and used in notifications.
211+
212+
**Usage:**
213+
214+
```ts highlight={2}
215+
new TracerouteMonitor("my-traceroute", {
216+
name: "API Gateway Network Path",
217+
/* More options ... */
218+
})
219+
```
220+
</ResponseField>
221+
222+
<ResponseField name="frequency" type="Frequency">
223+
How often the Traceroute Monitor should run. Use the `Frequency` enum to set the check interval.
224+
225+
**Usage:**
226+
227+
```ts highlight={3}
228+
new TracerouteMonitor("my-traceroute", {
229+
name: "API Gateway Network Path",
230+
frequency: Frequency.EVERY_5M,
231+
/* More options ... */
232+
})
233+
```
234+
235+
**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`).
236+
</ResponseField>
237+
238+
<ResponseField name="locations" type="string[]" default="[]">
239+
Array of [public location codes](/concepts/locations/#public-locations) where the Traceroute Monitor should run from. Use `privateLocations` for [private locations](/platform/private-locations/overview). Multiple locations help detect regional routing differences.
240+
241+
**Usage:**
242+
243+
```ts highlight={3}
244+
new TracerouteMonitor("global-path-monitor", {
245+
name: "API Path from Multiple Regions",
246+
locations: ["us-east-1", "eu-central-1", "ap-southeast-1"],
247+
request: {
248+
url: 'api.example.com',
249+
},
250+
})
251+
```
252+
</ResponseField>
253+
254+
<ResponseField name="activated" type="boolean" default="true">
255+
Whether the Traceroute Monitor is enabled and will run according to its schedule.
256+
257+
**Usage:**
258+
259+
```ts highlight={3}
260+
new TracerouteMonitor("my-traceroute", {
261+
name: "API Gateway Network Path",
262+
activated: false, // Disabled monitor
263+
request: {
264+
url: 'api.example.com',
265+
},
266+
})
267+
```
268+
</ResponseField>

‎detect/uptime-monitoring/traceroute-monitors/configuration.mdx‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: 'Traceroute Monitor Configuration'
3+
description: 'Configure your Traceroute monitor to map network paths and detect routing issues, latency, and packet loss.'
4+
sidebarTitle: 'Configuration'
5+
canonical: 'https://www.checklyhq.com/docs/detect/uptime-monitoring/traceroute-monitors/configuration/'
6+
---
7+
8+
<Tip>
9+
To configure a Traceroute monitor using code, learn more about the [Traceroute Monitor Construct](/constructs/traceroute-monitor).
10+
</Tip>
11+
12+
### Basic Setup
13+
14+
Configure your Traceroute monitor by specifying the target host and probe parameters:
15+
16+
* **Hostname or IP address:** The host to trace to (e.g. `api.example.com` or `203.0.113.1`). Do not include a scheme or port in this field
17+
* **IP family:** Choose between IPv4 (default) or IPv6
18+
* **Protocol:** The probe protocol. TCP (default) is the most firewall-friendly option. See the [protocol reference](/detect/uptime-monitoring/traceroute-monitors/overview#probe-protocols) for details on TCP, UDP, ICMP, and SCTP
19+
* **Port:** Destination port for TCP, UDP, and SCTP probes (1–65535). Defaults to `443` for TCP and `33434` for UDP/SCTP. Not applicable for ICMP — the port field is hidden when ICMP is selected
20+
* **Max Hops:** Maximum number of hops to probe before stopping (1–64, default: 30)
21+
* **Max Unknown Hops:** Maximum number of consecutive unresponsive hops to tolerate before cutting the trace short (1–30, default: 15). Many routers silently drop traceroute probes without affecting real traffic, so a reasonable limit prevents traces from halting unnecessarily
22+
* **Timeout:** Maximum time in seconds to wait for the entire trace to complete (1–30, default: 10)
23+
* **Reverse DNS (PTR lookup):** When enabled (default: on), Checkly performs a PTR lookup on each hop IP to resolve it to a hostname. Disable to reduce trace time when hostnames are not needed
24+
25+
### Assertions
26+
27+
Use assertions to validate Traceroute results and alert when paths change or degrade:
28+
29+
You can create assertions based on:
30+
31+
* **Latency:** RTT statistics for the **final responding hop**. Available properties: `avg`, `min`, `max`, `stdDev` (all in milliseconds). This assertion requires the destination to be reached — if `destinationReached` is `false`, `finalHopLatency` is absent and the assertion fails
32+
* **Hop Count:** Total number of hops recorded in the trace. Use this to detect routing changes that add or remove hops from the expected path
33+
* **Packet Loss:** Packet loss percentage at the **last recorded hop** (0–100). A non-zero value indicates that some probe packets were not returned
34+
35+
For more details, see [Assertions](/detect/assertions).
36+
37+
### Response Time Limits
38+
39+
Set performance thresholds based on final-hop latency:
40+
41+
* **Degraded After:** Final-hop avg RTT threshold (in milliseconds) after which the check is marked as degraded but not failed. Default: 3,000 ms. Maximum: 30,000 ms
42+
* **Failed After:** Final-hop avg RTT threshold after which the check fails completely. Default: 5,000 ms. Maximum: 30,000 ms
43+
44+
<Note>
45+
Response-time thresholds apply to the **final-hop average RTT**, not the total check execution time. If the destination is not reached, the monitor is marked as failed regardless of these thresholds.
46+
</Note>
47+
48+
### JSON Response Schema
49+
50+
The Traceroute response is available as structured JSON. These are the key fields (a few internal bookkeeping fields are omitted here, and fields marked as omitted are absent from the JSON rather than empty):
51+
52+
```json
53+
{
54+
"hostname": "api.example.com", // Target hostname or IP as configured
55+
"resolvedIp": "93.184.216.34", // IP address used for the trace
56+
"port": 443, // Destination port; for ICMP probes this reports the unused fallback 443
57+
"ipFamily": "IPv4", // "IPv4" or "IPv6"
58+
"maxHops": 30, // Configured max hops
59+
"totalHops": 12, // Number of hops actually recorded
60+
"destinationReached": true, // Whether the destination responded
61+
"truncationReason": "destinationReached",// Why the trace stopped:
62+
// "destinationReached" | "maxHops" | "maxUnknownHops" | "timeout"
63+
"probeProtocol": "TCP", // Probe protocol: "TCP" | "UDP" | "ICMP" | "SCTP"
64+
"finalHopLatency": { // RTT stats for the last responding hop (the whole object is omitted when the destination is not reached)
65+
"avg": 12.34,
66+
"min": 11.80,
67+
"max": 13.10,
68+
"stdDev": 0.42
69+
},
70+
"hops": [
71+
{
72+
"hop_number": 1,
73+
"main_ip": "10.0.0.1", // Primary IP observed at this hop
74+
"main_host": "router.isp.net", // Reverse-DNS hostname (omitted when PTR lookup is off or the lookup fails)
75+
"sent": 3, // Probe packets sent to this hop
76+
"received": 3, // Replies received from this hop
77+
"loss_percentage": 0.0, // Packet loss at this hop
78+
"rtt": { // RTT stats (omitted when the hop never replied)
79+
"last_ms": 1.23, // RTT of the most recent probe
80+
"avg_ms": 1.10, // Average RTT across all probes
81+
"best_ms": 0.95, // Minimum RTT
82+
"worst_ms": 1.23, // Maximum RTT
83+
"stddev_ms": 0.12 // Standard deviation
84+
},
85+
"asn": 15169, // Autonomous System Number (omitted when unknown)
86+
"asn_org": "GOOGLE", // AS organization name (omitted when unknown)
87+
"country": "US", // Two-letter country code (omitted when unknown)
88+
"aws_region": "us-east-1", // AWS region — only present when the hop is inside AWS
89+
"aws_service": "EC2" // AWS service — only present when the hop is inside AWS
90+
}
91+
// ... one entry per recorded hop
92+
],
93+
"timestamp": 1720000000 // Unix timestamp of the trace run
94+
}
95+
```
96+
97+
### Frequency
98+
99+
Set how often the monitor runs. Traceroute monitors run at most **once every 30 seconds** (every 30 seconds to 24 hours) — the two sub-30-second frequencies aren't available.
100+
101+
### Scheduling & Locations
102+
103+
* **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/concepts/scheduling)
104+
* **Locations:** Select [public](/concepts/locations/#public-locations) or [private](/platform/private-locations/overview) locations to run the monitor from
105+
106+
### Additional Settings
107+
108+
* **Name:** Give your monitor a clear name to identify it in dashboards and alerts
109+
* **Description:** Add context about what this monitor does and why it matters. Supports markdown, max 500 characters. When a failure occurs, [Rocky AI](/ai/rocky-ai) uses the description to provide more accurate [root cause and user impact analysis](/resolve/ai-root-cause-analysis/overview)
110+
* **Tags:** Use tags to organize monitors across [dashboards](/communicate/dashboards/overview/) and [maintenance windows](/communicate/maintenance-windows/overview)
111+
* **Retries:** Define how failed runs should be retried. See [retry strategies](/communicate/alerts/retries)
112+
* **Alerting:** Configure your [alert settings](/communicate/alerts/configuration), [alert channels](/communicate/alerts/channels), or set up [webhooks](/integrations/alerts/webhooks) for custom integrations

0 commit comments

Comments
 (0)