Troubleshooting

This page starts from what you see and works back to the cause. Each section names the screen to open, what the result means and what to change. Where a rule is described in full elsewhere, the section links to it.

An alert didn't arrive

Open the site, choose Notifications, then View Logs. The log shows every attempt with the notification, the trigger, the status and an error. What you find there decides where to look next.

When there is no row, one of these is usually the reason.

• The notification is disabled, or the switch for that kind of alert is off. Site goes down also controls expiry and slow-response alerts, and Content changes also controls DNS, robots.txt, WHOIS and status-code alerts.
• The failure count hasn't reached the Retry Threshold. The default is 3 failed checks in a row. On a site checked every 5 minutes, that is about 10 minutes after the site first fails.
• The Notification Interval hasn't passed. The default is 10 minutes between two messages from one notification, measured from the last time it sent anything.
• The probe regions contradicted the failure. The site then reads Partial, and OctoPing sends one checker blocked notice instead of a down alert. See the section on a site that blocks the checker below.
• The site is switched off, or the workspace's monitoring is paused. Nothing is checked, so nothing can alert.
• A recovery alert only follows a down alert. A site that failed and recovered before the threshold sends neither.
• The notification was created without the person's address. A member who joins later isn't added to notifications that already exist.

Choose Send Test on the notification to tell a delivery problem from a rule that didn't fire. A test that arrives means the channel works, and the question is about the rule. The rules are on Alert rules.

A site shows Degraded

Degraded means the site answered, and the latest response took longer than the site's Response Time Alert Threshold. It's set under Advanced request settings, and a site with the field empty can never be Degraded.

• Only the latest response counts. The next check that comes in under the threshold clears the status.
• The time measured is the time until the response headers arrive, so the size of the page doesn't matter.
• A Degraded site is up. Its checks succeeded, so it doesn't count as downtime or as an outage.
• A slow-response alert goes to notifications with the Site goes down switch on, at the first slow response and then no more often than the Notification Interval.

If the status flickers, the threshold is probably close to the site's normal time. Look at the response times on the site's detail page and set the threshold above what the site usually does. The statuses are listed on Statuses.

Content alerts that look wrong

Content monitoring is off by default and checks every 30 minutes once it's on. It compares the page's readable text with the last successful snapshot, after removing scripts, styles and navigation and normalizing whitespace. Any difference in that text is a change.

• In our experience, most alerts that look like false positives come from text that's different on every load. Typical sources are a date or a clock, a visitor counter, a rotating banner or promotion, recommended items, and text shown only to some visitors.
• The alert includes a text diff. Read it first. The changed lines usually name the section that varies.
• The first snapshot is the baseline, so a new check never alerts on its first run.
• A response that isn't successful is never compared, so a short outage doesn't produce a change alert.

There's no way yet to tell the check to ignore part of a page. What you can do today:

• Monitor a more stable URL, such as a page that holds the text you care about, instead of one that shows changing items.
• Turn Content Monitoring off on the site if the page can't be made stable. The site's availability, certificate and other checks keep running.
• Put the quiet team on a notification with Content changes off, and keep another notification with it on for the people who want those alerts. That switch also covers DNS, robots.txt, WHOIS and status-code alerts, so the first notification stops sending those too.

The check is described on the Checks reference.

A heartbeat ping returns ok false

A ping that OctoPing refuses still answers with HTTP 200, and the body says what happened. Read the message in the response.

• A job that pings with curl -fsS exits successfully even when ok is false, because curl only fails on an HTTP error. Check for "ok": true in the response if the job should fail on a bad ping. The response has a space after the colon, so match it with grep -q '"ok": *true'.
• A request answered with HTTP 429 means the address sending the pings made too many requests. Many frequent jobs on one host share that limit.
• A heartbeat can read Unhealthy while pings arrive if they come later than its interval plus its grace period. OctoPing evaluates deadlines every minute, so an alert can follow the deadline by up to that long.

The call is described on Heartbeat ping.

The regions disagree

Each vantage point reports its own result, and a difference between them is information. The primary checker decides when a site goes down and recovers, and the probe regions give a second opinion.

Regions report about every 5 minutes, so they can lag a fast primary check by a few minutes. When a failure begins, OctoPing waits up to 10 minutes for the regions to confirm or contradict it, and alerts if they stay silent. See Vantage points and confirmation.

The site blocks the checker

Some sites refuse requests from the addresses OctoPing checks from, usually through a firewall, a bot rule or a country rule. The checker then sees a 403 or 429, or a refused connection, while a visitor and the probe regions load the page.

• If the probe regions reach the site, it reads Partial. It counts as up, a public status page shows it as Operational, and OctoPing sends one informational checker blocked notice for the run instead of a down alert.
• If every vantage point is refused, you get a normal down alert with a failure reason such as Forbidden (HTTP 403) or Too Many Requests (HTTP 429).

There are two ways to clear it.

• Allow the addresses on your firewall. The checker blocked notice lists the addresses to allow when they're known, so use that list.
• Add a header under Custom HTTP Headers in the site's Advanced request settings and write a firewall rule that lets requests with that header through. The primary checker and the probe regions both send it.

A private address is refused

OctoPing checks sites from the public internet, so it doesn't send requests to addresses on private or internal networks. Examples are localhost, 10.x.x.x, 192.168.x.x and a hostname that resolves to one of them.

• When you save a site whose address is refused, the form shows the reason, which names the address and why it isn't allowed. Nothing is created.
• A site that was fine can start failing with the reason Blocked by OctoPing if its DNS now points to a private address, or if it redirects to one. The failure reasons page lists it as the blocked code.
• There's no setting in the app to allow private addresses.

To monitor something inside a private network, make it reachable on a public hostname that you protect with a firewall rule or HTTP Basic Authentication. For a job or a service that can't be reached from outside, use a heartbeat so the job reports to OctoPing, and you don't need to open a port. The reasons are listed on Failure reasons.