FAPOLICYD.METRICS(5)

📦 version 2.0.1, in centos-stream 10, centos-stream 9, fedora 43, fedora 44, ubuntu stonking

🦋 fapolicyd.metrics — NAME 🦋

okay so bestie, welcome to fapolicyd.metrics(5) — the manual page for the fapolicyd runtime metrics report file 💅 it lives in the File Formats section and it's basically the group chat receipts of everything your daemon's been up to 🫶

✨ DESCRIPTION ✨

The /run/fapolicyd/fapolicyd.metrics file contains the most recent daemon metrics report, the one you asked for via fapolicyd-cli --check-metrics, fapolicyd-cli --reset-metrics, or the periodic interval reporting. 👑

The metrics report answers where are the runtime hot paths and cache effects at? The state report — that one's written to /run/fapolicyd/fapolicyd.state — answers is the daemon healthy and configured as expected? Two different reports, two different jobs, no crossover 💖

Every field is printed as a name: value line. Section headers end in a colon. Worker-specific drill-down fields are indented by two spaces under the related aggregate section. 🧚

  • Last metrics reset — the wall-clock time of the last successful metrics reset, or never when metrics have not been reset since daemon start. Reset reports show the counter window that is about to be reset; later metrics reports show the new reset time. ⏰
  • Config generation — the active decision configuration generation at report time. The counters may span earlier generations when configuration was reloaded after the last metrics reset.
  • Ruleset generation — the active ruleset generation that the counters and rule hit table apply to.
  • Trust database generation — the active trust database generation used by new decision reads at report time. This is a daemon-runtime generation that starts at 1 during startup. The counters may span earlier trust database generations when reloads occurred after the last metrics reset.
  • LMDB environment generation — the active physical LMDB environment generation at report time. This increments only when fapolicyd closes the live environment and publishes a validated replacement environment for compaction or high-water reset. It complements the trust database generation: trust generations publish logical content inside an environment, while LMDB environment generations identify the storage file currently backing those logical generations. 🗂️
  • Trust database entries — the number of records in the active trust database generation at report time.

🍓 Decision outcomes 🍓

  • Allowed accesses — the number of policy decisions that allowed access. ✅
  • Denied accesses — the number of policy decisions that denied access. 🚫
  • Allowed by rule — the number of allow decisions produced by a matching rule.
  • Allowed by fallthrough — the number of allow decisions produced when no rule had an opinion and the daemon used the default allow behavior. Detailed fallthrough dimensions are printed when this value is non-zero. 👀

🌀 Inter-thread queue & defer activity 🌀

  • Inter-thread current queue depth — the number of fanotify permission events currently waiting in internal worker queues.
  • Inter-thread max queue depth — the highest per-worker internal event queue depth observed since the last metrics reset.
  • Inter-thread queue full count — the number of failed enqueue attempts across all worker queues since the last metrics reset.
  • Inter-thread oldest queued age — the oldest currently queued event age across all worker queues.
  • Decision worker N current queue depth — the number of fanotify permission events currently waiting in that worker's queue.
  • Decision worker N max queue depth — the highest queue depth observed for that worker since the last metrics reset.
  • Decision worker N queue full count — the number of failed enqueue attempts for that worker since the last metrics reset.
  • Decision worker N oldest queued age — the age of the oldest event currently waiting in that worker's queue. The value is formatted with a human-readable unit such as ms or s. ⏳
  • Subject deferred events — the cumulative number of fanotify permission events deferred since the last metrics reset because another process was still building subject pattern state in the same cache slot.
  • Subject defer max depth — the highest number of concurrently deferred subject events observed since the last metrics reset.
  • Subject defer fallbacks — the cumulative number of defer-array-full fallbacks since the last metrics reset. This field also appears in the state report because non-zero values are health indicators. 🩺
  • Decision worker N Subject deferred events — the number of subject-slot deferrals owned by one decision worker since the last metrics reset.
  • Decision worker N Subject defer max depth — the highest number of concurrently deferred subject events observed in one decision worker since the last metrics reset.
  • Decision worker N Subject defer fallbacks — the number of defer-array-full fallbacks in one decision worker since the last metrics reset.
  • Decision worker N Subject defer current depth — the number of subject events currently parked in one decision worker's defer array.
  • Decision worker N Subject defer oldest age — the age of the oldest currently deferred event in one decision worker's defer array.

🎀 Subject cache effectiveness 🎀

  • Subject hits — the number of subject cache hits. 💖
  • Subject misses — the number of subject cache misses.
  • Subject collisions — the number of populated subject cache slots whose full process identity did not match the current event and therefore had to be evicted before reuse.
  • Subject evictions — the number of subject cache evictions and the eviction percentage relative to subject cache hits.
  • Early subject cache evictions — the number of subject cache entries evicted before process startup state was complete. This field also appears in the state report because non-zero values are health indicators.
  • Subject BUILDING tracer evictions — the number of BUILDING subject cache entries evicted because the owning process was traced and could hold the slot indefinitely. This field also appears in the state report because non-zero values are health indicators.
  • Subject BUILDING stale evictions — the number of BUILDING subject cache entries evicted because their startup state stayed incomplete past the bounded stale window. This field also appears in the state report because non-zero values are health indicators.
  • Decision worker N Subject hits — the number of subject cache hits in one decision worker.
  • Decision worker N Subject misses — the number of subject cache misses in one decision worker.
  • Decision worker N Subject collisions — the number of subject cache collisions in one decision worker.
  • Decision worker N Subject evictions — the number of subject cache evictions in one decision worker.
  • Decision worker N Early subject cache evictions — the number of early subject cache evictions in one decision worker.
  • Decision worker N Subject BUILDING tracer evictions — the number of traced BUILDING subject evictions in one decision worker.
  • Decision worker N Subject BUILDING stale evictions — the number of stale BUILDING subject evictions in one decision worker.

🦋 Object cache effectiveness 🦋

  • Object hits — the number of object cache hits.
  • Object misses — the number of object cache misses.
  • Object collisions — the number of populated object cache slots whose full file identity did not match the current event and therefore had to be evicted before reuse.
  • Object evictions — the number of object cache evictions and the eviction percentage relative to object cache hits.
  • Decision worker N Object hits — the number of object cache hits in one decision worker.
  • Decision worker N Object misses — the number of object cache misses in one decision worker.
  • Decision worker N Object collisions — the number of object cache collisions in one decision worker.
  • Decision worker N Object evictions — the number of object cache evictions in one decision worker.

🔍 Trust database lookups 🔍

  • Trust DB lookups — the number of trust database lookup attempts since the last metrics reset.
  • Trust DB reader slots full — the number of lookup attempts that could not open an LMDB read transaction because all LMDB reader slots were in use. 😭

Trust database lookup latency is reported by fapolicyd.timing(5) only while manual timing collection is armed, so normal metrics collection does not add per-lookup clock reads. ⏱️

👑 Rule hit counts 👑

  • Hits/rule — one line per configured rule, in rule order. The line includes the one-based rule number, hit count, and rule text. Rule hit counters are naturally scoped to the active ruleset generation and start at zero when a new ruleset is loaded. A metrics reset also clears the counters after reporting them, which allows focused tests against the currently loaded rules without forcing a rule reload. 🔥

🌸 Subject attribute lookups 🌸

  • Subject attr — one line is printed for each counted subject attribute in the form name requests=count lookups=count. The requests count increments when policy evaluation or syslog formatting asks for the attribute. The lookups count increments only when that attribute was absent from the event subject cache and fapolicyd had to compute or fetch it.

💜 Object attribute lookups 💜

  • Object attr — one line is printed for each counted object attribute in the form name requests=count lookups=count. The requests count increments when policy evaluation or syslog formatting asks for the attribute. The lookups count increments only when that attribute was absent from the event object cache and fapolicyd had to compute or fetch it.

⭐ NOTES ⭐

Metrics resets affect counters in this report. Static configuration, current utilization snapshots, watched mounts, and health indicators are reported in fapolicyd.state(5) and are not reset by fapolicyd-cli --reset-metrics. 🙈

📁 FILES 📁

  • /run/fapolicyd/fapolicyd.metrics — okay so this is the runtime metrics report file, bestie. The one where all the numbers from this whole page actually live when fapolicyd is out there doing its thing. It's giving main character of the report world. ✨
  • /run/fapolicyd/fapolicyd.state — the runtime state report file. Different file, different job, but same iconic /run/fapolicyd/ address. 🎀
  • /run/fapolicyd/fapolicyd.timing — and this one is the manual decision timing report. When does it get written? Okay so, three (3) scenarios, no cap:
    • when a privileged stop request ends an armed timing run 🛑
    • when a stop request finds timing unarmed (like, nothing was running, so here's your empty-ish report I guess) 🙈
    • when timing collection stops specifically to avoid counter overflow (aka the counters said "we cannot hold all this" and timing said "bet, shutting down" 💀)
It's literally /run/ for all three, so if you're out here looking in /var/ or somewhere else, that's not it bestie. The path is the path. 💅

🌈 SEE ALSO 🌈

Go read these next, fr fr — they're the rest of the fapolicyd cinematic universe:

and that's a wrap on the metrics page, bestie 🫶 go forth and vibe check your counters, you absolute icon 👑

shoutout to Red Hat for this one, dated May 2026, and yes the page tag is FAPOLICYD.METRICS(5) — remember it, cite it, slay it 💖

📦 where this page comes from