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_api flag is on (on by default),
    • the ai_governance_audit_events_filters wip 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 filter can be set from the URL with ?toolName=. A toolName from 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 as tool_name.
  • toolName is passed only by the filtered sessions queries from !261757 (merged), which are listed in config/known_invalid_graphql_queries.yml until 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_dashboard with label top_tools and property row. The view-all link tracking, the event's label list and the top_tools metrics 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_filters flag 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

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.

10-top-tool-opens-sessions-in-panel

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)
Top tools card without row links Top tools card with row links

Audit events filter bar

The after image shows a Tool = mcp__everything__echo chip.

Before After (mock)
Audit events filter bar without a Tool token Audit events filter bar with a Tool chip

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.

  1. Enable ai_governance_sessions_api and ai_governance_audit_events_filters for the group.
  2. Open the AI Governance dashboard of your-group, with agent sessions that used tools.
  3. Select a row on Top tools. The Audit events tab opens with a Tool filter for that tool and the card's time window.
  4. On Audit events, add the Tool filter and pick a suggestion, or type a tool name.
  5. 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.

Edited by Dheeraj Joshi

Merge request reports

Loading
Loading