Mappers are the third stage of the extension pipeline, called after validators and filters but before forwarders. Their purpose is to transform beacon data into an appropriate format to be consumed by some other process.
The choice of mapper can be specified at the command line, using the -m option. Four mappers are available out-of-the-box, statsd, har, waterfall and unmapped.
Defining custom mappers is simple. The source code for the statsd mapper should be easy to follow, but the basic pattern is to export an interface that looks like this:
{
initialise: function (options) {
}
}Where initialise is a function that takes an options object and returns the mapper function, bound to any pertinent options. The signature for the returned mapper function should look like this:
function (/* bound options, ... */ data, referer, userAgent, remoteAddress) {
}The remaining/unbound arguments passed to the mapper are, in order:
data: Filtered data.referer: URL of the page that sent the beacon request.userAgent: User agent string of the client that sent the beacon request.remoteAddress: IP address of the client that sent the beacon request.
The result of the mapper function should be a string containing the mapped data.
In addition to the initialise function, mappers may optionally expose a separator property, which can be used by forwarders to ensure sane data-chunking behaviour in the event that they are required to break data across multiple packets before sending it on. For example, the statsd mapper defines separator as '\n'.