Spike: Move analytics instrumentation CLI from GitLab monolith to GDK

Overview

This spike investigates moving the analytics instrumentation CLI from the GitLab monolith to GDK to enable support for external projects like AI Gateway. This is a prerequisite for implementing CLI support for AI Gateway as described in #583437.

Problem Statement

Currently, the analytics instrumentation CLI is tightly coupled to the GitLab monolith, making it difficult to extend support to external projects like AI Gateway. Before implementing event generation for concrete external projects, we need to validate that moving the CLI to GDK is technically feasible and provides the desired UX improvements.

Goals

  1. Validate technical feasibility of moving CLI to GDK
  2. Establish project selection UX that allows users to choose which service they're working with
  3. Prove configuration management for multiple projects with different requirements
  4. Test schema validation across different project types

Proposed Approach

UX Design

From a user experience perspective, setting up CLI for a new satellite service should include:

  • Define schema requirements [Project-dependent]
  • Add usage examples [Project-dependent]
  • Add testing examples [Project-dependent]
  • Define where definitions should be created [Project-dependent, user-dependent]
  • Enable instrumentation MR reviews [Danger-bot dependent]

Technical Implementation

  • Move CLI to GDK as gdk internal-events-cli
  • Add project selection flow within the CLI (no command line args needed)
  • Support local configuration in gdk.yml for project paths and defaults
  • Dynamic schema loading from each repo's config/events directories

Example User Flow 

$ gdk internal-events-cli

Welcome to the CLI! Which project is this for?

  gitlab (/Users/person/workspace/gitlab-development-kit/gitlab)
  ai-gateway (/Users/person/workspace/ai-gateway)
> switchboard (you'll be prompted to define the project directory next)

-------

Input absolute path to switchboard repo:
> /Users/person/workspace/switchboard

Configuration Example 

internal_events: 
  ai-gateway: 
    path: /Users/person/workspace/ai-gateway
    defaults:
      tiers: 
        - ultimate
  switchboard: 
    path: /Users/person/workspace/switchboard
  defaults:
    product_group: analytics_instrumentation

Success Criteria

  • CLI successfully runs from GDK with gdk internal-events-cli
  • Project selection flow works for multiple projects
  • Configuration can be saved and retrieved from gdk.yml
  • Schema validation works for different project types
  • Event definitions can be generated for external projects
  • No major technical blockers identified

Technical Considerations

Advantages

  • Universal availability through GDK
  • Consistent updates across projects
  • Clear separation from GitLab monolith
  • Establishes CLI as service-agnostic

Potential Challenges

  • Departure from typical GDK command usage patterns
  • Team lacks GDK maintainer expertise (dependency on others for changes)
  • Need to handle different validation requirements per project
  • Schema versioning for self-managed instances

Constraints

  • Most CLI complexity is tied to metrics, not events
  • Different projects have varying event definition requirements
  • Multiple schema versions may need to exist for validation
  • CLI should always use latest validation

Proof of Concept

Initial POC available at: gitlab-development-kit@main...sy-relocate-cli-to-gdk

  • Functional with gdk internal-events-cli
  • Uses GitLab repo's event schema with conditionals
  • Demonstrates project selection flow

Next Steps

  1. Complete technical spike implementation
  2. Test with AI Gateway project structure
  3. Validate schema loading from external projects
  4. Document findings and recommendations
  5. If successful, proceed with full implementation for #583437

Related Issues

Edited by 🤖 GitLab Bot 🤖