Event dictionary 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 Snowplow events and ensure consistency. Every Snowplow 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:

FieldRequiredAdditional information
descriptionyesA description of the event.
categoryyesThe event category (see Event schema).
actionyesThe event action (see Event schema).
label_descriptionnoA description of the event label (see Event schema).
property_descriptionnoA description of the event property (see Event schema).
value_descriptionnoA description of the event value (see Event schema).
extra_propertiesnoThe type and description of each extra property sent with the event.
identifiersnoA list of identifiers sent with the event. Can be set to one or more of project, user, or namespace.
iglu_schema_urlnoThe URL to the custom schema sent with the event, for example, iglu:com.gitlab/gitlab_experiment/jsonschema/1-0-0.
product_sectionyesThe section.
product_stagenoThe stage for the event.
product_groupyesThe group that owns the event.
milestonenoThe milestone when the event is introduced.
introduced_by_urlnoThe URL to the merge request that introduced the event.
distributionsyesThe distributions where the tracked feature is available. Can be set to one or more of ce or ee.
tiersyesThe tiers where the tracked feature is available. Can be set to one or more of free, premium, or ultimate.

Example event definition

The linked uuid YAML file includes an example event definition.

description: Issue promoted to epic
category: epics
action: promote
property_description: The string "issue_id"
value_description: ID of the issue
    type: integer
    description: Weight of the issue
- project
- user
- namespace
product_section: dev
product_stage: plan
product_group: group::product planning
milestone: "11.10"
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/10537
- ee
- premium
- ultimate

Create a new event definition

Use the dedicated event definition generator to create new event definitions.

The category and action of each event are included in the filename to standardize file naming.

The generator takes three options:

  • --ee: Indicates if the event is for EE.
  • --category=CATEGORY: Indicates the category of the event.
  • --action=ACTION: Indicates the action of the event.
bundle exec rails generate gitlab:snowplow_event_definition --category Groups::EmailCampaignsController --action click
create  create  config/events/groups__email_campaigns_controller_click.yml