Improve AI Catalog metrics: Where context is single item always track item ID, and foundational properties

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

About

Some of our events in ee/config/events/ (search for "ai_catalog") operate on single items and currently all capture the AI catalog item type.

But we are missing more specific information about the item that would let us filter/splice the data by

  • Event data filtered for a specific custom item
  • Event data filtered for a specific foundational item
  • Event data filtered by foundational items as a whole
  • Event data filtered by custom items as a whole

Proposal

Update our events that fire where there is a single item in context, ensuring they all track:

Property key name Description
item_id (Numeric|null) The item's PostgreSQL ID (some events do track this already). Note, value will be null for any foundational item that does not exist in the database (example: some foundational agents).
foundational_item_ref (String|null) The item's "foundational item reference", when the item is a foundational item. Note, value will be null when item is not foundational.
foundational (Boolean) A boolean that is true when item is foundational and false when not.

For example, see !224303 (merged) that adds foundational (boolean) and foundational_item_ref (string) to an existing event.

At the time of writing (March 2026), the metrics we can apply these to are:

  • click_enable_ai_catalog_item_button
  • click_duplicate_ai_catalog_item_button
  • click_disable_ai_catalog_item_button
  • click_delete_ai_catalog_item_button
  • view_ai_catalog_item
  • view_ai_catalog_project_managed
  • create_ai_catalog_item_consumer
  • update_ai_catalog_item_consumer
  • delete_ai_catalog_item_consumer
  • create_ai_catalog_item
  • update_ai_catalog_item
  • delete_ai_catalog_item
  • trigger_ai_catalog_item (being updated in !224303 (merged))

Note, the existing issue Improve Item Consumer event metric tracking to ... (#578615) can be responsible for adding this to item consumer events if it is implemented after this one.

See https://docs.gitlab.com/development/internal_analytics/internal_event_instrumentation.

We should update the AI instrumentation documentation with this convention (see #591972 (comment 3237632874) for context).

Edited by Luke Duncalfe