generated from mintlify/starter
-
Notifications
You must be signed in to change notification settings - Fork 6
TREE-337: ICMP Monitor documentation #161
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
sujaya-sys
wants to merge
8
commits into
main
Choose a base branch
from
icmp-monitor-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+529
−37
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
90804cf
initial outline icmp documentation
sujaya-sys 85d0959
Merge branch 'main' into icmp-monitor-docs
sujaya-sys 7a79ecc
added further details to icmp dev docs
sujaya-sys 6f40c14
added CLI reference for icmp
sujaya-sys 9ad6485
minor inconsistencies
sujaya-sys 0b4f3d1
Added results section
sujaya-sys dab9ee7
Update communicate/dashboards/overview.mdx
sujaya-sys f5ac9d2
incorporated feedback on PR
sujaya-sys File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,235 @@ | ||
| --- | ||
| title: 'IcmpMonitor Construct' | ||
| description: 'Learn how to configure ICMP monitors with the Checkly CLI.' | ||
| sidebarTitle: 'ICMP Monitor' | ||
| --- | ||
|
|
||
| import GeneralMonitorOptionsTable from '/snippets/general-monitor-options-table.mdx'; | ||
|
|
||
| <Tip> | ||
| Learn more about ICMP Monitors in [the ICMP monitor overview](/detect/uptime-monitoring/icmp-monitors/overview). | ||
| </Tip> | ||
|
|
||
| ICMP monitors check if a host is reachable by sending ICMP Echo Requests (pings). Use them to monitor network connectivity and latency. | ||
|
|
||
| <Accordion title="Prerequisites"> | ||
| Before creating ICMP Monitors, ensure you have: | ||
|
|
||
| - An initialized Checkly CLI project | ||
| - A hostname or IP address you want to ping | ||
| - Basic understanding of network connectivity (ICMP / ping) | ||
|
|
||
| For additional setup information, see [CLI overview](/cli/overview). | ||
| </Accordion> | ||
|
|
||
| <CodeGroup> | ||
|
|
||
| ```ts Basic Example | ||
| import { Frequency, IcmpMonitor } from "checkly/constructs" | ||
|
|
||
| new IcmpMonitor('icmp-welcome', { | ||
| name: 'Welcome Site Reachability', | ||
| frequency: Frequency.EVERY_1M, | ||
| request: { | ||
| hostname: 'welcome.checklyhq.com', | ||
sujaya-sys marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| }, | ||
| degradedPacketLossThreshold: 20, // percentage | ||
| maxPacketLossThreshold: 30, // percentage | ||
| }) | ||
| ``` | ||
|
|
||
| ```ts Advanced Example | ||
| import { Frequency, IcmpAssertionBuilder, IcmpMonitor } from "checkly/constructs" | ||
|
|
||
| new IcmpMonitor('cloudflare-dns-icmp', { | ||
| name: 'Cloudflare DNS ICMP Monitor', | ||
| activated: true, | ||
| frequency: Frequency.EVERY_1M, | ||
| maxPacketLossThreshold: 20, // percentage | ||
| degradedPacketLossThreshold: 10, | ||
| request: { | ||
| hostname: '1.1.1.1', | ||
| pingCount: 20, | ||
| assertions: [ | ||
| IcmpAssertionBuilder.latency('avg').lessThan(100), | ||
| IcmpAssertionBuilder.latency('max').lessThan(200), | ||
| ] | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| </CodeGroup> | ||
|
|
||
| ## Configuration | ||
|
|
||
| ICMP monitors have their own ICMP-specific settings, plus the standard monitor options shared across all check types. | ||
|
|
||
| <Tabs> | ||
| <Tab title="ICMP Monitor Settings"> | ||
|
|
||
| | Parameter | Type | Required | Default | Description | | ||
| |-----------|------|----------|---------|-------------| | ||
| | `request` | `object` | ✅ | - | ICMP request configuration object | | ||
| | `degradedPacketLossThreshold` | `number` | ❌ | `10` | Packet loss percentage at which the monitor is marked as degraded | | ||
| | `maxPacketLossThreshold` | `number` | ❌ | `20` | Packet loss percentage at which the monitor is marked as failed | | ||
|
|
||
| </Tab> | ||
| <Tab title="General Monitor Settings"> | ||
|
|
||
| <GeneralMonitorOptionsTable /> | ||
|
|
||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| ### `IcmpMonitor` Options | ||
|
|
||
| <ResponseField name="request" type="object" required > | ||
|
|
||
| ICMP request configuration, including ping settings and response validation. | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```ts | ||
| new IcmpMonitor('icmp-monitor', { | ||
| name: 'ICMP Latency Monitor', | ||
| request: { | ||
| hostname: 'api.checklyhq.com', | ||
| pingCount: 15, | ||
| assertions: [ | ||
| IcmpAssertionBuilder.latency('avg').lessThan(100), | ||
| ] | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| **Parameters:** | ||
|
|
||
| | Parameter | Type | Required | Default | Description | | ||
| |-----------|------|----------|---------|-------------| | ||
| | `hostname` | `string` | ✅ | - | The target host (domain name or IP address) | | ||
| | `pingCount` | `number` | ❌ | `10` | Number of ICMP Echo Request packets to send per check run (1-50, default: 10) | | ||
| | `assertions` | `IcmpAssertion[]` | ❌ | `[]` | Response assertions using the `IcmpAssertionBuilder` | | ||
| | `ipFamily` | `string` | ❌ | `IPv4` | IP family selection (IPv4, IPv6) | | ||
|
|
||
| </ResponseField> | ||
|
|
||
| <ResponseField name="degradedPacketLossThreshold" type="number" default="10"> | ||
| Packet loss percentage at which the monitor is marked as degraded (warning state). | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```ts highlight={3} | ||
| new IcmpMonitor("icmp-performance-tiers", { | ||
| name: "ICMP Performance Tiers", | ||
| degradedPacketLossThreshold: 15, // Warn at 15% | ||
| request: { | ||
| hostname: '1.1.1.1', | ||
| pingCount: 20, | ||
| } | ||
| }) | ||
| ``` | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="maxPacketLossThreshold" type="number" default="20"> | ||
| Packet loss percentage at which the monitor is marked as failed | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```ts highlight={3} | ||
| new IcmpMonitor("icmp-performance-tiers", { | ||
| name: "ICMP Performance Tiers", | ||
| maxPacketLossThreshold: 25, // Fail at 25% | ||
| request: { | ||
| hostname: '1.1.1.1', | ||
| pingCount: 20, | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| </ResponseField> | ||
|
|
||
| ### `IcmpMonitor` Assertions | ||
|
|
||
| Assertions for ICMP monitors can be defined using the `IcmpAssertionBuilder`. The following sources are available: | ||
|
|
||
| - `latency(property)`: Validate round-trip time (RTT) for ICMP pings. The property parameter is required and must be one of: `avg`, `min`, `max`, or `stdDev` | ||
| - `jsonResponse(property?)`: Assert against the [JSON response structure](/detect/uptime-monitoring/icmp-monitors/configuration#json-response-schemas). This allows you to target specific fields using JSON path assertions | ||
|
|
||
| Here are some examples: | ||
|
|
||
| - Assert the average latency is below a threshold | ||
|
|
||
| ```ts | ||
| IcmpAssertionBuilder.latency('avg').lessThan(100) | ||
| // Equivalent to: | ||
| { source: 'LATENCY', property: 'avg', comparison: 'LESS_THAN', target: '100' } | ||
| ``` | ||
|
|
||
| - Assert against specific JSON fields in the response | ||
|
|
||
| ```ts | ||
| IcmpAssertionBuilder.jsonResponse('$.packetsReceived').equals(10) | ||
| // Equivalent to: | ||
| { source: 'JSON_RESPONSE', property: '$.packetsReceived', comparison: 'EQUALS', target: '10' } | ||
| ``` | ||
|
|
||
| Learn more in our docs on [Assertions](/detect/assertions). | ||
|
|
||
| ### General Monitor Options | ||
|
|
||
| <ResponseField name="name" type="string" required> | ||
| Friendly name for your ICMP Monitor that will be displayed in the Checkly dashboard and used in notifications. | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```ts highlight={2} | ||
| new IcmpMonitor("my-monitor", { | ||
| name: "ICMP Ping Monitor", | ||
| /* More options ... */ | ||
| }) | ||
| ``` | ||
|
|
||
| </ResponseField> | ||
|
|
||
| <ResponseField name="frequency" type="Frequency"> | ||
| How often the ICMP Monitor should run. Use the `Frequency` enum to set the check interval. | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```ts highlight={3} | ||
| new IcmpMonitor("my-monitor", { | ||
| name: "ICMP Ping Monitor", | ||
| frequency: Frequency.EVERY_1M, | ||
| /* 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` | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="locations" type="string[]" default="[]"> | ||
| Array of [public location codes](/concepts/locations/#public-locations) where the ICMP Monitor should run from. Multiple locations provide geographic coverage and help detect regional network issues. | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```ts highlight={3} | ||
| new IcmpMonitor("global-icmp-monitor", { | ||
| name: "ICMP Ping Monitor", | ||
| locations: ["us-east-1", "eu-central-1", "ap-southeast-1"] | ||
| }) | ||
| ``` | ||
| </ResponseField> | ||
|
|
||
| <ResponseField name="activated" type="boolean" default="true"> | ||
| Whether the ICMP Monitor is enabled and will run according to its schedule. | ||
|
|
||
| **Usage:** | ||
|
|
||
| ```ts highlight={3} | ||
| new IcmpMonitor("my-monitor", { | ||
| name: "ICMP Ping Monitor", | ||
| activated: false // Disabled monitor | ||
| }) | ||
| ``` | ||
|
|
||
| </ResponseField> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.