What fact gathering actually costs · Ansible

Every play you have written so far started with a task you did not write.

PLAY [configure web tier] ******************************************************

TASK [Gathering Facts] *********************************************************
ok: [web01]
ok: [web02]

That task is ansible.builtin.setup, and Ansible inserts it because gather_facts defaults to true. It runs against every host in the play, before your first real task, and it does the full work of a module: build the payload, open a connection, copy, execute under the target’s Python, parse JSON back.

Most people meet this as a line of output they scroll past. On a fifty-host inventory it is a second or two and nobody notices. On two thousand hosts it is frequently the largest single item in the run, and it happens before you have changed anything at all.

This lesson measures it rather than asserting it, because “gathering is slow” is the kind of claim that gets repeated into folklore and then used to justify gather_facts: false everywhere, which breaks things in ways the next lessons have to clean up.

What the implicit task is

setup is an ordinary module. It runs on the target, collects information about the system, and returns it under the ansible_facts key. Ansible then merges that dictionary into the host’s variables, which is why ansible_facts.distribution is available to every subsequent task without you doing anything.

Three play keywords control it, and all three are genuine play-level keywords rather than module arguments:

Keyword	Type	Default	What it does
`gather_facts`	bool	true	Whether the implicit `setup` task runs at all
`gather_subset`	list	`all`	Which categories of facts to collect
`gather_timeout`	int	10	Per-subset timeout in seconds
`fact_path`	string	`/etc/ansible/facts.d`	Where custom local facts are read from

Read-only / Safethe keywords are real, and this is how to check— ansible-doc -t keyword prints the authoritative definition of a play or task keyword, including which level it applies to. Faster and more reliable than searching documentation.

$ ansible-doc -t keyword gather_facts gather_subset gather_timeout

gather_facts:
applies_to:
- Play
description: A boolean that controls if the play will automatically run the 'setup'
  task to gather facts for the hosts.
type: bool
gather_subset:
applies_to:
- Play
description: Allows you to pass subset options to the fact gathering plugin controlled
  by 'gather_facts'.
type: list
gather_timeout:
applies_to:
- Play
description: Allows you to set the timeout for the fact gathering plugin controlled
  by 'gather_facts'.
type: int

Note applies_to: Play. These are not task keywords. You cannot put gather_subset on an individual task — to gather a different subset mid-play you call the setup module explicitly as a task, which is a different thing and is covered in lesson 5.

The measurement

Here is the experiment, run on ansible-core 2.21.3. Fifty hosts, forks: 5, a play whose only real task is a debug that does nothing. The connection is local, so there is zero network latency — this is the floor, not a typical case.

Read-only / Safethree identical plays, three gathering settings— The same fifty-host play run with full gathering, with the minimal subset, and with gathering disabled. Nothing but a debug task in each.

$ for p in gather_all gather_min gather_none; do /usr/bin/time -f '%e s' ansible-playbook -i bench.ini -f 5 $p.yml; done

--- gather_all      (gather_facts: true)
7.65 s
7.20 s
--- gather_min      (gather_subset: ['!all'])
3.50 s
3.19 s
--- gather_none     (gather_facts: false)
0.40 s
0.42 s

Read that carefully. The play that does nothing takes 0.4 seconds. Add full fact gathering and it takes 7.2 seconds. Gathering is 94% of the run.

The minimal subset — everything except the expensive collectors — costs 3.2 seconds, so restricting the subset saved more than half the gathering time without disabling it.

Where the time goes

The subsets are not equal. Counting the facts each one returns shows where the weight sits:

Read-only / Safefact count by subset— Runs the setup module directly with different gather_subset values and counts the returned keys. setup is read-only; it collects information and changes nothing.

$ for s in all '!all' '!all,!min' network hardware; do ansible localhost -m ansible.builtin.setup -a "gather_subset=$s"; done

all         -> 121 keys
!all        ->  55 keys
!all,!min   ->   2 keys
network     ->  76 keys
hardware    ->  90 keys

Full gathering returns 121 top-level facts. The min subset — what you get from !all — returns 55, and covers essentially everything a typical play branches on: distribution, kernel, hostname, service manager, package manager, Python, user identity, SSH host keys.

The remaining 66 facts are the expensive ones. hardware enumerates block devices, mounts and memory. network enumerates every interface and address. Those two collectors are where the seconds are, and they are also the two that most plays never read.

Verified against 2.21.3:

Read-only / Safeexactly one collector— Requests the distribution subset and nothing else. The returned dictionary is the whole answer: eight distribution facts plus the two bookkeeping keys.

$ ansible localhost -m ansible.builtin.setup -a "gather_subset=!all,!min,distribution"

localhost | SUCCESS => {
  "ansible_facts": {
      "ansible_distribution": "Ubuntu",
      "ansible_distribution_file_parsed": true,
      "ansible_distribution_file_path": "/etc/os-release",
      "ansible_distribution_file_variety": "Debian",
      "ansible_distribution_major_version": "26",
      "ansible_distribution_release": "resolute",
      "ansible_distribution_version": "26.04",
      "ansible_os_family": "Debian",
      "gather_subset": [
          "!all",
          "!min",
          "distribution"
      ],
      "module_setup": true
  },
  "changed": false
}

Writing it in a play

Restricting the subset is a two-line change at play level:

Read-only / Safesite.yml— A play that branches only on OS family. Gathering the distribution collector is sufficient and costs a fraction of the default.

- name: Deploy the agent
hosts: appservers
gather_subset:
  - '!all'
  - '!min'
  - distribution
  - pkg_mgr
tasks:
  - name: Install the agent package
    ansible.builtin.package:
      name: monitoring-agent
      state: present

Two habits make this maintainable rather than a micro-optimisation someone reverts in six months:

Quote the negations. !all starts with ! and YAML will not parse it bare in some contexts. Always quote subset entries that begin with !. This is the same YAML rule covered in the YAML part, and it bites here more often than anywhere else.

Write down which facts the play needs. A comment naming the facts the play reads turns the subset list from a magic incantation into something a reviewer can check. When someone later adds a task that reads ansible_facts.mounts, the subset list is where the bug will be, and a comment is what makes that obvious.

`gather_timeout` and the host that hangs

gather_timeout defaults to 10 seconds and applies per fact collector, not to the gathering task as a whole.

That default is usually right and occasionally catastrophic. The classic case is hardware on a host with a hung NFS mount: the collector walks the mount table, stat() blocks on the dead mount, and the collector burns its full ten seconds before giving up. Multiply by the number of affected hosts, divide by forks, and a routine run becomes a long one.

Raising gather_timeout is almost always the wrong fix. It makes the run slower and hides the real problem, which is a broken mount. The right responses, in order of preference:

Fix the host. A hung mount is an incident, not a gathering setting.
Exclude the collector you do not need — '!hardware' — so the play stops touching the broken thing at all.
Raise the timeout only if you genuinely need the facts from a host that is legitimately slow to answer.

Under the hood

gather_facts is not hard-wired to the setup module. It is dispatched through the gather_facts action, which selects one or more fact modules and runs them. On a normal Linux host that resolves to ansible.builtin.setup; on a network device it resolves to that platform’s fact module instead.

That indirection is why the keyword is gather_facts and the module is setup — they are deliberately different names for deliberately different things.

The dispatcher can run several fact modules in parallel, and upstream is explicit that this is not automatically faster: “for low cost or delay fact modules parallelism overhead might end up meaning the whole process takes longer”. When several fact modules run in parallel, order is not guaranteed and conflicting keys resolve as last-merged.

For a single-module Linux host none of this applies, which is why the measurement above is a clean read on the setup module itself.

When `gather_facts: false` is the right call

Disabling gathering entirely is correct more often than its reputation suggests, and wrong in one specific way that costs people an afternoon.

Correct when the play reads no facts. A play that restarts a service by name, or copies a file to a fixed path, or runs a health check against a URL, reads nothing the setup module produces. Gathering for it is pure cost. This is most of what an operational runbook play does.

Correct on a host with no Python. setup needs a Python on the target. Bootstrap plays that install Python with raw must disable gathering, because the gathering task would fail before the bootstrap task ran. This is covered in the interpreter part; the gathering consequence belongs here.

Correct when facts come from cache. If a fact cache is configured and populated, gathering: smart will skip the gathering task for hosts it already has facts for. That is lesson 5, and it is the setting that lets you keep facts and stop paying for them on every run.

Wrong when a module gathers on your behalf. This is the one that catches people. Upstream documents it plainly for ansible.builtin.package: it selects the underlying package manager from facts, and “if ansible.builtin.setup was not yet run, ansible.builtin.package will run it”.

So a play with gather_facts: false whose first task is package gathers facts anyway — just later, and without any of the subset restrictions you set at play level, and with the cost hidden inside a task that appears to be doing something else. The run is not faster. It is the same cost, harder to see.

The blast-radius reading of a gathering task

Gathering Facts is also the first honest statement of how many hosts the play is about to touch. Before it runs, the host list is a pattern; after it runs, you have ok: lines for every host that answered and unreachable: for every one that did not.

That is worth something operationally. On a run where the host list is the risk — and on a large fleet it usually is — the gathering task is a free reachability check across the whole target set before any change happens.

When you disable gathering on a play that changes things, you lose that checkpoint. --list-hosts gives you the intended list and ansible <pattern> -m ansible.builtin.ping gives you the reachable one; run one of them first. The habit costs seconds and it is the cheapest blast-radius control in the course.

A decision you can apply

For any play, in order:

Does it read facts at all? Grep the play and its roles for ansible_facts and ansible_. If nothing, gather_facts: false and move on — but check for a package, service or setup task that will gather implicitly.
Which facts does it read? Map each to a collector. Distribution branching needs distribution. Choosing a package manager needs pkg_mgr. Interface addresses need network. Disk checks need hardware.
Set the subset explicitly, with a comment naming why.
Measure, on your own inventory, before and after. If the saving is a tenth of a second, put the default back and spend the attention elsewhere.

Step 4 matters as much as the rest. Restricting the subset on a twelve-host inventory is a change with a cost — a future reader has to understand it — and no benefit. Fleet-scale reasoning applied at small scale is just complexity.