Set proxy settings and properties for scripted monitors

Read on to learn about synthetic monitoring's proxy settings and properties.

Proxy settings API for scripted monitors

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 and 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.

Examples

An example of setting a proxy server with HTTP protocol on port 1234 with no authentication:

$network.setProxy('http://host.com:1234')

An example of setting a proxy server with HTTP protocol with authentication credentials.

$network.setProxy('http://proxyUsername:proxyPassword@proxyHost:1234')

$network.setProxyForHttp(string or object PROXY URL)

This call is exactly the same as the per-URL setProxy call, 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.

Examples

An example of setting a proxy server with HTTP protocol on port 1234 with no authentication:

$network.setProxyForHttp('http://host.com:1234')

An example of setting a proxy server with HTTP protocol with authentication credentials.

$network.setProxyForHttp('http://proxyUsername:proxyPassword@proxyHost:1234')

$network.setProxyForHttps(string or object PROXY URL)

This call is exactly the same as the per-URL setProxy call, 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.

Examples

An example of setting a proxy server with HTTPS protocol on port 1234 with no authentication:

$network.setProxyForHttps('https://host.com:1234')

An example of setting a proxy server with HTTPS protocol with authentication credentials.

$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.

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:

var authCredentialsMap = {
'example.com': {username: 'authUsername', password: 'authPassword'},
}

$network.setProxyAdvanced(object PROXY RULES OBJECT)

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. 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. This object is "flavoured" to fit our runtime: users can define an additional property, authCredentials, for the Proxy server objects to provide authentication credentials for a specific proxy server. authCredentials is an object in the format {username: 'authUsername', password: 'authPassword'}.

Examples

An example of creating a proxyRules with authCredentials:

var proxyRules = {
	singleProxy: {
		host:"example.com",
		authCredentials: {
		  username: 'authUsername', 
		  password: 'authPassword'
		}
	}
};

$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();:

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

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.

For more help

Additional documentation resources include:

• Write scripted browsers (how to write scripted browsers for synthetic monitoring)
• Write API tests (how to write API tests for synthetic monitoring)
• Add and edit monitors (how to create virtual browser monitors in New Relic)