Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
A transaction monitor drives a real headless Chromium through a list of steps you write: open a page, type into a field, click a button, wait for something, check that the result says what it should. The check passes only if every step passes. It is the only monitor in PingZen that sees your site the way a browser does — and the most expensive one you can run, which is why the second half of this page is about cost.
What It Is For
Login, and anything behind it
The sign-in page returning 200 is not the same thing as a user being able to sign in. A transaction monitor types the credentials, presses the button and validates that the URL or the page content proves the session started. A broken session store, an expired OAuth secret or a redirect loop shows up here and nowhere else.
A multi-step flow where only step four is broken
Checkout, booking, sign-up, a support form. Every page in the flow answers 200 on its own, and the flow is still dead because one button stopped submitting. The monitor records how many steps passed before it stopped, so the alert names the step instead of the site.
Pages that only exist after JavaScript runs
A single-page app ships an empty shell and fills it in from the client. A keyword check on the raw HTML sees nothing to match; the browser sees the rendered page. Use a validate step on an element that only appears once the app has actually loaded its data.
The click-through you do by hand after every release
If there is a five-minute manual smoke test somebody performs after each deploy, that test is a transaction monitor. Write it once, and it runs whether or not anyone remembered — including at three in the morning, when the deploy was automatic.
What It Is Not For
A browser is slow, expensive and limited to one flow at a time. Most questions have a cheaper answer:
| You want to know | Use instead |
|---|---|
| Is the page up right now? A transaction runs every 5 minutes at best and takes a browser launch to answer | HTTP / HTTPS monitor — every 60 seconds, and it can check a keyword in the response too |
| How fast is the page, and what are the Core Web Vitals? | PageSpeed monitor. A transaction measures its own wall-clock time, which includes the browser start-up and tells you nothing about the page |
| Does a sequence of API calls still work — token, then create, then read back? | API check monitor. Same idea without a browser: assertions on status, body and headers, and variables carried between steps |
| Is the certificate about to expire? A transaction over HTTPS says nothing about the expiry date | TLS/SSL certificate monitor |
| Is the server or the port reachable at all? | Ping monitor or a TCP monitor |
| Did a scheduled job or a device stop reporting? | Heartbeat monitor, which the job calls itself |
| Anything a browser is overkill for — one URL, one status code, one string | An HTTP monitor. Keep the transaction for the flow that only a browser can walk |
What One Check Does
- Waits for a free browser slot. Only two Chromium instances run at a time in one server process, so a busy moment can add real seconds here.
- Launches a headless Chromium, opens a fresh browser context and a blank page. Nothing is shared with the previous check: no cookies, no local storage, no logged-in session.
- Runs your steps in order. Every failure stops the run immediately — the steps after the broken one are not attempted.
- Takes a screenshot if a step failed and screenshot-on-error is on.
- Closes the context and the browser, and reports the total wall-clock time as the response time.
The monitor’s own URL field is not visited. The browser starts on a blank page, so the first step must be a navigate step — otherwise your selectors run against nothing.
Each step gets a slice of the monitor timeout: the timeout divided by the number of steps, but never less than 5 seconds. With the default 60-second timeout and three steps, each step has 20 seconds; with twenty steps, each still gets the 5-second floor, which is why long transactions can outlive their own timeout (see the status table below).
Step Actions
| Action | What it does |
|---|---|
navigate | Opens a URL and waits for the DOM to be ready — not for every image and background request to finish. The URL must be http or https and must not point at a private or internal address; a blocked URL fails the step |
click, dblclick | Clicks the element matched by your selector, waiting for it to become clickable within the step budget |
type | Sets the value of an input. It replaces what is there rather than appending, so you do not need to clear the field first |
clear | Empties an input |
select | Picks an option in a <select> element by value |
hover | Moves the pointer over an element — for menus that only open on hover |
press | Sends a key to the page, such as Enter or Escape |
wait | Either waits for a selector to appear, or sleeps for a fixed number of milliseconds (100 to 30 000 in the form). Prefer waiting for the element: a fixed sleep is either too short on a bad day or wasted time on a good one |
scroll | Scrolls an element into view, or to a vertical position, or — with nothing set — to the bottom of the page, which is how you trigger lazy loading |
screenshot | Captures the page. See the note on screenshots below before you rely on this |
validate | The step that actually makes the check mean something — see the next table |
A step can carry a name. If you leave it empty, failures are reported as “Step 3: click”, which is readable but not as good as “Submit the order”.
Selectors are CSS selectors. Pick something stable — a data-testid, an id, a form name. A selector built out of generated class names will break on the next front-end build and page you at night about a design change.
Validations
Navigation and clicks prove the page did not crash. Validation steps prove it did the right thing. A transaction without a single validate step passes as long as nothing throws — which includes the case where the login failed and the app quietly returned you to the login page.
| Validation | Passes when |
|---|---|
url_contains, url_equals | The current address contains, or exactly equals, your text. The usual proof that a login landed on /dashboard |
title_contains, title_equals | The page title contains, or exactly equals, your text |
element_exists | An element matching the selector is in the DOM, visible or not |
element_visible | The element exists and is actually visible on screen |
element_text_contains, element_text_equals | The element's text contains your text, or matches it exactly after trimming spaces. Matching is case-sensitive |
no_console_errors | Always. This one is not implemented yet — it is accepted and does nothing. Console errors are collected during the run, but they never fail a check |
A validation looks up its element straight away instead of waiting for it. If the element appears a moment after the click that produces it, put a wait step in front of the validation.
Status Logic
A transaction monitor has no degraded state. Every step passed, or the check is a failure.
| Result | Status |
|---|---|
| Every step ran and every validation held | UP |
| A step failed — element missing, validation false, navigation blocked. Recorded as "Step failed: name — reason" | DOWN |
| A step used up its slice of the timeout. Recorded as "Step timeout: name" | DOWN |
| The browser could not start or died mid-run. Recorded as "Browser error: …" | DOWN |
| The monitor has no steps at all — "No transaction steps configured" | DOWN |
| The whole run — browser slot, launch, every step — took longer than the timeout plus 5 seconds, or longer than the hard ceiling of 120 seconds | TIMEOUT |
Both DOWN and TIMEOUT count as downtime and both open an incident after the confirmation threshold — three consecutive failing checks by default. At the 5-minute minimum interval that is about 10 minutes from the first failing run to the alert, and up to 15 from the moment the flow actually broke. If that is too slow for this flow, lower the threshold to 1 or 2 and accept that a flaky selector will page you.
A step that timed out is filed under “timeout” in the failure breakdown even though the status is DOWN, so a monitor that keeps hitting its step budget is easy to spot in the failure chart.
What a Failure Reports
When a step breaks, the check records the index and name of the failing step, how many steps passed before it, and up to ten browser console errors. The message stored with the check — the one you see in the history and in the alert — is the “Step failed” or “Step timeout” line, which names the step. The step counters and the console errors are collected on every run but are not kept in the check history; today they exist only inside the failing check itself.
About screenshots. With screenshot-on-error enabled (the default), a full-page PNG is written when a step fails. It lands in a temporary directory on the server that ran the check, which nothing in the product exposes: there is currently no way to open that image from the PingZen interface or the API. The same is true of the screenshot step action. Treat both as not-yet-finished features rather than as evidence you can go and look at, and make your alert readable from the step name alone.
The Cost of a Real Browser
Every other monitor sends a request. This one starts a browser, which is roughly a quarter of a gigabyte of memory and several seconds of start-up before your first step runs. PingZen enforces that cost in the product:
| Limit | Value |
|---|---|
| Minimum check interval | 300 seconds (5 minutes). A lower value is raised to 300 when the monitor is saved from the form or the REST API. This matches what other synthetic-browser products do |
| Minimum timeout | 60 seconds, raised the same way. The maximum is 120 seconds |
| Steps per monitor | 50 |
| Browsers at once | Two per server process. Further checks queue, and the wait counts against their own timeout |
Practical consequences worth planning around:
- A transaction monitor consumes a monitor slot in your plan like any other, but it costs far more to run. One well-chosen flow beats five overlapping ones.
- Do not put every page of the funnel in its own monitor. One transaction that walks the whole funnel gives the same coverage for one browser launch.
- Keep the step count honest. The step budget is the timeout split across the steps with a 5-second floor, so twenty steps of five seconds can run for a hundred seconds — past the point where the run is killed and recorded as a timeout. Under about ten steps is a comfortable place to be.
- Where it runs. The check normally runs on PingZen’s central server. A probe can only run it if that probe was built with a browser, so most locations do not offer transactions at all — the location picker shows only the ones that do.
Configuration
Steps
The list you build in the step editor: drag to reorder, pick an action, fill in the fields that action needs. Up to 50. Start with a navigate step and end with a validate step.
Viewport
1920 × 1080 by default. Width can be 320 to 3840, height 240 to 2160. Set a phone-sized viewport when the flow you care about is the mobile one — a responsive layout can hide the button your selector expects.
User agent
Empty by default, which means the browser sends its own. Set your own string (up to 500 characters) when the site treats the default as a bot, or when you want your monitoring traffic to be identifiable in your logs.
Screenshot on error
On by default. It captures a full-page PNG when a step fails — see the note above about where that file goes and why you should not depend on it yet.
Interval and timeout
300 seconds and 60 seconds are the floors, and the form will not let you go below them. Raise the timeout when the flow is genuinely long; every step's budget grows with it.
Viewport, user agent and screenshot-on-error live behind the “advanced options” toggle under the step editor.
Gaps to Know About
Honest notes on where the feature is not finished, so you do not spend an evening debugging them:
- The Scroll X box in the step editor is ignored. A scroll step uses the Y position only; setting X alone scrolls to the bottom of the page instead.
no_console_errorsvalidation does nothing. Console errors are captured but never fail a check.- A scroll to a selector that does not exist passes silently. It is not a way to assert an element is present — use
element_existsfor that. - Waiting for a URL to change is supported by the checker but has no field in the step editor; it is only reachable through the REST API. In the form, wait for a selector instead.
- A per-step timeout can be set through the API with
timeout_ms(milliseconds). Thetimeoutfield the API also accepts is not read by the checker — a value there is silently ignored. - Screenshots cannot be viewed from the interface, as described above.
Key Features
- A real headless Chromium walks your flow, so JavaScript, redirects and client-side rendering all behave as they do for a user
- Twelve step actions and nine validation types, built in a drag-and-drop editor rather than a script
- Every run starts from a clean browser — no leftover cookies or sessions between checks
- Failures name the step that broke, and count how many steps passed before it
- Navigation is restricted to public HTTP and HTTPS addresses, so a monitor cannot be pointed at internal infrastructure
- Interval and timeout floors are enforced for you, so a browser check cannot be scheduled like an HTTP ping
Common Questions
What protocols can I monitor?
PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, TLS/SSL certificates, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check, and Transaction. You can monitor websites, APIs, servers, databases, and any network service.
How fast can I get alerts?
Telegram alerts are delivered within 1-2 seconds of detection. Slack and Discord notifications arrive almost instantly. You can configure multiple alert channels for redundancy.
Can I organize monitors by project?
Yes! PingZen supports workspaces, which let you organize monitors by project, environment, or team. Each workspace can have its own alert configurations and team members.
Is there an API for automation?
Absolutely. PingZen provides a full REST API with OpenAPI documentation. You can create, update, and delete monitors programmatically.
How do status pages work?
Status pages are public, branded pages showing your services' uptime. You can display real-time status and allow customers to subscribe for updates.
What happens if I reach my monitor limit?
We'll notify you when approaching your limit. You can pause some monitors or contact us for increased capacity. We never stop monitoring without warning, ensuring your critical services stay protected.
Ready to stop missing downtime?
Join thousands of teams who trust PingZen. Setup takes 30 seconds.