Register the Agent Platform token usage event and setting ahead of use

Andrew Dunnrequested to merge
feature/register-agent-platform-token-usage-event into master

What does this MR do and why?

Registers the AI usage event report_agent_platform_token_usage, ID 59, and the setting key that will gate it, a release before a follow-up MR records the event. A node on the previous release can then drain, read and save what newer nodes write (expand and contract). Nothing in this MR fires the event or reads the setting. The event's Service Ping metric and the setting's API parameter and admin control ship with the MR that does.

  • The event definition, its register_feature(:agent_platform) entry and its AiUsageEventType value. Without them, the write buffer drain raises '59' is not a valid event and keeps the batch, and the instance aiUsageData query cannot return the row.
  • The transformation keeps the Agent Platform session events' fields (project_id, session_id, flow_type, environment) and the per-model usage map that !259436 (merged) writes for GitLab Duo Non-Agentic Chat.
  • ID 58 is claimed by !259032.
  • The duo_agent_platform_token_usage_tracking_enabled key in the AI feature settings schema, separate from the Non-Agentic Chat setting. The schema rejects keys it does not list, so without it a node on the previous release could not save a settings row that carries the key.

The generated GraphQL reference and introspection result gain the enum value, two sort values and two count fields. agentPlatformUserMetrics.reportAgentPlatformTokenUsageEventCount counts. agentPlatformMetrics.reportAgentPlatformTokenUsageSessionEventCount reads null, as the three subscription events' fields do, because that count service maps only the six session events. The event stays out of the agent_platform_sessions ClickHouse materialized view, which selects those six by ID.

Release path

flowchart LR
  X["This MR merges<br/>milestone 19.6"] --> RC["19.6 release candidate"]
  RC --> M["Recording MR merges<br/>milestone 19.7"]
  M --> R["19.7 released"]
  M -.-> W1["GitLab.com deploy or rollback:<br/>every node knows event 59<br/>and the setting key"]
  R -.-> W2["Upgrade 19.6 to 19.7:<br/>19.6 nodes drain, read and save<br/>what 19.7 nodes write"]

References

How to set up and validate locally

With ClickHouse running, run bundle exec rspec ee/spec/models/ai/setting_spec.rb ee/spec/graphql/types/analytics/ai_usage/ai_usage_event_type_enum_spec.rb ee/spec/lib/gitlab/tracking/ai_tracking_spec.rb ee/spec/requests/api/graphql/analytics/ai_analytics/ai_user_metrics_spec.rb.

For the setting key, no ClickHouse is needed: in a Rails console, Ai::Setting.new(feature_settings: { 'duo_agent_platform_token_usage_tracking_enabled' => false }).tap(&:valid?).errors[:feature_settings] returns ["must be a valid json schema"] on master and [] on this branch.

On a cloud-native GitLab instance, one buffered event 59 with a usage map and the session fields:

Step Master This MR
Write buffer drain ArgumentError: '59' is not a valid event, and the batch goes back into the buffer one row
Instance aiUsageData once the row exists Cannot return null for non-nullable field AiInstanceUsageEvent.event the row, with usage and the session fields in extras

An AI coding assistant wrote this change and ran RSpec, RuboCop, the coverage check and the GraphQL documentation check on a source development VM, and the drain and read above on that instance, deployed with caproni.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Merge request reports