StatsD

Artillery can send metrics to any StatsD-compatible backend, providing a simple and widely-supported protocol for metrics collection.

Quick Start

config:
  plugins:
    publish-metrics:
      - type: statsd
        host: localhost
        port: 8125

Configuration

Configuration Options

Examples

Basic Configuration

config:
  plugins:
    publish-metrics:
      - type: statsd
        prefix: 'artillery.publish_metrics_plugin.'

Custom Host and Port

config:
  plugins:
    publish-metrics:
      - type: statsd
        host: metrics.example.com
        port: 8126
        prefix: 'loadtest.'

Multiple Environments

config:
  plugins:
    publish-metrics:
      - type: statsd
        host: '{{ $env.STATSD_HOST }}'
        port: '{{ $env.STATSD_PORT }}'
        prefix: 'artillery.{{ $env.ENVIRONMENT }}.'

Compatible Backends

The StatsD integration works with any StatsD-compatible backend:

• Original StatsD: The original Etsy StatsD daemon
• Telegraf: InfluxData’s metrics collector (see InfluxDB integration)
• Datadog Agent: Can receive StatsD metrics (see Datadog integration)
• AWS CloudWatch Agent: Supports StatsD protocol
• Graphite: With StatsD frontend
• Prometheus: Via statsd_exporter

Metric Format

Artillery sends the following metric types to StatsD:

• Counters: For counts (e.g., total requests, errors)
• Timers: For latencies (e.g., response times)
• Gauges: For concurrent users and other measurements

Example metric names (with default prefix):

• artillery.http.requests - Total HTTP requests
• artillery.http.response_time - Response time measurements
• artillery.errors.ECONNREFUSED - Connection errors
• artillery.vusers.active - Active virtual users

Best Practices

1. Use namespacing: Include environment and service names in your prefix
2. Monitor UDP buffer: StatsD uses UDP, which can drop packets under high load
3. Local StatsD relay: Consider running a local StatsD relay to buffer metrics
4. Consistent prefixes: Use consistent prefixes across all your load tests

Debugging

To verify metrics are being sent, you can:

1. Use tcpdump to monitor UDP traffic:

   tcpdump -i any -n udp port 8125

2. Run a simple StatsD server for testing:

   nc -lu 8125

3. Check your StatsD backend’s logs and dashboards