--- title: Transition guide for switching to newer synthetic monitor runtime source: https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/new-runtime --- If your monitors are on an old runtime, we recommend updating them. The new runtime includes better features, such as improving the backend environment in which your public monitors are running. Making the switch gives you these features: - Access to the [**Latest** Chrome runtime](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/manage-monitor-runtimes/#browserdependencies), so that your scripted browser monitors use browser versions like the ones used by your end users. - Access to the updated [scripted API runtime](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/manage-monitor-runtimes/#apidependencies) that uses `got` node.js library instead of the deprecated `request` library. - Support for [async or await syntax](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/manage-monitor-runtimes/#browserdependencies). This simplifies script creation and maintenance, diverging from the old runtime's `.then` promise chaining. - Better support for [shadow DOM objects](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/synthetic-scripted-browser-reference-monitor-versions-chrome-100/#shadow). - [Custom timing library](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/custom-timing-details) for scripted API monitors. - Access to our [NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-synthetics-tutorial) to automate the management of your synthetic monitors. ## Private location requirements [#private-locations] Using new runtimes on [private locations](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/private-locations/private-locations-overview-monitor-internal-sites-add-new-locations) requires the installation of [synthetics job manager](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/private-locations/install-job-manager). ## Convert your monitors to the new runtime [#runtime-convert] Existing monitors default to the runtime used at their time of creation. We recommend converting your monitors sooner rather than later. This stops them from breaking during future end-of-life processes. The [runtime upgrades UI](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/runtime-upgrade-ui) provides proactive runtime upgrade test results and allows you to make bulk runtime upgrades. ### Convert a single monitor [#conver-single] 1. Go to **[one.newrelic.com](https://one.newrelic.com/all-capabilities) > Synthetic monitoring**. 2. Select the monitor you want to want to convert. 3. Click **General** on the left navigation pane. 4. Use the dropdown menu of the **Runtime** field to switch the current runtime view. Select the latest supported runtime for your monitor type. The view changes depending on whether the monitor is an API monitor or a browser monitor. For the current supported versions, see [Review browser monitor runtime dependencies](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/manage-monitor-runtimes/#browserdependencies). ![Upgrade a specific monitor](https://docs.newrelic.com/images/synthetic_screenshot-full_upgrade-one-monitor.webp "Upgrade a specific monitor") 5. Click **Validate** to check that your monitors function in the new runtime. Make any script modifications if needed. 6. Click **Save monitor**. > #### 💡 TIP > > See our runtime upgrade [troubleshooting guide](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/troubleshooting/runtime-upgrade-troubleshooting) for common upgrade errors and solutions. ## Create a monitor in the new runtime [#runtime-UI] When you create a new simple browser monitor, scripted browser monitor, or scripted API monitor, the new runtime will be the default. But, if you're creating a monitor for a [private location](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/private-locations/monitor-private-locations). And, if you're using containerized private minions instead of synthetic job managers, you may need the legacy runtime. To create a monitor in the new runtime: 1. Go to **[one.newrelic.com](https://one.newrelic.com/all-capabilities) > Synthetic monitoring**. 2. Click **Create monitor**. 3. Select the monitor type you want to create. ![Create monitor](https://docs.newrelic.com/images/synthetic_screenshot-crop_create-monitor.webp "Create monitor") 4. Set the fields you consider. **Name** is a required field. 5. Use the dropdown menu of the **Runtime** field to switch between the legacy and new runtime environment. 6. Click **Select locations**. 7. Click **Define steps** to configure the step builder. 8. Click **Save monitor**. The new runtime is backward compatible with the old one. But, we recommend you switch to the new one as soon as possible. ## Use NerdGraph to manage your monitors [#nerdgraph] You can manage synthetic monitors using [our NerdGraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-synthetics-tutorial) to get: - Management of your certificate check monitors, broken links monitors, and step monitors. - Simplified processes for creating scripted monitors. - The ability to attach scripts to scripted monitors with only one call (as opposed to two calls). - The ability to add tags to your monitors. NerdGraph also lets you create [broken links](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-synthetics-tutorial/#create-broken-links), [step](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-synthetics-tutorial/#create-step), and [certificate check](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-synthetics-tutorial/#create-certificate-check) monitors with code. ## Get custom timing details with your scripted API monitors [#custom-timing-details] Using the `$http` object or `request` module in the legacy runtime allowed some of your scripted API monitors to report timing details. The result details were limited to script logs, a check result (pass or fail), and were unavailable with Node.js modules. The new synthetic monitoring runtime includes out-of-the-box timing details when using the default `$http` object. To get custom timing details when using other `Node.js` modules, you can use the [`$har` library](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/custom-timing-details) to report to New Relic. ## Deprecated features [#deprecated] The new runtime includes syntax changes and other deprecations. We're introducing new language that changes the [script syntax](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/synthetic-scripted-browser-reference-monitor-versions-chrome-100) in your scripted browser monitors. The new runtime is backwards compatible with legacy runtime syntax in most cases. To avoid breaking monitors during the upgrade process, you may receive a deprecation warning in your script log output. As of version 2.0.29 or higher of the browser runtime, you will no longer receive deprecation warnings for using the `$browser` or `$driver` syntax in the new runtime. You can continue to use this Selenium 3.6 compatible syntax in the Selenium 4.1 runtime. You can also choose to use the `$webDriver` and `$selenium` based Selenium 4.1 syntax. | Deprecated | New (if applicable) | Why? | | ------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | white/black list | allow/deny list | You can learn more about New Relic's commitment to inclusivity on our [diversity, equity, and inclusion](https://newrelic.com/about/diversity-equity-inclusion) page. | | Selenium WebDriver promise manager / control flow | Use `async/await` or `.then` to handle promises | Selenium WebDriver promise manager / control flow allowed some functions to execute in order, without manually managing promises / async functions. This was removed in Selenium WebDriver 4.0 and is not available in the new runtime. All [async functions and promises](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/synthetic-scripted-browser-reference-monitor-versions-chrome-100) need to be managed with `await` or with `.then` promise chains. This will ensure script functions execute in the expected order. |