Skip to content
subcloakdocs
subcloak.comDownload

Debugging tools

Alerts

Get a macOS notification when matching traffic fails, returns a 5xx or a specific status, runs slow, or contains some text. Every trigger, explained.

Alerts watch your traffic while you work on something else. When a matching request fails, returns an error, runs slower than a limit or contains certain text, Cloak Proxy posts a macOS notification. Click it to jump straight to the request. Use alerts to catch the one failing call during a long manual test, or to notice when a staging API starts returning 5xx.

Get notified when a request fails

Section titled “Get notified when a request fails”

  1. Right-click a request in the traffic list and choose Tools › Alerts….

    Cloak Proxy creates a rule named after the request with “fails” added, which matches its method and URL (without the query) and fires on Any error (4xx, 5xx or failure). It turns Alerts on and opens the rule.

  2. If macOS asks whether Cloak Proxy may send notifications, click Allow.

  3. Change the Condition if you want a different trigger.

  4. Keep working. When a matching request meets the condition, a notification appears. Click it to see the request in the main window.

To start from scratch, choose Tools › Edit Alerts Rules… and click +. A new rule is named New Alert and fires on Server error (5xx).

An alert created from a request. Recent lists every time it fired.

  1. When to notify.
  2. Play the default notification sound.
  3. Ask macOS for permission to show notifications.
  4. The last 20 times this rule fired. Click one to see the request.
An Alerts rule named GET api.example.com/v1/users fails, with the condition Any error (4xx, 5xx or failure), Play a sound checked, and an empty Recent section

Conditions

Section titled “Conditions”

Pick a condition under Notify when. Three of them need a value, typed in the field that appears under the menu.

Condition Fires when a matching request Value
Any matching request Finishes, whatever the result.
Server error (5xx) (default) Gets a status code of 500 or higher.
Any error (4xx, 5xx or failure) Gets a status of 400 or higher, or fails without a response.
Connection failure Fails without a response: the server couldn’t be reached, it timed out, a breakpoint aborted it, a script failed, or the Block List or Network Conditions dropped it.
Slower than (ms) Takes longer than the value, from start to finish. Milliseconds, for example 1500. If it isn’t a number, the rule never fires.
Status code is Gets exactly this status code. A status code, for example 401.
Response body contains Gets a response whose body contains the text, ignoring case. The decompressed body is searched, up to its first 2,000,000 bytes. The text to look for. If it’s empty, the rule never fires.

Rule settings

Section titled “Rule settings”
Setting Default What it does
Name and matcher Which requests to watch. See Rules and matching. The name is the notification’s title.
Condition Server error (5xx) See the table above.
Play a sound On Plays the default notification sound with each notification.
Allow Notifications… Asks macOS for permission to show notifications.

Every matching rule fires, not just the first, so one request can trigger several alerts.

Notifications

Section titled “Notifications”

A notification’s title is the rule’s name. Its text is the method, the URL, and the result: the status code (→ 503) or the failure reason, then the duration in milliseconds. For example:

GET https://api.example.com/v1/users → 503 (1240 ms)
  • Grouping: each rule posts at most one notification every 10 seconds. Requests that fire in between are counted, and the next notification adds +N more since the last alert. In Notification Center, a rule’s notifications are grouped together.
  • Click a notification to bring Cloak Proxy forward and select the request in the traffic list.
  • Notifications appear even while Cloak Proxy is the app in front.

Recent alerts and history

Section titled “Recent alerts and history”

The Recent section of a rule lists the last 20 times it fired, newest first, with the time and the notification text. It shows Nothing yet. until the rule fires. Every firing is listed, including those grouped into a later notification. Click an entry to select its request.

All alerts from all rules are also listed in Insights › Alerts. Cloak Proxy keeps the 500 most recent alerts while it’s running.

What alerts check

Section titled “What alerts check”
  • Alerts check a request once, when it finishes (completes or fails).
  • Only recorded requests are checked. Nothing fires while recording is paused, or for requests the Allow List skips.
  • Requests you send with Repeat or Compose are checked like live traffic. Sessions you open or import are not.
  • The matcher is compared with the request as it was finally sent. If Map Remote rewrote the URL, match the new URL.

Example rules

Section titled “Example rules”
Goal Matcher Condition Value
Any payment failure api.example.com/v1/payments/* Server error (5xx)
Expired sessions api.example.com/* Status code is 401
A slow search GET, https://api.example.com/v1/search Slower than (ms) 1500
A feature flag shows up api.example.com/v1/config Response body contains "newCheckout":true
Anything unreachable * Connection failure
Section titled “Related”
Insights: alerts historyEvery alert from every rule in one list.
Failed requests and tunnelsRead why a request failed.
Rules and matchingWildcards, regex and methods.
Headless and CIFail a CI run on 5xx or errors with cloakctl run.