Getting Started with New Relic Synthetics: Best Practices That Set You Up for Success

This post is adapted from a series of best practice guides that reflect the New Relic Community Team’s work with thousands of customers—identifying challenges and coming up with actionable solutions for organizations getting started with New Relic Synthetics. Also, check out our guides to getting started with New Relic APM, New Relic Infrastructure, New Relic Mobile, New Relic Insights, and New Relic Browser; and discover the New Relic Community Team’s latest Best Practice Guide offerings.

New Relic Synthetics puts a set of very powerful and important application monitoring and troubleshooting capabilities at your team's fingertips. Synthetics enables you to simulate real user flows and behavior—at any frequency you choose, from locations around the world. Automated, scriptable tools let you analyze app performance and identify and solve problems across all your digital touchpoints—often before they impact your actual users.

Every day, the New Relic Community Team hears from customers with questions about how to get the greatest value from New Relic Synthetics. This guide presents our most popular and useful answers: insider tips and best practices with special value for organizations just starting their journey with Synthetics.

(If you’re completely new to the New Relic technology landscape, we suggest starting with this primer and series of short videos that give New Relic newbies a quick but thorough introduction to our family of applications, the technology that powers them, and their place in modern software development.)

New Relic Synthetics organizational tips

Set up a naming convention for your synthetic monitors

When you're in a race against time to troubleshoot a business-critical app, the last thing you want to do is waste time hunting for the right monitor—or finding the wrong one—to get the data you need. This can be an especially common problem when dealing with multiple monitors targeting the same service. For example, a ping check that tests availability once a minute and a scripted browser monitor that tests a full user workflow are obviously very different tools, yet it can be difficult to quickly tell them apart when both monitors target the same production services.

A naming convention based on clear and consistent guidelines is a great way to solve this problem. For example, a naming convention based on the following characteristics:

Type - Service - Env

… yields a unique and descriptive name such as:

Ping - Webstore - Production

To rename a monitor and to review naming rules (such as allowable characters)—and to access other vital configuration settings—refer to the New Relic Synthetics Monitor settings overview.

Set appropriate permissions for your monitors

The Synthetics permission system is optional; by default, all users have full access to all monitors. This isn't ideal in all situations; some Synthetics scripts, for example, are likely to contain sensitive and/or regulated information. In general, the more monitors and/or users your organization manages, the more important it is to use permissions to maintain control over who can access and edit your Synthetics resources.

Permissions in Synthetics are based on user groups. When activated, if a user group doesn't have view or edit access to a given entity, then members of that group will not be able to access that entity at all. Group-based user permissions are versatile enough to address almost any set of secure access requirements you choose to apply to your Synthetics monitors, locations, and other entities.

Learn more about how to activate the Synthetics permissions system here. Since Synthetics does not include user groups by default, you'll also need to know how to create and delete user groups for your permissions system; and how to assign and manage each group's permissions.

Monitor management via the API

If you need to manage a large number of monitors, it can be much easier and more efficient to automate the process of adding, removing, and updating monitors. New Relic Synthetics includes a REST API to handle these tasks programmatically—for example, by automating the creation and management of ping, simple browser, scripted browser, and API test monitors. You can also use the API to update your scripts and see available locations.

Learn more about managing Synthetics monitors via the REST API, including a review of the monitor types in API and details on how to perform tasks programmatically using the API.

Add secure credentials to your scripts

For New Relic Synthetics to simulate real user flows across your apps and other digital assets, it is often necessary to store user authentication records and other sensitive data within Scripted Browsers and other scripted monitoring tools deployed across your Synthetics environment. With this level of access, however, comes a responsibility to ensure that sensitive data entrusted to Synthetics stays secure—and that our monitoring, analysis, and automation tools always maintain the highest data-security standards.

Synthetics secure credentials is the feature that helps us comply with the strictest data security standards. Secure credentials uses key-value pairs and strong encryption to keep your data safe, while also making it much easier add and change sensitive data across dozens or even hundreds of Synthetics scripts.

The first step to benefiting from Synthetics secure credentials is to enable the Synthetics group-based permissions system (see "Set appropriate permissions" above). To learn more about how Synthetics secure credentials protects your data and how to use it, begin with this New Relic blog post. Then review the New Relic technical documentation for a deep dive into secure credentials, including requirements, best practices, script update guidelines, and more.

Understanding your New Relic Synthetics data

Interpret your Synthetics failures

When a Synthetics monitor fails, it returns an error code that indicates—often in considerable detail—the nature of the failure. It's useful to build a working familiarity with commonly encountered error codes, which can speed troubleshooting and diagnosis.

It's useful to begin with a working knowledge of standard HTTP response codes. Then refer to this guide to Synthetics response codes for a more detailed and useful understanding of the behavior of your monitors. It's also helpful to learn more about troubleshooting monitor failures in Synthetics, since even "isolated" monitor failures may indicate a recurring and potentially significant problem.

Interpreting your scripts

Scripts can comprise anywhere from 10 to 1,000 or more lines, so it's useful to understand how to read and troubleshoot them in order to diagnose and respond to scripted monitor failures. You can set yourself up for success by making liberal use of comments within your scripts—making it easier to understand at a glance what a scripted function is doing even if you can't always parse the script yourself.

Log messages can be another useful source of information when investigating a monitor failure. Looking at the script log will, for example, show you how far your script got before failing—giving you a clear pointer to the likely problem areas.

The New Relic Synthetics documentation includes a brief and useful overview of how to manually log monitor results to the script log, and to use logging to troubleshoot a script.

Using New Relic Synthetics to make your data actionable

Insights queries for Synthetics

There are 3 default event types sent to New Relic Insights from Synthetics: SyntheticCheck, SyntheticRequest, and SyntheticPrivateMinion. Each event type comes with several helpful attributes, summarized below. We suggest trying out these queries yourself—the results will give you a deeper understanding of your Synthetics requests.

Synthetics events and attributes

Non-200 requests, faceted by domain:

SELECT count(*) FROM SyntheticRequest SINCE yesterday where responseCode !=200 FACET domain limit 100

Synthetics Failures faceted by location:

SELECT count(*) FROM SyntheticCheck WHERE result != 'SUCCESS' SINCE this week FACET locationLabel LIMIT 100

Synthetics Failures faceted by individual monitor:

SELECT count(*) FROM SyntheticCheck WHERE result != 'SUCCESS' SINCE this week FACET monitorName LIMIT 100 timeseries auto

Average durations per network type (DNS/Connect/SSL/etc…) faceted by location:

SELECT average(durationDNS) as 'DNS', average(durationSSL) as 'SSL', average(durationConnect) as 'Connect' , average(durationSend) as 'Send', average(durationWait) as 'Wait', average(durationBlocked) as 'Blocked', average(durationReceive) as 'Receive', average(duration) as 'Duration' FROM SyntheticRequest SINCE yesterday FACET locationLabel

Learn more about the Synthetics default events for Insights here.

Synthetics custom alerts using NRQL

By default, Synthetics alerts will notify you of a monitor failure, and notify you again when that monitor recovers. By using NRQL alerts, you can also set up alternate alert configurations, such as getting alerts for the number of failing locations over time or getting alerts only when multiple monitors fail in a set period. In fact, NRQL can let you toset up alerts on any returned numeric value.

Refer to our level-up post to learn more about setting up, managing, and using NRQL alerts.

Ready to learn more?

Looking for more New Relic Synthetics best practices and tips? Check out the Synthetics Level Up Category pages in the New Relic Explorers Hub to discover a wealth of community-generated resources on these and related topics. When you’re ready, test your knowledge by taking our Synthetics Best Practices Quiz and earning your proficiency badge!