API

Setup

init()

You must call init to set up r7insight.js. At a minimum you must specify a token and a region that corresponds to the data center that your Insight Platform account is in (e.g. us or eu):

R7Insight.init({token: 'YOUR-LOG-TOKEN', region: 'YOUR INSIGHT PLATFORM REGION (us / eu)'});

you can also change the default parameters:

Option	Description	Default	Example
token and region	Mandatory. The Insight log token	N/A	R7Insight.init({token: 'TOKEN', region: 'eu'}) or R7Insight.init({token: 'TOKEN', region: 'us'})
ssl	Use SSL/TLS to send events. See encryption	true	R7Insight.init({token: 'TOKEN', region: 'eu' , ssl: false})
catchall	Log any uncaught JavaScript exceptions. This replaces the window.onerror handler, but if you've specified one already, it'll invoke that one afterwards	false	R7Insight.init({token: 'TOKEN', region: 'eu', catchall: true})
trace	Adds a randomly generated trace code	true	R7Insight.init({token: 'TOKEN', region: 'eu', trace: true})
no_format	Sends events to Insight verbatim.	false	R7Insight.init({token: 'TOKEN',region: 'eu', no_format: true})
page_info	Append basic information about browser capabilities. Options are never, per-page and per-entry. See page info	'never'	R7Insight.init({token: 'TOKEN', region: 'eu',page_info: 'per-page'})
print	Echo events to the screen via the console object. This will logged at the same level as the call to R7Insight, e.g. R7Insight.warn(msg) => console.warn(msg). See log levels	false	R7Insight.init({token: 'TOKEN',region: 'eu', print: true})

Tracing

When logging on the web, you don't have any knowledge of the event-generators (browsers!) ahead of time. This presents a problem: how do you group events that originated from the same user-agent, and how do you differentiate users? Even if you have their IP address, that's not a strong guarantee of uniqueness.

The trace_code option adds a string that's unique to each user-agent, giving you a handle to search against in the Insight dashboard.

Encryption

By default, r7insight.js encrypts calls to the Insight service with TLS. In certain versions of IE, log events are sent in the clear regardless of configuration due to the constraints of the XDomainRequest specification. Specifically, if the page was served via plain http, log data will be as well.

Page info

r7insight.js optionally lets you log basic capabilities for the originating user-agent. The data sent will look something like this:

{
    name: "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us)",
    screenWidth: 1024,
    screenHeight: 768
}

You can choose to send this at the following frequencies:

• per-page: the first time an event is logged after a page refresh
• per-entry: every time an event is logged
• never: not at all

Logging

With r7insight.js configured, go log some events. log takes most of the same arguments as console.log:

log()

R7Insight.log("Hello, logger!"); // Simple string-literal

var x = "logger";
R7Insight.log("Hello, ", x, " and some objects: ", 1); // Interpolation

R7Insight.log({hello: "logger!"}); // Object (gets logged as a key=value pair)

// An object with some nesting
R7Insight.log({nested:
    {object: [1,null],
     key: undefined}
});
// => nested.object.0=1,nested.object.1=null,nested.key=undefined

Format

• Simple JS types (numbers, string literals and booleans) are left untouched
• undefined values will be explicitly printed as strings for clarity (unlike, say, JSON.stringify())
• Objects and arrays are 'flattened' to make them searchable; see the examples above
• Instead of failing on the client, cyclic objects are replaced with a placeholder so they can be serialized. For example:

var x = {}
x.y = x;

R7Insight.log(x) // => {y: '<?>'}

Log levels

r7insight.js supports the following methods to log events at different severity levels:

• log
• info
• warn
• error

They otherwise behave exactly the same as log():

R7Insight.log("a LOG level event");
R7Insight.info("an INFO level event");
R7Insight.warn("a WARN level event");
R7Insight.error("an ERROR level event");

Ad blockers

If you find that the script or its requests are blocked by ad blockers, you can load the script from your own domain and proxy the requests (which look like https://us.webhook.logs.insight.rapid7.com/v1/logs/94e2188b-506a-40cd-8601-9be0f40ede27) through your own domain as well, using the LEENDPOINT global option. Here's how:

If your custom url resembles https://<region>.my-hostname.<ext>, then you would set the region as normal :

window.LEENDPOINT = window.location.host + '/r7insight/v1';  // in R7Insight: _endpoint = (_SSL ? "https://" : "http://") + _endpoint + "/logs/" + _token;

R7Insight.init({
  token : 'YOUR-LOG-TOKEN',
  region : 'YOUR INSIGHT PLATFORM REGION (us / eu)'});

If you wanted to pass traffic to the same domain the site is running on you would need to set region = 'custom'

window.LEENDPOINT = window.location.host + '/r7insight/v1';  // in R7Insight: _endpoint = (_SSL ? "https://" : "http://") + _endpoint + "/logs/" + _token;

R7Insight.init({
  token : 'YOUR-LOG-TOKEN',
  region : 'custom'});

In your web server’s config, you need to proxy /r7insight/... to eu|[us.js.logs.insight.rapid7.com/](http://us.js.logs.insight.rapid7.com/)....

Region is set to REGION (change this to the region you require (eu/us)). Headers are based on the ones required behind cloudfront and elb in AWS. TLS communication is assumed to be the norm. We rewrite away our custom path and use a variable for the hostname to avoid nginx pinning to a specific IP (workaround to use nginx dns-resolver http://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) in AWS our nginx http{} config section would contain something like :

# DNS Resolver
  resolver 169.254.169.253 valid=15s ipv6=off;
  resolver_timeout 15s;

Here’s an example proxy location for nginx (this would sit inside your sites server{} configuration) :

location /r7insight/ {
    set $logentries REGION.webhook.logs.insight.rapid7.com;
    rewrite ^/r7insight/(.*)$ /noformat/logs$1 break;
 
    proxy_set_header X-Forwarded-For $http_x_forwarded_for;
    proxy_set_header X-Real-IP $proxy_add_x_forwarded_for;

    proxy_ssl_protocols TLSv1.2;
    proxy_ssl_server_name on;
 
    proxy_set_header Host $logentries;
    proxy_pass https://$logentries;
}

Replace REGION with the data center that your InsightOps account is based in (e.g. “us” or “eu”). Insight doesn’t parse the proxy headers so all logged data will appear as if it came from your proxy server.