Loading
Add toolName filter to the AI governance sessions GraphQL field
The design review on #634436+ asks that a row on the Top tools used by agents card open the Audit events tab filtered to that tool. This adds the backend for it: a toolName argument on the aiGovernanceSessions GraphQL field, for groups and projects, that returns the sessions that called the tool.
How it matches
- The name is the one the Top tools card shows. The filter matches the same recorded names the card folds into that row, derived by inverting the card's own mapping (
GovernedMcpTools#recorded_names_for): the name itself plus every spelling, prefixed or bare, that only that rule governs. A spelling several rules share, such asgitlab_save_work_item, stays its own row on the card and matches only itself here, so a row opens exactly the sessions it counted. - A session called the tool when it has a tool call event (
ai_tool_invokedorai_claude_tool_invoked) with that name. The tool name is read the same way as on the Tool calls cards. - A GitLab Duo session's events carry its workflow. A connected agent's events carry the session id. The filter checks both.
- The event search stays inside the group's path. It starts at
sessionStartedAfterwhen that is given, since a session's events never come before it starts. - An unknown name returns no sessions and no error.
PostgreSQL
- Without ClickHouse,
toolNameis unsupported: the field returns an argument error,Filtering by toolName requires ClickHouse to be enabled for analytics., instead of ignoring the filter and returning every session. The PostgreSQL sessions path from Fall back to PostgreSQL for AI governance sessi... (!259922 - merged) has no tool call events to filter on, and the dashboard never sendstoolNamewithout ClickHouse because the Top tools card returns null there. - On Database Lab,
ai_audit_eventsis empty on GitLab.com, so the PostgreSQL side cannot be measured at scale. Reading the largest group's sessions for 30 days alone took 8.6 s cold, past the 4.5 s read timeout. A PostgreSQL path can follow once it is measured on self-managed sized data.
Query
ClickHouse query and local plan
-- added to the existing sessions query
AND (
workflow_id IN (
SELECT workflow_id FROM ai_audit_events
WHERE startsWith(traversal_path, '<group traversal path>')
AND event_name IN ('ai_tool_invoked', 'ai_claude_tool_invoked')
AND coalesce(nullIf(JSONExtractString(details, 'tool_name'), ''),
JSONExtractString(details, 'name')) IN ('<name>', '<spellings>')
AND workflow_id != 0
AND created_at >= '<sessionStartedAfter>')
OR id IN (
SELECT ai_governance_session_id FROM ai_audit_events
WHERE <the same conditions> AND ai_governance_session_id != 0))Locally, both event subqueries prune by partition and by the primary key on traversal_path and created_at; the workflow one also uses workflow_id. A plan at scale is still to do with the ClickHouse review.
Reviews needed
- ClickHouse review: two new subqueries on
ai_audit_events.
Out of scope
- The Tool token on the Audit events tab and the Top tools row links, in a follow-up MR stacked on this one.
- Tool calls by risk: its slices group many tools by what they do, so it needs an
actionTypefilter, in a later MR.
Verification
- Specs for the ClickHouse finder, both resolvers and
GovernedMcpTools: 91 examples pass. The finder cases forgitlab_save_work_item(must not matchcreate_work_item) and the bare aliasget_workitem_notes(must matchget_work_item_notes), and the resolver case without ClickHouse, all fail without the change. - Both mappings were run against the real MCP tool catalog in
rails runner: the oldspellings_forfilter disagreed with the card on 17 rows, the newrecorded_names_foron none. - GraphQL docs and introspection regenerated.
Related to #634436+.
Edited by Dheeraj Joshi