Skip to content

Commit 0cceec1

Browse files
danielpaulusdanielpaulus
committed
docs: add Traceroute monitor documentation
Add overview, configuration, and CLI construct docs for Traceroute monitors. Config sourced from the webapp builder, CLI construct, and go-runner executor. Nav entries added to docs.json. Screenshots TODO.
1 parent 5697d29 commit 0cceec1

4 files changed

Lines changed: 495 additions & 0 deletions

File tree

‎constructs/traceroute-monitor.mdx‎

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

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
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+
---
6+
7+
<Tip>
8+
To configure a Traceroute monitor using code, learn more about the [Traceroute Monitor Construct](/constructs/traceroute-monitor).
9+
</Tip>
10+
11+
### Basic Setup
12+
13+
Configure your Traceroute monitor by specifying the target host and probe parameters:
14+
15+
* **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
16+
* **IP family:** Choose between IPv4 (default) or IPv6
17+
* **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
18+
* **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
19+
* **Max Hops:** Maximum number of hops to probe before stopping (1–64, default: 30)
20+
* **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
21+
* **Timeout:** Maximum time in seconds to wait for the entire trace to complete (1–30, default: 10)
22+
* **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
23+
24+
### Assertions
25+
26+
Use assertions to validate Traceroute results and alert when paths change or degrade:
27+
28+
You can create assertions based on:
29+
30+
* **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`, the assertion fails
31+
* **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
32+
* **Packet Loss:** Packet loss percentage at the **last recorded hop** (0–100). A non-zero value indicates that some probe packets were not returned
33+
34+
For more details, see [Assertions](/detect/assertions).
35+
36+
### Response Time Limits
37+
38+
Set performance thresholds based on final-hop latency:
39+
40+
* **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
41+
* **Failed After:** Final-hop avg RTT threshold after which the check fails completely. Default: 5,000 ms. Maximum: 30,000 ms
42+
43+
<Note>
44+
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.
45+
</Note>
46+
47+
### JSON Response Schema
48+
49+
The Traceroute response is available as structured JSON. All responses share this format:
50+
51+
```json
52+
{
53+
"hostname": "api.example.com", // Target hostname or IP as configured
54+
"resolvedIp": "93.184.216.34", // IP address used for the trace
55+
"port": 443, // Destination port (omitted for ICMP)
56+
"ipFamily": "IPv4", // "IPv4" or "IPv6"
57+
"maxHops": 30, // Configured max hops
58+
"totalHops": 12, // Number of hops actually recorded
59+
"destinationReached": true, // Whether the destination responded
60+
"truncationReason": "destinationReached",// Why the trace stopped:
61+
// "destinationReached" | "maxHops" | "maxUnknownHops" | "timeout"
62+
"probeProtocol": "TCP", // Probe protocol: "TCP" | "UDP" | "ICMP" | "SCTP"
63+
"finalHopLatency": { // RTT stats for the last responding hop
64+
"avg": 12.34, // null when destination is not reached
65+
"min": 11.80,
66+
"max": 13.10,
67+
"stdDev": 0.42
68+
},
69+
"hops": [
70+
{
71+
"hop_number": 1,
72+
"main_ip": "10.0.0.1", // Primary IP observed at this hop
73+
"main_host": "router.isp.net", // Reverse-DNS hostname (empty when PTR lookup is off or lookup fails)
74+
"sent": 3, // Probe packets sent to this hop
75+
"received": 3, // Replies received from this hop
76+
"loss_percentage": 0.0, // Packet loss at this hop
77+
"rtt": {
78+
"last_ms": 1.23, // RTT of the most recent probe
79+
"avg_ms": 1.10, // Average RTT across all probes
80+
"best_ms": 0.95, // Minimum RTT
81+
"worst_ms": 1.23, // Maximum RTT
82+
"stddev_ms": 0.12 // Standard deviation
83+
},
84+
"asn": 15169, // Autonomous System Number (0 if unknown)
85+
"asn_org": "GOOGLE", // AS organization name
86+
"country": "US", // Two-letter country code
87+
"aws_region": "", // AWS region name (if hop is in AWS)
88+
"aws_service": "" // AWS service name (if hop is in AWS)
89+
}
90+
// ... one entry per recorded hop
91+
],
92+
"timestamp": 1720000000 // Unix timestamp of the trace run
93+
}
94+
```
95+
96+
### Frequency
97+
98+
Set how often the monitor runs (every 10 seconds to 24 hours).
99+
100+
### Scheduling & Locations
101+
102+
* **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/concepts/scheduling)
103+
* **Locations:** Select [public locations](/concepts/locations/#public-locations) to run the monitor from
104+
105+
### Additional Settings
106+
107+
* **Name:** Give your monitor a clear name to identify it in dashboards and alerts
108+
* **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)
109+
* **Tags:** Use tags to organize monitors across [dashboards](/communicate/dashboards/overview/) and [maintenance windows](/communicate/maintenance-windows/overview)
110+
* **Retries:** Define how failed runs should be retried. See [retry strategies](/communicate/alerts/retries)
111+
* **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)