ansible.builtin.set_stats module – Define and display stats for the current ansible run

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name set_stats even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.set_stats for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • This module allows setting/accumulating stats on the current ansible run, either per host or for all hosts in the run.

  • This module is also supported for Windows targets.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

aggregate

boolean

Whether the provided value is aggregated to the existing stat true or will replace it false.

Choices:

  • false

  • true ← (default)

data

dictionary / required

A dictionary of which each key represents a stat (or variable) you want to keep track of.

per_host

boolean

Whether the stats are per host or for all hosts in the run.

Choices:

  • false ← (default)

  • true

Attributes

Attribute

Support

Description

action

Support: partial

While the action plugin does do some of the work it relies on the core engine to actually create the variables, that part cannot be overridden

Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller

async

Support: none

Supports being used with the async keyword

become

Support: none

Is usable alongside become keywords

bypass_host_loop

Support: none

Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations

Conditionals will work as if run_once is being used, variables used will be from the first available host

This action will not work normally outside of lockstep strategies

bypass_task_loop

Support: none

These tasks ignore the loop and with_ keywords

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

connection

Support: none

Uses the target’s configured connection information to execute code on it

core

Support: partial

While parts of this action are implemented in core, other parts are still available as normal plugins and can be partially overridden

This is a ‘core engine’ feature and is not implemented like most task actions, so it is not overridable in any way via the plugin system.

delegation

Support: none

Can be used in conjunction with delegate_to and related keywords

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

ignore_conditional

Support: none

The action is not subject to conditional execution so it will ignore the when: keyword

platform

Platforms: all

Target OS/families that can be operated against

tags

Support: full

Allows for the ‘tags’ keyword to control the selection of this action for execution

until

Support: full

Denotes if this action obeys until/retry/poll keywords

Notes

Note

  • In order for custom stats to be displayed, you must set show_custom_stats in section [defaults] in ansible.cfg or by defining environment variable ANSIBLE_SHOW_CUSTOM_STATS to true. See the ansible.builtin.default callback plugin for details.

Examples

- name: Aggregating packages_installed stat per host
  ansible.builtin.set_stats:
    data:
      packages_installed: 31
    per_host: yes

- name: Aggregating random stats for all hosts using complex arguments
  ansible.builtin.set_stats:
    data:
      one_stat: 11
      other_stat: "{{ local_var * 2 }}"
      another_stat: "{{ some_registered_var.results | map(attribute='ansible_facts.some_fact') | list }}"
    per_host: no

- name: Setting stats (not aggregating)
  ansible.builtin.set_stats:
    data:
      the_answer: 42
    aggregate: no

Authors

  • Brian Coca (@bcoca)