Artillery Metrics by Endpoint Plugin

1.24.0 · active · verified Wed Apr 22

The `artillery-plugin-metrics-by-endpoint` package extends Artillery, a powerful load testing tool, by providing granular, per-endpoint breakdown of latency and HTTP response codes. Unlike Artillery's default behavior, which aggregates performance metrics across all endpoints, this plugin enables users to view statistics (e.g., p50, p95, p99 response times, min/max latency, and status code counts) for each unique URL or named request within their HTTP tests. The current stable version is 1.24.0, with releases typically aligning with updates to the main Artillery monorepo, where the plugin's code now resides. Its key differentiator is the ability to offer deep insights into individual endpoint performance, crucial for identifying bottlenecks in complex microservice architectures or APIs with many routes. It offers configuration options to intelligently group metrics for dynamic URLs, providing clearer reports.

Common errors

```
WARNING: Plugin metrics-by-endpoint specified but module artillery-plugin-metrics-by-endpoint could not be found (MODULE_NOT_FOUND)
```
cause Artillery cannot find the plugin package. This usually means the plugin was installed in a different npm scope (global vs. local) than Artillery, or it was not installed at all.

fix Ensure `artillery-plugin-metrics-by-endpoint` is installed in the same manner as your Artillery installation. If Artillery is global, install the plugin globally (`npm install -g artillery-plugin-metrics-by-endpoint`). If Artillery is a local project dependency, install the plugin locally (`npm install --save-dev artillery-plugin-metrics-by-endpoint`).
```
Metrics for dynamic URLs are not grouping correctly; I see many distinct endpoints for what should be one logical endpoint (e.g., /users/1, /users/2, etc.)
```
cause The plugin's default behavior treats each unique URL string as a separate endpoint. Without specific configuration, dynamic path segments or query parameters result in separate metric entries.

fix Add `useOnlyRequestNames: true` and define `name` properties for your requests in the Artillery scenario. For dynamic path segments, ensure your `name` is consistent across those requests. If query parameters are causing the issue, add `stripQueryString: true`.
```
I expected the plugin to only show metrics for requests with an explicit 'name' property when `useOnlyRequestNames` is true, but it's still showing metrics for unnamed requests.
```
cause Even with `useOnlyRequestNames: true`, if a request lacks a `name`, the plugin may still fall back to using the full URL path, which can be unexpected.

fix Ensure *all* requests you want metrics for have an explicit `name` property. Additionally, you can set `reportNoNameRequests: false` in the plugin configuration to explicitly prevent metrics from being reported for requests that do not have a `name` field.

Warnings

breaking As of Artillery v2 (2.0.0-beta.x and later), there were significant internal changes. While this plugin is now integrated into the main Artillery monorepo, ensure your `artillery` and `artillery-plugin-metrics-by-endpoint` versions are compatible, especially if you are using older Artillery versions.
Fix: Upgrade Artillery to a recent stable version (e.g., `npm install -g artillery@latest`) and ensure `artillery-plugin-metrics-by-endpoint` is also at its latest version (`npm install artillery-plugin-metrics-by-endpoint`). If Artillery is installed locally, install the plugin locally too.
gotcha By default, the plugin treats each unique URL, including query parameters, as a separate endpoint. This can lead to an explosion of metrics for dynamic URLs (e.g., `/item?id=1`, `/item?id=2`), making reports unmanageable.
Fix: Configure `stripQueryString: true` to ignore query parameters, and/or `useOnlyRequestNames: true` (recommended) to group metrics based on the `name` property defined for requests in your scenario. Set `groupDynamicURLs: false` to ensure dynamic parts of the URL are still considered unique if `useOnlyRequestNames` isn't fully comprehensive.
gotcha If `useOnlyRequestNames: true` is set, but some requests in your scenario do not have a `name` property defined, the plugin might still fall back to using the full request path as the metric name, contrary to the expectation that only named requests would be reported or that unnamed requests would be skipped.
Fix: Explicitly add a `name` property to *all* requests for which you desire per-endpoint metrics when `useOnlyRequestNames: true`. Consider setting `reportNoNameRequests: false` if you strictly only want metrics for explicitly named requests.
gotcha Artillery plugins must be installed in the same scope (global or local) as Artillery itself. Mismatched installations can lead to the plugin not being found or loaded correctly.
Fix: If Artillery is installed globally (`npm install -g artillery`), install the plugin globally (`npm install -g artillery-plugin-metrics-by-endpoint`). If Artillery is a local project dependency, install the plugin as a local dev dependency (`npm install --save-dev artillery-plugin-metrics-by-endpoint`).

Install

npm install artillery-plugin-metrics-by-endpoint npm
yarn add artillery-plugin-metrics-by-endpoint yarn
pnpm add artillery-plugin-metrics-by-endpoint pnpm

Imports

Plugin Activation
wrong:
```
import { MetricsByEndpointPlugin } from 'artillery-plugin-metrics-by-endpoint';
```
correct:
```
config:
  plugins:
    metrics-by-endpoint: {}
```
Artillery plugins are activated via YAML configuration in the test script, not through direct JavaScript imports. The `metrics-by-endpoint` key corresponds to the npm package name.
Configuration Options
wrong:
```
// No direct JS import for configuration is typically used by end-users.
```
correct:
```
config:
  plugins:
    metrics-by-endpoint:
      useOnlyRequestNames: true
      stripQueryString: true
```
Plugin-specific options like `useOnlyRequestNames` or `stripQueryString` are configured directly under the plugin's entry in the `config.plugins` section of the Artillery YAML test script. There is no public JavaScript API for end-user configuration.
Defining Request Names
wrong:
```
// No direct JS import pattern for this concept.
```
correct:
```
- get:
    url: '/users/{{ userId }}'
    name: 'Get User Profile'
```
To leverage `useOnlyRequestNames`, define a `name` property on your HTTP requests within the scenario flow. This explicitly tells the plugin how to group metrics, especially for dynamic URLs, providing more stable reporting.

Quickstart

This Artillery YAML script demonstrates how to enable the `metrics-by-endpoint` plugin and configure it to report metrics based on explicit request names, while stripping query strings for better aggregation. It includes a multi-step scenario with named HTTP requests, ensuring granular performance data for each defined endpoint.

config:
  target: 'https://api.example.com'
  phases:
    - duration: 60
      arrivalRate: 10
      name: 'Warm up traffic'

  plugins:
    metrics-by-endpoint:
      useOnlyRequestNames: true # Aggregate metrics by 'name' property of requests
      stripQueryString: true    # Ignore query parameters when determining endpoint identity

  scenarios:
    - name: 'User Scenario with Endpoint Metrics'
      flow:
        - get:
            url: '/status'
            name: 'Check API Status'
        - post:
            url: '/users'
            name: 'Create New User'
            json:
              username: 'user_{{ $uuid }}'
              email: 'user_{{ $uuid }}@example.com'
            capture:
              json: '$.id'
              as: 'userId'
        - get:
            url: '/users/{{ userId }}'
            name: 'Retrieve User Profile'
        - put:
            url: '/users/{{ userId }}'
            name: 'Update User Profile'
            json:
              status: 'active'

view raw JSON →