--- title: Set proxy settings and properties for scripted monitors source: https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/scripting-monitors/set-proxy-settings-properties-scripted-monitors --- Read on to learn about synthetic monitoring's proxy settings and properties. ## Proxy settings API for scripted monitors [#proxy-api] > #### ⚠️ IMPORTANT > > Proxy usage for Firefox requires version 3.0.7 or higher of the [synthetics-node-browser-runtime image](https://docs.newrelic.com/docs/release-notes/synthetics-release-notes/node-browser-runtime-release-notes/). The global object `$network` allows you to control the network configuration used by your synthetic scripted monitors. The following are applicable for both [scripted browsers](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/scripting-monitors/write-scripted-browsers) and [API tests](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/scripting-monitors/write-api-tests), unless otherwise stated. **$network.setProxy(string or object PROXY URL)** Sets a proxy server to be used for all per-URL requests (HTTP, HTTPS, and FTP). Additional notes: - The port is optional. If not provided, it will be derived from the scheme. For example, for HTTP the port would be 80. - The username and password are assumed to be the result of a call to `encodeURIComponent()`. Special characters like `@` and `:` in the username and/or the password must be escaped. **Returns** This method returns a `Promise` that will resolve once the configuration has been applied. **Parameters** | Parameter | Data Type | Description | | --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `proxyURL | proxyUrlParsed` | String or Object | The URL to connect to the proxy server. A string containing a `proxyURL` (for example, `http://proxy_host:8888`) or a plain object in the same format as defined by [Node's `url.parse(urlString)` method](https://nodejs.org/api/url.html#url_url_strings_and_url_objects). | **Examples** An example of setting a proxy server with HTTP protocol on port 1234 with no authentication: ````js $network.setProxy('http://host.com:1234') ``` An example of setting a proxy server with HTTP protocol with authentication credentials. ```js $network.setProxy('http://proxyUsername:proxyPassword@proxyHost:1234') ``` ```` **$network.setProxyForHttp(string or object PROXY URL)** > #### 💡 TIP > > This call is exactly the same as the [per-URL `setProxy` call](#setproxy-perurl), except that it applies to HTTP traffic. Sets a proxy server to be used for all HTTP requests. Additional notes: - The port is optional. If not provided, it will be derived from the scheme. For example, for HTTP the port would be 80. - The username and password are assumed to be the result of a call to `encodeURIComponent()`. Special characters like `@` and `:` in the username and/or the password must be escaped. **Returns** This method returns a `Promise` that will resolve once the configuration has been applied. **Parameters** | Parameter | Data Type | Description | | --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `proxyURL | proxyUrlParsed` | String or Object | The URL to connect to the proxy server. A string containing a `proxyURL` (for example, `http://proxy_host:8888`) or a plain object in the same format as defined by [Node's `url.parse(urlString)` method](https://nodejs.org/api/url.html#url_url_strings_and_url_objects). | **Examples** An example of setting a proxy server with HTTP protocol on port 1234 with no authentication: ````js $network.setProxyForHttp('http://host.com:1234') ``` An example of setting a proxy server with HTTP protocol with authentication credentials. ```js $network.setProxyForHttp('http://proxyUsername:proxyPassword@proxyHost:1234') ``` ```` **$network.setProxyForHttps(string or object PROXY URL)** > #### 💡 TIP > > This call is exactly the same as the [per-URL `setProxy` call](#setproxy-perurl), except that it applies to HTTPS traffic. Sets a proxy server to be used for all HTTPS requests. Additional notes: - The port is optional. If not provided, it will be derived from the scheme. For example, for HTTP the default port would be 443. - The username and password are assumed to be the result of a call to `encodeURIComponent()`. Special characters like `@` and `:` in the username and/or the password must be escaped. **Returns** This method returns a `Promise` that will resolve once the configuration has been applied. **Parameters** | Parameter | Data Type | Description | | --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `proxyURL | proxyUrlParsed` | String or Object | The URL to connect to the proxy server. A string containing a `proxyURL` (for example, `http://proxy_host:8888`) or a plain object in the same format as defined by [Node's `url.parse(urlString)` method](https://nodejs.org/api/url.html#url_url_strings_and_url_objects). | **Examples** An example of setting a proxy server with HTTPS protocol on port 1234 with no authentication: ````js $network.setProxyForHttps('https://host.com:1234') ``` An example of setting a proxy server with HTTPS protocol with authentication credentials. ```js $network.setProxyForHttps('https://proxyUsername:proxyPassword@proxyHost:1234') ``` ```` **$network.setProxyPAC(string PAC SCRIPT URL, object AUTH OBJECT)** Sets a proxy server via a proxy auto-config (PAC) script and returns a promise. This function is only available for [scripted browser monitors](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/scripting-monitors/write-scripted-browsers). **Returns** This method returns a `Promise` that will resolve once the configuration has been applied. **Parameters** | Parameter | Data Type | Description | | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `scriptURL` | String | The URL of the PAC script. | | `authCredentialsMap` | Object | Map of authentication credentials to be provided to the proxy server(s), keyed by the hostnames of the proxy server. Values of this map must be defined in the format `{username: 'authUsername', password: 'authPassword'}` | **Examples** An example of setting a proxy server via a proxy auto-config (PAC) script: ````js var authCredentialsMap = { "example.com": { username: "authUsername", password: "authPassword" }, }; ``` Here's an example of setting up a proxied network via proxy auto-config (PAC) script: ```js var authCredentialsMap = { "example.com": { username: "authUsername", password: "authPassword" }, "anotherExample.com": { username: "authUsername", password: "authPassword" }, }; $network.setProxyPAC("https://www.example.com/pacScript", authCredentialsMap); ``` ```` **$network.setProxyAdvanced(object PROXY RULES OBJECT)** > #### 💡 TIP > > This method is **Chrome-specific**: it only applies to scripted browser monitor types. It can be used to allow for a more flexible and complex proxy configuration. In most cases, this method will not be needed. Sets the proxy configuration using the format supported by Chrome Extension API for Proxying. The input is a ProxyRules object, as defined by the [Chrome Extension API to configures proxies](https://developer.chrome.com/extensions/proxy#type-ProxyRules). You can add `authCredentials` for proxies that need it. See Parameters for more details. **Returns** This method returns a `Promise` that will resolve once the configuration has been applied. **Parameters** | Parameter | Data Type | Description | | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProxyRules Object` | Object | The `proxyRulesObject` is a plain object that follows the format ProxyRules as defined by the [Chrome Extension API to configures proxies](https://developer.chrome.com/extensions/proxy#type-ProxyRules). This object is "flavoured" to fit our runtime: users can define an additional property, `authCredentials`, for the [`Proxy server objects`](https://developer.chrome.com/extensions/proxy#type-ProxyServer) to provide authentication credentials for a specific proxy server. `authCredentials` is an object in the format `{username: 'authUsername', password: 'authPassword'}`. | **Examples** Here's an example of creating a `proxyRules` with `authCredentials`: ````js var proxyRules = { singleProxy: { host: "example.com", authCredentials: { username: "authUsername", password: "authPassword", }, }, }; ``` Here's an example of setting up a proxied network with mixed network zone assets: ```js var proxyRules = { singleProxy: { host: "entproxy.mycompany.com", port: 8888, scheme: "http" }, bypassList: ["s3.amazonaws.com", "*.localcdn.com"], }; $network.setProxyAdvanced(proxyRules); ``` ```` **$network.clearProxy()** Clears/removes the current proxy configuration. **Returns** This method returns a `Promise` that will resolve once the configuration has been applied. **$network.getProxy()** This method returns the current proxy configuration. It must be synchronized in a promise callback. **Examples** An example of synchronizing `getProxy` with `$network.setProxy();` and `$network.clearProxy();`: ````js var assert = require("assert"); $network .setProxy("http://user:password@myproxyurl.com") .then(function () { console.log("Proxy configuration applied"); // Note: $network.getProxy() is not synchronized with the webdriver Control Flow. // To make sure we get the proxy configuration after the call to setProxy() above // succeeds we need to use a promise callback var proxyData = $network.getProxy(); console.log(proxyData); }) .then(function () { // Again: getProxy() is not synchronized with the Webdriver Control Flow: we // need this promise callback otherwise clearProxy() might be called before the call // to getProxy() above returns return $network.clearProxy(); }) .then(function () { console.log("Proxy configuration cleared"); // We need this promise callback for reasons explained above var proxyData = $network.getProxy(); assert.equal(proxyData.rules, null); }); ``` ```` ## Proxy properties [#proxy] > #### ⚠️ IMPORTANT > > This proxy information applies only to these versions: > > - API monitors: 0.4.0, 0.2.2, 0.2.1, 0.1.0 > - Scripted monitors: 0.1.0 In order to analyze and collect your HTTP traffic metrics, New Relic must ensure the traffic passes through a conceptual funnel. Our synthetic monitoring includes a software funnel component capable of analyzing the HTTP requests or responses and then recording the information. - New Relic's scripted browser monitors (versions 0.4.x and lower) include a mechanism to do this analysis without needing an HTTP proxy, so you don't have to configure anything. - New Relic's API test (versions 0.4.x and lower) provides an `$http` object that is pre-configured to make the requests pass through the internal HTTP proxy. This allows you to write your test without including any proxy settings. If you want to use some other way to generate HTTP traffic while still collecting the HTTP traffic metrics, you can use `$env.PROXY_HOST` and `$env.PROXY_PORT`. To record traffic metrics, be sure to include these properties in your script.