__add_metric(9)

✨ __add_metric(9) ✨

okay so bestie, welcome to __add_metric — literally the function whose whole job is "Add a metric to metric_list." that's it, that's the vibe 💅 it lives in the Kernel API Manual, and if you're reading this you're probably deep in perf internals, so let's go 🫶

🌸 SYNOPSIS 🌸

int __add_metric (struct list_head *metric_list , const struct
pmu_metric *pm , const char *modifier , bool metric_no_group , bool
metric_no_threshold , int runtime , const char *user_requested_cpu_list
, bool system_wide , struct metric *root_metric , const struct
visited_metric *visited , const struct pmu_metrics_table *table );

it's giving "eleven arguments and every single one of them matters" 😭 ngl that's a lot of params, but we're gonna walk through all of them, no skips ✨

🎀 ARGUMENTS 🎀

• metric_list — the list the metric is added to. this is the destination, the group chat the metric is getting added to 💖
• pm — the pmu_metric containing the metric to be added. it's the actual metric being added, the main character 👑
• modifier — if non-null, event modifiers like "u". so like, optional extra flavour on the event 🔥
• metric_no_group — should events written to events be grouped "{}" or global. grouping is the default, but due to multiplexing the user may override. so basically: grouping on by default, but the user gets to be the boss of it 😌
• metric_no_threshold — should threshold expressions be ignored? yes/no, that's the whole question. lowkey simple, highkey important 🧚
• runtime — a special argument for the parser only known at runtime. so it's not known at compile time, it's a runtime thing, iykyk 🦋
• user_requested_cpu_list — command line specified CPUs to record on. the user said "these CPUs" and we listen 💜
• system_wide — are events for all processes recorded. like, everyone, all processes, system-wide, no cap 🌈
• root_metric — metrics may reference other metrics to form a tree. in this case the root_metric holds all the IDs and a list of referenced metrics. when adding a root this argument is NULL. it's literally the tree trunk of the metric tree 🌳✨
• visited — a singly linked list of metric names being added that is used to detect recursion. yes bestie, recursion detection — we do NOT want the metrics referencing each other in an infinite loop, that's giving chaos 😭⚠️
• table — the table that is searched for metrics, most commonly the table for the architecture perf is running upon. so like, "which arch are we on? that table then" 💀

🦋 SEE ALSO 🦋

go look at the kernel file ./tools/perf/util/metricgroup.c and also these iconic siblings:

• setup_metric_events(9)
• resolve_metric(9)
• metric_list_cmp(9)
• default_metricgroup_cmp(9)
• metricgroup__add_metric(9)
• metricgroup__add_metric_list(9)
• find_tool_events(9)
• build_combined_expr_ctx(9)
• parse_ids(9)

ok that's the whole page bestie 💖 every argument, every default, every "NULL when adding a root" caveat — all of it, no details skipped, we ate and left no crumbs 🍓

and that's a wrap! shoutout to ./tools/perf/util for being the source, October 2026 for the date, and __add_metric(9) for the manual page energy — periodt 💅🎀✨