Link Top tools rows to Audit events filtered by tool
The design review in #634436 (items 3 and 11) asked that the Top tools card on the AI Governance dashboard lead to the sessions that used a tool. This MR adds a Tool filter to the Audit events report and makes each Top tools row a link to that filtered report.
The toolName argument it needs lands in Add toolName filter to the AI governance sessio... (!263154). So this MR no longer targets that backend branch. It sits on Link connected agents to the Audit events tab f... (!261757 - merged), which adds the ai_governance_audit_events_filters wip flag and the filtered sessions queries, and it puts the Tool filter behind the same flag. With the flag off, nothing changes on the page and no query sends toolName.
Changes
- Audit events: a new "Tool" filter,
=only, once per search. It suggests the tool names from the Top tools card and filters them as you type. - The filter shows only when all three hold:
- the
ai_governance_sessions_apiflag is on (on by default), - the
ai_governance_audit_events_filterswip flag is on, - ClickHouse is enabled for analytics. The backend only filters by tool on ClickHouse, so both governance pages now pass
Gitlab::ClickHouse.globally_enabled_for_analytics?, the check the resolver uses.
- the
- The filter can be set from the URL with
?toolName=. AtoolNamefrom the URL is dropped when the filter is not shown, so the table never sends it. A filter from the URL is not counted in tracking; one the user applies is tracked astool_name. toolNameis passed only by the filtered sessions queries from !261757 (merged), which are listed inconfig/known_invalid_graphql_queries.ymluntil the backend is on master. The plain sessions queries are unchanged.- Top tools card: each row links to Audit events filtered by that tool, with the card's time window and agent class. The rows match the developer and project cards. Without the flag the row links to the report for the window and agent class only, as it does today without the sessions API.
- With the side panel flag on too (
ai_governance_dashboard_side_panels, wip), a row opens the sessions that called the tool in the dashboard side panel from !269500 (merged), titled with the tool, as the Top tools workflow asks (#637210). Ctrl, Cmd or Shift-click still opens the Audit events tab. Without the filters flag the row keeps its link, since the panel could not filter by tool. - Row clicks are tracked as
click_card_link_on_ai_governance_dashboardwith labeltop_toolsand propertyrow. The view-all link tracking, the event's label list and thetop_toolsmetrics come from Track AI Governance filter changes, tab clicks ... (!262793 - merged).
For example, selecting the Bash row on the last 7 days opens ?tab=agent-artifacts&toolName=Bash&startTimeAfter=2026-10-12, and the report shows only sessions that called Bash.
Decisions
- Suggestions reuse the Top tools query instead of a new search query. The names match what the card shows and nothing new runs on the server. The trade-off is that only tools used in the last 30 days are suggested.
- Links and the filter pass the recorded tool name, and the backend folds its spellings. The title on the card is for display only.
- The Tool filter shares the generic
ai_governance_audit_events_filtersflag with the Agent filter in !261757 (merged), so the frontend can merge ahead of the backend. Once !263154 and !261754 are on master, the known-invalid entries and the flag go away.
References
- Related to #634436
- Targets the branch of Link connected agents to the Audit events tab f... (!261757 - merged) (which targets
master) - Backend: Add toolName filter to the AI governance sessio... (!263154)
- Relates to #637210 (Top 7 most called tools workflow)
Open points
- Unknown tool names in the URL return no sessions. The backend decides this.
Screenshots
Side panel (flag on), on a local instance: selecting Grep opens the sessions that called it, filtered by Tool and the card's window.
Group dashboard, 1440px wide, super sidebar open. Both "after" images are mocks: the change applied to the same page in the browser.
Top tools card
| Before | After (mock) |
|---|---|
![]() |
![]() |
Audit events filter bar
The after image shows a Tool = mcp__everything__echo chip.
| Before | After (mock) |
|---|---|
![]() |
![]() |
How to set up and validate locally
You need the backend from !263154, or the offsite demo branch that includes it, and ClickHouse enabled for analytics.
- Enable
ai_governance_sessions_apiandai_governance_audit_events_filtersfor the group. - Open the AI Governance dashboard of
your-group, with agent sessions that used tools. - Select a row on Top tools. The Audit events tab opens with a Tool filter for that tool and the card's time window.
- On Audit events, add the Tool filter and pick a suggestion, or type a tool name.
- Disable
ai_governance_audit_events_filters: the Tool filter is gone and Top tools rows link to the unfiltered report.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist.




