Synthetic Monitors for Application Endpoints

A Cloud Monitoring synthetic monitor (opens in a new tab) is a proactive probe that simulates user or client behavior against application endpoints and workflows. The synthetic monitor runs as code on a schedule from global locations and validates availability, functionality, and performance before real users are affected. The same scheduled check can therefore detect regional failure, broken navigation, and degraded API contracts across distributed endpoints.

1.1Generic HTTP Validations for Endpoints and APIs

A generic HTTP validation is a Mocha test that sends a real HTTP request to a URL and asserts on the response. The generic HTTP validation depends on Node.js dependencies declared in package.json and loaded with require, such as node-fetch for sending requests, chai for assertions, and clients such as @google-cloud/secret-manager, @google-cloud/spanner, or Supertest for secrets, data, or richer API validation. At runtime, traffic flows from the Mocha it block to the target URL through fetch, then to an assertion such as expect(externalRes.ok).to.be.true, so a non-successful status fails the monitor.

1.2Broken-Link Checkers for Multi-Page User Journeys

A broken-link checker is a browser-based synthetic monitor that starts at an origin_uri and validates the links a user could follow. The broken-link checker is implemented with the Cloud Functions Framework and the Synthetics SDK for Broken Links by calling runBrokenLinksHandler(options) inside functions.http('BrokenLinkChecker', ...), so incoming scheduler requests flow to the handler, then to the origin page, then to each discovered link. Link discovery depends on browser rendering, so the broken-link checker depends on Puppeteer and requires its specific setup steps to launch correctly.

The behavior of the broken-link checker is controlled entirely through its options object. The options object defines the starting point, scope, selection logic, timing, and failure evidence for the crawl:

• origin_uri is the starting URI to test and crawl for links.
• link_limit controls how many links are tested in one run.
• query_selector_all selects which elements contain links, for example a, and get_attributes selects which attributes to read, for example href.
• link_order selects FIRST_N or RANDOM to test the first links in order or sample randomly.
• link_timeout_millis sets the timeout per link, and max_retries sets retries per failed link.
• wait_for_selector waits for a selector before extracting links from a dynamically rendered page.
• per_link_options overrides expectations for specific URLs, such as custom expected_status_code values or per-link timeouts.
• total_synthetic_timeout_millis sets the timeout for the entire synthetic monitor run.
• screenshot_options controls failure capture, such as capturing on FAILING and where to store the image.

1.3Execution Constraints, Overrides, and Failure Evidence

Execution constraints for synthetic monitors define how much time, memory, and tolerance a probe has before it is marked failed. A Puppeteer-based broken-link checker needs more resources than a single fetch call, and the default memory, CPU, and security settings might not be sufficient, so set memory to at least 1GiB for reliable browser execution. Timeouts operate at two levels: link_timeout_millis bounds each link probe, while total_synthetic_timeout_millis, for example 60000 milliseconds, bounds the whole run, so one slow page cannot consume the entire schedule. Retries with max_retries separate transient network slowness from persistent breakage, but retries increase run time and must fit inside the total timeout.

Per-link overrides handle the nuance that not every non-200 response is a failure. The per_link_options map keys a specific URL to its own expectation, such as expected_status_code: "STATUS_CLASS_4XX", expected_status_code: 304, or expected_status_code: "STATUS_CLASS_3XX", plus an optional link_timeout_millis for known-slow targets. This structure lets the monitor enforce strict success for normal navigation while explicitly allowing redirects, not-modified responses, or expected client errors on selected links. Screenshot capture on FAILING preserves visual evidence from the browser at failure time, which connects the failed assertion back to the rendered state the user would have seen.

A synthetic monitor probe (opens in a new tab) is code that proactively simulates a user request against an application endpoint and decides pass or fail on every run. The synthetic monitor probe runs as an HTTP Cloud Function that fetches a target URL, evaluates assertions on the response, and emits results to observability and alerting pipelines. This design lets teams catch broken functionality, slow responses, and outages before real users encounter them.

2.1Configuring Synthetic Probes

A synthetic probe defines where to send traffic and how broadly to crawl. A generic Mocha probe uses fetch(url) to ping a single website URL, while a broken-link checker starts from an origin_uri and follows links found on that page. The broken-link checker is invoked through functions.http('BrokenLinkChecker', runBrokenLinksHandler(options)), so the options object controls the entire probe and the handler executes it.

The broken-link checker probe depends on the @google-cloud/synthetics-sdk-broken-links package and, when browser rendering is needed, on Puppeteer with its required setup. Probes that use Puppeteer need at least 1GiB of allocated memory because the default memory, CPU, and security settings might not be sufficient. Once deployed, the probe crawls links according to its configured options:

• origin_uri is the starting page where link discovery begins.
• link_limit controls how many links the probe will test.
• query_selector_all and get_attributes control which page elements and attributes supply links, such as a and href.
• link_order selects FIRST_N or RANDOM discovery order.
• link_timeout_millis sets the timeout per link, for example 30000.
• max_retries sets the number of retries per link after any failure.
• wait_for_selector waits for a page selector before extracting links.
• per_link_options overrides expectations for individual URLs.
• total_synthetic_timeout_millis sets the timeout for the entire monitor run, for example 60000.
• screenshot_options controls screenshot capture, such as capture on FAILING to a storage location.

2.2Implementing Assertions for Response and Performance

Assertions in a synthetic monitor are the checks that turn an HTTP response into a pass or fail verdict. The generic Mocha template asserts availability with expect(externalRes.ok).to.be.true, which fails the check when the fetch response is not successful. The broken-link checker asserts the same idea per discovered link through expected_status_code, which can be a specific code such as 304 or a class such as STATUS_CLASS_3XX or STATUS_CLASS_4XX.

Latency assertions in the broken-link checker come from two timeout boundaries that work together. The link_timeout_millis value applies to each individual link request, while total_synthetic_timeout_millis applies to the whole synthetic monitor execution from origin page load through the last link check. Traffic flows from the origin page to each extracted link in link_order, each link check is evaluated against its own expected_status_code and link_timeout_millis, and per_link_options lets one URL expect a redirect while another allows extra time. This structure supports nuanced rules such as allowing a known redirect to return STATUS_CLASS_3XX while still failing truly broken links.

2.3Integrating Alerting and Incident Response

An alerting policy in observability converts failed probes and degraded performance into notifications and follow-up work. The alerting policy evaluates thresholds, events, or anomalies from collected logs and metrics and then triggers notifications through various channels when conditions are met. The synthetic monitor therefore depends on the alerting policy: the probe produces pass, fail, and latency signals, and the policy decides when those signals warrant human attention.

Troubleshooting and remediation close the loop from alert back to a healthy endpoint. Collected logs and metrics are used to investigate and diagnose the issue behind a failed assertion, enabling resolution and minimizing downtime. Effective alerting logic provides enhanced visibility into health and performance, mitigates issues before they impact operations through real-time monitoring, streamlines troubleshooting with centralized logs and detailed metrics, and improves operational efficiency by reducing downtime.

Analyzing results and optimizing for reliability and cost is the practice of turning synthetic probe data into decisions about application health and monitoring spend. Synthetic monitors proactively validate functionality, performance, and availability by simulating user interactions across distributed endpoints. Their latency distributions, success rates, and error patterns become performance metrics that must be interpreted, correlated, and tuned over time.

3.1Interpret Latency, Success Rate, and Error Patterns

Interpreting synthetic monitor results means reading latency, success, and error signals together in Cloud Monitoring rather than reacting to a single failed probe. Latency distributions show how response times spread across regions and time windows, success rates show the proportion of probes that complete workflows as expected, and error patterns show whether failures cluster by endpoint, step, geography, or time. Cloud Monitoring supports this interpretation in four related ways:

• Analyze trends in performance metrics to separate gradual degradation from sudden breakage
• Analyze the effects of experiments to see whether a change improved or regressed probe results
• Define alerts for critical metrics so sustained shifts in latency or success trigger response
• Perform retrospective analyses to review past incidents and validate whether fixes held

Trend and retrospective views matter because synthetic results are noisy by nature. A single slow probe may reflect transient network variation, while a widening latency distribution or a falling success rate across many probes points to a real breakpoint in scaling or capacity.

3.2Correlate Synthetic Results with Other Telemetry to Diagnose Causes

Correlation means comparing synthetic monitor failures against other performance metrics to locate the root cause. A synthetic probe reports what an emulated user experienced at an endpoint or workflow step, while backend metrics show CPU, memory, request queues, database latency, and downstream dependency behavior during the same window. When synthetic latency rises at the same time backend saturation rises, the cause likely sits inside the application or its allocated resources, and when synthetic probes fail while backend health looks normal, the cause likely sits in routing, load balancing, authentication, or an external dependency.

Load testing strengthens this diagnosis by revealing potential breakpoints and showing how the application scales under stress. If synthetic error patterns under normal traffic match the failure modes seen during a load test, the team has evidence that capacity limits, not application logic, explain the probe failures. Defining alerts for critical metrics then connects diagnosis to response, so the same correlated signals that explain an incident will trigger the next alert before users are broadly affected.

3.3Optimize Monitor Configuration for Reliability and Cost

Optimizing synthetic monitoring means adjusting probe coverage, frequency, and resource allocation (opens in a new tab) to balance detection sensitivity against operational cost and external dependency impact. More frequent probes from more locations detect outages faster, but each probe consumes monitoring quota, generates telemetry to store and analyze, and places additional load on the application and any third-party APIs in the workflow. Reducing frequency or narrowing coverage lowers cost and dependency pressure, but increases the risk that short outages or region-specific failures go undetected.

Active Assist is a set of tools that provides insights and recommendations to help optimize resource utilization. These recommendations help teams adjust resource allocation and improve performance, for example by rightsizing overprovisioned services that synthetic monitors show as consistently fast or by adding capacity where synthetic latency distributions show sustained degradation. Used with retrospective analysis, Active Assist turns synthetic history into a tuning loop: keep sensitive, frequent probing where success rates and latency directly protect revenue or availability, and relax probing where stability is proven and cost or external load outweighs faster detection.

Key Facts

• A Cloud Monitoring synthetic monitor runs as scheduled code from global locations to simulate user journeys and validate availability, functionality, and performance.
• A generic Mocha validation uses fetch and assertions such as expect(externalRes.ok).to.be.true, while a broken-link checker uses runBrokenLinksHandler(options) with Puppeteer and requires at least 1GiB of memory.
• Link_timeout_millis bounds each individual link probe, while total_synthetic_timeout_millis bounds the entire synthetic monitor run.
• Per_link_options maps a specific URL to its own expected_status_code, such as 304, STATUS_CLASS_3XX, or STATUS_CLASS_4XX, so expected redirects or client errors do not fail the run.