Internal events

The schemaful product analytics framework that replaces older "usage data" counters.

Source

Concern	Location
Core API	lib/gitlab/internal_events.rb (~8K LoC)
Tracking concern	lib/gitlab/internal_events_tracking.rb
Event definitions	config/events/ (large directory of YAML schemas)
Metric definitions	config/metrics/
Generator	bin/rails generate gitlab:internal_event …

Why

The legacy "Service Ping" / Gitlab::UsageData (lib/gitlab/usage_data.rb, ~25K LoC) generated weekly counter snapshots by running expensive SQL across the database. The new system:

• Writes each event individually as it happens.
• Routes events to Snowplow and ClickHouse for real-time analytics.
• Has stronger schemas and lifecycle.

Defining an event

A YAML in config/events/ declares the event:

description: Track when a user creates a project
internal_events: true
action: create_project
identifiers:
  - user
  - project
  - namespace
product_group: source code
product_categories:
  - groups_and_projects
milestone: '17.0'

A YAML in config/metrics/ declares a metric derived from one or more events.

Tracking an event

Gitlab::InternalEvents.track_event(
  'create_project',
  user: current_user,
  project: project
)

Why "internal"

Events are "internal" because they're emitted by the GitLab application itself, not by external integrations. The framework sends them to:

• Snowplow (in production).
• ClickHouse (for self-managed analytics dashboards).
• Local stdout (in development).

Service Ping integration

A Sidekiq cron job aggregates internal events into the weekly Service Ping payload submitted to Versions.gitlab.com. Self-managed operators can opt out of Service Ping; they still keep their local ClickHouse data.

Related

• ClickHouse — the OLAP store.
• Database.