- Different ways of extending and customizing Artillery
- How to track custom metrics from your tests
- How to customize VU behavior with custom JS code
- How Artillery plugins work
Artillery is designed to be extensible and hackable to let users customize it if needed. Artillery is powered by Node.js which means that thousands of high-quality
npm modules can be leveraged to do pretty much anything you may need to do.
Virtual user behavior can be customized via custom functions written in JS and attached to scenarios via extension points also known as “hooks”. Different engines provide different extension points, e.g. the HTTP engine supports the following hooks:
beforeRequest- run a function before a request is sent
afterResponse- run a function after a response has been received
function- run a function as a step anywhere in the scenario
Please refer to documentation of individual engines for details on what hooks they support, and what the APIs look like:
Custom metrics may be tracked from custom JS code. Two metric types are supported:
- counters - a count of some things that happened, e.g. the number of times VUs completed a certain transaction
- histograms - a distribution (max, min,
p99) of some measurement, e.g. API response time
Custom metrics are included in Artillery’s output alongisde standard metrics.
Custom metrics are sent through an
EventEmitter object, which is available as an argument in hook functions, and as a constructor parameter for plugins and engines.
events.emit('counter', 'my_counter', 1)- increment the value of a counter called
events.emit('histogram, 'my_histogram', 42)- record a measurement of
42in a histogram called
Imagine, we have the following request in a scenario which creates a new
pet object. We’d like to count how many pony objects we’ve created. Ponies are also computationally-expensive to create, so we’d like to track response time for pony-related requests specifically:
Plugins provide a way to package up some functionality in an easy to use interface. Plugins in Artillery have full access to the test script and Artillery’s internals, and it’s possible to get very creative with what they can do.
Artillery plugins are distributed as
npm packages and follow the
artillery-plugin-$NAME convention, e.g.
- Plugins are enabled via
config.pluginssection of a test script, which makes Artillery try to load the plugin. For example:This config will make Artillery try to find & load
option1: some value
option2: some other value
- The plugin package is expected to export a
Pluginclass. The constructor receives two arguments:
script- the entire test script definition, which may be modified by plugin code. For example: a plugin may attach additional hook functions to scenario definitions, like the metrics-by-endpoint plugin.
EventEmitterwhich receives events from Artillery, and may be used to send custom metrics, like the
- A plugin may define a
cleanupfunction, which takes a
donecallback. Artillery will call this function when a test finishes before exiting, providing an opportunity for any cleanup that a plugin needs to do, like flushing buffered metrics to an external monitoring system for example.
Plugins can subscribe to the following events:
phaseStarted- a new arrival phase has started
phaseCompleted- an arrival phase has finished
stats- provides metrics for the previous reporting period
done- all VUs are finished
An engine packages up a way to communicate with a particular type of server in Artillery, like HTTP, Socket.io or WebSockets. Engines may work on levels 4 or 7 of the OSI model or on a higher-level protocol level, e.g. an SQL engine, or a AWS Kinesis engine.
We’re working on expanding this section in the documentation. In the meantime, the AWS Kinesis engine is a good place to start if you’re looking to write your own engine.
Custom reporters to send metrics and reports to external systems may be implemented as plugins. Please see the official
publish-metrics plugin for a complete example.