Fact gathering is usually the bill · Ansible

The facts part of this course established what the implicit setup task is, what it costs, and how gather_subset and gather_facts: false change that. This lesson does not repeat the mechanism. It answers the question that comes up once you have a profile in front of you: given that gathering is the top line, how do you cut it without breaking something?

That question has a specific answer, and it is not “try it and see”. Facts are read implicitly all over a mature repository — in when: conditions, in templates, in role defaults, in variable definitions two layers away from the play — and removing one is not a change that fails loudly. It is a change that renders a config file with an empty value.

Why this lesson leads the tuning list

The measurement from the first lesson in this part, on a play that gathers facts and prints one value across 24 hosts:

Read-only / Safethe profile that starts most investigations— ansible-core 2.21.3 with ansible.posix 2.1.0, forks 12, local connections and therefore no network at all.

$ ANSIBLE_CALLBACKS_ENABLED=ansible.posix.profile_tasks ansible-playbook -i facts.ini facts.yml -f 12

TASKS RECAP ********************************************************************
===============================================================================
Gathering Facts --------------------------------------------------------- 2.43s
Nothing else ------------------------------------------------------------ 0.12s

95% of the run, with the network removed. On a real fleet the gathering task also pays an SSH conversation per host, so the proportion goes up, not down.

Every other lever in this part trades something away. Raising forks trades an accidental blast-radius limit. free trades the synchronisation barrier. Pipelining trades a sudoers hardening default. Fact caching trades freshness.

Cutting gathering trades nothing — provided the facts you cut are ones nothing reads. That proviso is the whole lesson.

The audit

Before changing any play, find out what the repository actually reads.

Read-only / Safewhat facts does this repository consume?— Three read-only greps over the repository. They find the direct references; the callout below covers what they miss.

# 1. Direct fact references, in every form they are written
grep -rhoE 'ansible_facts\[.[a-z_]+|ansible_facts\.[a-z_]+|\bansible_[a-z0-9_]+' \
roles/ playbooks/ inventory/ templates/ 2>/dev/null \
| sed -E 's/ansible_facts[\.\[].?//' \
| sort -u

# 2. Anything reading facts of OTHER hosts - these need those hosts gathered
grep -rn 'hostvars\[' roles/ playbooks/ 2>/dev/null

# 3. Templates are the easiest place to miss one
grep -rn 'ansible_' templates/ roles/*/templates/ 2>/dev/null

Run it and read the output. A typical result on a real repository is twenty to forty distinct facts, and almost all of them come from three or four subsets — distribution, pkg_mgr, default_ipv4, processor_count. The list is nearly always much shorter than people expect, which is exactly why the saving is available.

Map what you find onto subsets with ansible-doc, which lists every legal value:

ansible-doc ansible.builtin.setup | sed -n '/gather_subset/,/^$/p'

What the grep misses

Three things, and each has bitten someone:

Connection variables that look like facts. ansible_host, ansible_user, ansible_port and ansible_connection come from inventory, not from setup. They will appear in your grep results and they are not evidence that you need gathering. Do not add subsets for them.

Facts read through indirection. A role default written as app_listen_address: "{{ ansible_default_ipv4.address }}" is a fact reference that only fires when the default is used. So is {{ lookup('vars', 'ansible_' + some_variable) }}, which no grep will find.

Facts read by collection content you did not write. A third-party role in requirements.yml reads whatever it reads. grep over ~/.ansible/collections and your roles_path too, or accept that gather_facts: false on a play that calls one is a gamble.

The safe order is: audit, restrict to a subset, run the full suite in staging, and only then consider disabling gathering entirely. --check is useful here, because an undefined fact fails during templating whether or not the module would have changed anything.

What each subset costs

Measured on the pinned controller: 24 hosts, forks: 12, one trivial task, with only the gathering configuration changed.

Read-only / Safethe cost of each gathering choice— ansible-core 2.21.3, local connections. These are controller-side collection costs with no network; a real fleet adds an SSH conversation per host to every row except the first.

$ /usr/bin/time -f '%e s' ansible-playbook -i facts.ini gsub.yml -f 12 -e '{"gs":[...]}'

gather_facts: false                          0.35 s
gather_subset: ['!all','!min','distribution'] 1.08 s
gather_subset: ['!all']            (min)      1.10 s
gather_subset: ['!all','!min','network']      1.39 s
gather_subset: ['!all','!min','hardware']     2.53 s
gather_subset: ['all']             (default)  2.81 s

Four readings from that table:

Full gathering is 2.46 s of a 2.81 s run. 87% of the wall clock, before the network.
hardware is the expensive one. 2.53 s on its own — nearly the whole cost of all. It walks the mount table, enumerates devices and reads memory and CPU topology. If nothing in your repository reads ansible_memtotal_mb, ansible_processor_count, ansible_devices or ansible_mounts, this is the single biggest saving available.
The minimal set is cheap. 1.10 s, and it includes distribution, which is what most conditionals actually branch on. Note that ['!all','!min','distribution'] measured 1.08 s — the same as min — because !all alone still collects the minimal set.
Disabling gathering entirely is a step change, not an increment: 0.35 s. If a play genuinely reads no facts, that is the option.

Read-only / Safea subset chosen from an audit, with the reason recorded— Gathering reads system information and changes nothing, whatever subset is chosen.

- name: Deploy the monitoring agent
hosts: appservers
# Audited 2026-08-11: this play and the roles it includes read
# ansible_distribution, ansible_os_family and ansible_pkg_mgr only.
# hardware is not collected - it was 2.53s of a 2.81s run.
gather_subset:
  - '!all'
  - '!min'
  - distribution
  - pkg_mgr
tasks:
  - name: Install the agent package
    ansible.builtin.package:
      name: monitoring-agent
      state: present

The comment is the load-bearing part. Without it, the next person to add a task that reads ansible_mounts gets an undefined-variable error with no indication of where the constraint came from, and the obvious fix — deleting the gather_subset block — throws away the saving instead of extending the list.

Gathering on demand

The third option, and the one that fits a play where some hosts need facts and most do not, or where facts are needed only after something has changed.

ansible.builtin.setup is an ordinary module. You can call it whenever you like:

Read-only / Safegather late, and only where needed— setup reads system information. It is read-only on every host it runs against.

- name: Resize and reconfigure
hosts: appservers
gather_facts: false          # most of this play needs nothing

tasks:
  - name: Expand the data volume
    community.general.lvol:
      vg: data
      lv: app
      size: "{{ app_volume_size }}"
    register: volume_change

  - name: Re-read hardware facts now that the volume changed
    ansible.builtin.setup:
      gather_subset:
        - '!all'
        - '!min'
        - hardware
    when: volume_change is changed

  - name: Size the cache to the volume we now actually have
    ansible.builtin.template:
      src: cache.conf.j2
      dest: /etc/app/cache.conf
      mode: '0644'
    when: volume_change is changed

Two things this shape gets right that a play-level gather_facts: true cannot.

The expensive hardware subset is collected only on hosts where something changed, rather than on all of them at the start. And the facts are read after the change rather than before, which is the difference between sizing a cache to the new volume and sizing it to the old one.

Under the hood

There is a fleet-wide switch that changes the default without editing every play: the gathering setting.

Read-only / Safewhat the three choices mean— From ansible-config list on ansible-core 2.21.3.

$ ansible-config list | grep -A18 '^DEFAULT_GATHERING:'

DEFAULT_GATHERING:
choices:
  explicit: facts will not be gathered unless directly requested in the play.
  implicit: 'the cache plugin will be ignored and facts will be gathered per play
    unless ''gather_facts: False'' is set.'
  smart: each new host that has no facts discovered will be scanned, but if the
    same host is addressed in multiple plays it will not be contacted again in the
    run.
default: implicit
ini:
- key: gathering
  section: defaults

The default is implicit, and its description contains the detail that matters for this part: implicit ignores the cache plugin. A fact cache configured under the default gathering mode does nothing for a play that does not set gather_facts: false, which is a common and confusing way for caching to appear not to work.

smart is the setting for a multi-play playbook. A site.yml that composes eight plays over overlapping groups gathers facts once per host for the whole run instead of once per play. It costs nothing in risk within a single run — the facts are still from this run — and it is the change to make before considering a persistent cache.

explicit inverts the default: nothing gathers unless a play asks. That is the right setting for a repository that has completed the audit and annotated its plays, and the wrong one to impose on a repository that has not, because every play that quietly depended on facts breaks at once.

What happens if you set gather_facts: false on a play that turns out to need one fact?

You get an undefined-variable error, and where it surfaces decides how bad the day is.

In a when: condition — the task fails on every host with 'ansible_os_family' is undefined. Loud, immediate, and easy to fix.

In a template — the render fails, so the file is not written. Also loud.

In a template with a default() filter — this is the bad one. A template written as listen = {{ ansible_default_ipv4.address | default('0.0.0.0') }} renders successfully with the fallback, writes a valid configuration file, notifies a handler, restarts the service, and reports changed. The service now listens on every interface instead of the one it was supposed to bind to.

Nothing failed. The run is green. The defect is a security-relevant configuration change discovered later, by someone else.

That is why the audit comes before the change rather than after, and why --check plus a full staging run is the verification step rather than “it ran fine”. A default() filter over a fact is a place where removing gathering converts a failure into a silent wrong answer, and any repository of reasonable age has several.

Order of operations

Profile. Confirm gathering is actually your largest line. If it is not, do something else.
Audit. Grep for facts, including templates, hostvars, role defaults and third-party collections. Write the list down.
Restrict, do not disable. Move to a gather_subset that covers the audited list, with a comment naming what it covers and when it was checked. This is where most of the saving is, and it is much safer than gather_facts: false.
Consider gathering = smart if the playbook has several plays over overlapping hosts. One line, no per-play edits.
Verify in staging, with --check and then a real run, watching for templates that rendered with a default() instead of a fact.
Only then consider gather_facts: false on the plays your audit proved read nothing.

Caching is a separate decision and a separate trade — it is the next lesson — and it should come after this one, because caching facts you did not need to gather is optimising the wrong thing.

Knowledge check

Why this matters

Every performance discussion about Ansible starts with concurrency and should start here. The measurement is consistent across environments and across course examples: on a play that does not do much per host, fact gathering is most of the run, and on a real fleet the network makes it worse rather than better.

It is also the only lever in this part that does not require giving something up. Raising forks costs you an accidental safety limit. free costs you the barrier. Pipelining costs you a sudoers default on every host. Caching costs you freshness. Not gathering facts nobody reads costs you nothing at all.

The catch is that “nobody reads” is a claim about a whole repository, including its templates, its role defaults and the collections it pulls in — and the way it fails is a template rendering a default() value into a config file that then restarts a service. So do the audit, write the subset with a comment saying what it covers, and verify in staging. Thirty minutes of grep buys the largest saving available, and skipping it buys a configuration defect that reports success.