W3cubDocs

/Ansible

community.general.statsd module – Send metrics to StatsD

Note

This module is part of the community.general collection (version 10.7.3).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.statsd.

New in community.general 2.1.0

Synopsis
Requirements
Parameters
Attributes
Examples

Synopsis

The statsd module sends metrics to StatsD.
For more information, see https://statsd-metrics.readthedocs.io/en/latest/.
Supported metric types are counter and gauge. Currently unupported metric types are timer, set, and gaugedelta.

Requirements

The below requirements are needed on the host that executes this module.

statsd

Parameters

Parameter	Comments
delta boolean	If the metric is of type `gauge`, change the value by `delta`. Choices: `false` ← (default) `true`
host string	StatsD host (hostname or IP) to send metrics to. Default: `"localhost"`
metric string / required	The name of the metric.
metric_prefix string	The prefix to add to the metric. Default: `""`
metric_type string / required	The type of metric. Choices: `"counter"` `"gauge"`
port integer	The port on `host` which StatsD is listening on. Default: `8125`
protocol string	The transport protocol to send metrics over. Choices: `"udp"` ← (default) `"tcp"`
state string	State of the check, only `present` makes sense. Choices: `"present"` ← (default)
timeout float	Sender timeout, only applicable if `protocol` is `tcp`. Default: `1.0`
value integer / required	The value of the metric.

Attributes

Attribute	Support	Description
check_mode	Support: none	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Examples

- name: Increment the metric my_counter by 1
  community.general.statsd:
    host: localhost
    port: 9125
    protocol: tcp
    metric: my_counter
    metric_type: counter
    value: 1

- name: Set the gauge my_gauge to 7
  community.general.statsd:
    host: localhost
    port: 9125
    protocol: tcp
    metric: my_gauge
    metric_type: gauge
    value: 7

Authors

Mark Mercado (@mamercad)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/statsd_module.html