Skip to content

docs: add Traceroute monitor documentation#428

Merged
danielpaulus merged 6 commits into
mainfrom
docs/traceroute-monitors
Jul 17, 2026
Merged

docs: add Traceroute monitor documentation#428
danielpaulus merged 6 commits into
mainfrom
docs/traceroute-monitors

Conversation

@danielpaulus

@danielpaulus danielpaulus commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds Traceroute monitor documentation — three new pages plus navigation:

  • detect/uptime-monitoring/traceroute-monitors/overview.mdx — what Traceroute monitors do and how they work, probe protocol reference (TCP / UDP / ICMP / SCTP with protocol-dependent default ports and how destination reach is detected per protocol), results breakdown, and troubleshooting accordions (incl. CAP_NET_RAW for self-hosted agents)
  • detect/uptime-monitoring/traceroute-monitors/configuration.mdx — all request fields with defaults/ranges, assertions (Latency / Hop Count / Packet Loss), response-time limits, the JSON response schema, frequency (30s floor, SIM-283), scheduling & locations
  • constructs/traceroute-monitor.mdx — CLI construct reference: TracerouteMonitor, TracerouteRequest, and TracerouteAssertionBuilder with basic + advanced examples and full parameter tables
  • docs.json — nav entries for the Traceroute Monitors group (after ICMP Monitors) and constructs/traceroute-monitor; canonical URLs added and sitemap.xml regenerated

All content is verified against main of the monorepo (go-runner executor, webapp builder & model defaults, public-API schema) and of checkly-cli (construct sources) — including the protocol-dependent port defaults from SIM-311 (443 TCP / 33434 UDP+SCTP) and the responseTime('avg'|'min'|'max'|'stdDev') assertion-builder signature.

Test plan

  • Mintlify renders all three pages; sidebar nav and cross-page links/anchors resolve

Before GA

  • Add screenshots: overview (light/dark), request configuration panel, results detail page

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.
…private locations

Remove incorrect statement that private locations are unsupported;
update the Scheduling & Locations bullet to match ICMP/TCP docs.
@mintlify

mintlify Bot commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
checkly-422f444a 🟢 Ready View Preview Jul 8, 2026, 1:42 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

…back)

- construct port default: document as 443 for all non-ICMP protocols
  (not 443/33434 split); 33434 is only the webapp UI pre-fill, not the
  CLI/API default; recommend explicit port: 33434 for UDP/SCTP
- UDP/SCTP destination detection: broaden from "Port Unreachable only"
  to any ICMP Destination Unreachable from the target (admin-prohibited,
  host-unreachable, etc.); SCTP also detected via ABORT/INIT-ACK
- JSON port field: always present (no omitempty), 0 for ICMP; not omitted
- JSON finalHopLatency: whole object is omitted (omitempty pointer), not
  present with null fields, when destination is not reached
…-283)

Traceroute monitors floor at 30s; EVERY_10S/EVERY_20S are not available.
danielpaulus and others added 2 commits July 17, 2026 13:59
…itemap

Bring the branch up to date with main (it was ~1485 commits behind, predating
the sitemap tooling + frontmatter check), add the required canonical URLs to the
three Traceroute monitor pages, and regenerate sitemap.xml to include them.
Fixes the static-docs-checks failure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013AYwkvoaANQTH5dGStbBj2
@danielpaulus

Copy link
Copy Markdown
Contributor Author

Accuracy fixes after checking the pages against main of the monorepo and checkly-cli (landed in c8b0088, alongside the main-merge/sitemap work):

  • TracerouteAssertionBuilder.responseTime() takes the RTT property as an argumentresponseTime('max').lessThan(200). The previously documented chained form (responseTime().avg().lessThan(50)) doesn't exist and wouldn't compile (packages/cli/src/constructs/traceroute-assertion.ts).
  • Port defaults are protocol-dependent everywhere since SIM-311: 443 for TCP, 33434 for UDP/SCTP in web UI, CLI, and API. Removed the stale note claiming CLI/API default to 443 for all non-ICMP protocols.
  • JSON schema: ICMP responses report the unused fallback port: 443, not 0 (the backend strips the port on input, the runner fills the default). omitempty fields (main_host, rtt, asn, aws_*, finalHopLatency) are absent from the JSON when unset, not empty.
  • SCTP destination detection happens via ICMP Destination Unreachable only — the runner never captures direct SCTP ABORT/INIT-ACK replies (the raw send socket is closed right after the probe; there's no SCTP listener).
  • Minor: TTL-expiry wording (the responding router drops the probe, it doesn't forward it), open-port advice scoped to TCP (UDP/SCTP need a closed port), and a note that CAP_NET_RAW is required for all Traceroute protocols — SCTP is just the case that surfaces an explicit socket error.

@danielpaulus
danielpaulus merged commit 2b0cd4f into main Jul 17, 2026
6 checks passed
@danielpaulus
danielpaulus deleted the docs/traceroute-monitors branch July 17, 2026 13:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant