Read on to learn about synthetic monitoring's proxy settings and properties.
Proxy settings API for scripted monitors
You can set proxy server configuration for synthetic scripted monitors for monitor versions 0.4.0 or higher.
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'surl.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'surl.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'surl.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 theProxy 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
withauthCredentials
: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
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.
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)