Event definition guide

The event dictionary is a work in progress, and this process is subject to change.

This guide describes the event dictionary and how it’s implemented.

Event definition and validation

This process is meant to document all internal events and ensure consistency. Every internal event needs to have such a definition. Event definitions must comply with the JSON Schema.

All event definitions are stored in the following directories:

Each event is defined in a separate YAML file consisting of the following fields:

Field Required Additional information
description yes A description of the event.
internal_events no Always true for events used in Internal Events.
category no Required for legacy events. Should not be used for Internal Events.
action yes A unique name for the event. Only lowercase, numbers, and underscores are allowed. Use the format <operation>_<target_of_operation>_<where/when>.

Ex: publish_go_module_to_the_registry_from_pipeline
<operation> = publish
<target> = go_module
<when/where> = to_the_registry_from_pipeline.
identifiers no A list of identifiers sent with the event. Can be set to one or more of project, user, or namespace.
product_section yes The section.
product_stage no The stage for the event.
product_group yes The group that owns the event.
milestone no The milestone when the event is introduced.
introduced_by_url no The URL to the merge request that introduced the event.
distributions yes The distributions where the tracked feature is available. Can be set to one or more of ce or ee.
tiers yes The tiers where the tracked feature is available. Can be set to one or more of free, premium, or ultimate.

Example event definition

This is an example YAML file for an internal event:

description: A user visited a product analytics dashboard
internal_events: true
action: visit_product_analytics_dashboard
- project
- user
- namespace
product_section: dev
product_stage: monitor
product_group: group::product analytics
milestone: "16.4"
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/128029
- ee
- ultimate