Snowplow development guidelines

Snowplow is an enterprise-grade marketing and Analytics Instrumentation platform that tracks how users engage with our website and application.

Snowplow consists of several loosely-coupled sub-systems:

• Trackers fire Snowplow events. Snowplow has twelve trackers that cover web, mobile, desktop, server, and IoT.
• Collectors receive Snowplow events from trackers. We use different event collectors that synchronize events to Amazon S3, Apache Kafka, or Amazon Kinesis.
• Enrich cleans raw Snowplow events, enriches them, and puts them into storage. There is a Hadoop-based enrichment process, and a Kinesis-based or Kafka-based process.
• Storage stores Snowplow events. We store the Snowplow events in a flat file structure on S3, and in the Redshift and PostgreSQL databases.
• Data modeling joins event-level data with other data sets, aggregates them into smaller data sets, and applies business logic. This produces a clean set of tables for data analysis. We use data models for Redshift and Looker.
• Analytics are performed on Snowplow events or on aggregate tables.

Enable Snowplow tracking

Tracking can be enabled at:

• The instance level, which enables tracking on both the frontend and backend layers.
• The user level. User tracking can be disabled on a per user basis. GitLab respects the Do Not Track standard, so any user who has enabled the Do Not Track option in their browser is not tracked at a user level.

Snowplow tracking is configured to send data for GitLab.com to a collector configured by GitLab. By default, self-managed instances do not have a collector configured and do not collect data via Snowplow.

You can configure your self-managed GitLab instance to use a custom Snowplow collector.

1. On the left sidebar, expand the top-most chevron ({chevron-down}).

2. Select Admin Area.

3. On the left sidebar, select Settings > General.

4. Expand Snowplow.

5. Select Enable Snowplow tracking and enter your Snowplow configuration information. For example:

   Name	Value
   Collector hostname	your-snowplow-collector.net
   App ID	gitlab
   Cookie domain	.your-gitlab-instance.com

6. Select Save changes.

Snowplow request flow

The following example shows a basic request/response flow between the following components:

• Snowplow JS / Ruby Trackers on GitLab.com
• GitLab.com Snowplow Collector
• The GitLab S3 Bucket
• The GitLab Snowflake Data Warehouse
• Sisense:

sequenceDiagram
    participant Snowplow JS (Frontend)
    participant Snowplow Ruby (Backend)
    participant GitLab.com Snowplow Collector
    participant S3 Bucket
    participant Snowflake DW
    participant Sisense Dashboards
    Snowplow JS (Frontend) ->> GitLab.com Snowplow Collector: FE Tracking event
    Snowplow Ruby (Backend) ->> GitLab.com Snowplow Collector: BE Tracking event
    loop Process using Kinesis Stream
      GitLab.com Snowplow Collector ->> GitLab.com Snowplow Collector: Log raw events
      GitLab.com Snowplow Collector ->> GitLab.com Snowplow Collector: Enrich events
      GitLab.com Snowplow Collector ->> GitLab.com Snowplow Collector: Write to disk
    end
    GitLab.com Snowplow Collector ->> S3 Bucket: Kinesis Firehose
    Note over GitLab.com Snowplow Collector, S3 Bucket: Pseudonymization
    S3 Bucket->>Snowflake DW: Import data
    Snowflake DW->>Snowflake DW: Transform data using dbt
    Snowflake DW->>Sisense Dashboards: Data available for querying

For more details about the architecture, see Snowplow infrastructure.

Event schema

All the events must be consistent. If each feature captures events differently, it can be difficult to perform analysis.

Each event provides attributes that describe the event.

Examples

* If you choose to omit the category you can use the default.
** Use property for variable strings.

Reference SQL

Last 20 reply_comment_button events

SELECT
  session_id,
  event_id,
  event_label,
  event_action,
  event_property,
  event_value,
  event_category,
  contexts
FROM legacy.snowplow_structured_events_all
WHERE
  event_label = 'reply_comment_button'
  AND event_action = 'click_button'
  -- AND event_category = 'projects:issues:show'
  -- AND event_value = 1
ORDER BY collector_tstamp DESC
LIMIT 20

Last 100 page view events

SELECT
  -- page_url,
  -- page_title,
  -- referer_url,
  -- marketing_medium,
  -- marketing_source,
  -- marketing_campaign,
  -- browser_window_width,
  -- device_is_mobile
  *
FROM legacy.snowplow_page_views_30
ORDER BY page_view_start DESC
LIMIT 100

Top 20 users who fired reply_comment_button in the last 30 days

SELECT
  count(*) as hits,
  se_action,
  se_category,
  gsc_pseudonymized_user_id
FROM legacy.snowplow_gitlab_events_30
WHERE
  se_label = 'reply_comment_button'
  AND gsc_pseudonymized_user_id IS NOT NULL
GROUP BY gsc_pseudonymized_user_id, se_category, se_action
ORDER BY count(*) DESC
LIMIT 20

Query JSON formatted data

SELECT
  derived_tstamp,
  contexts:data[0]:data:extra:old_format as CURRENT_FORMAT,
  contexts:data[0]:data:extra:value as UPDATED_FORMAT
FROM legacy.snowplow_structured_events_all
WHERE event_action in ('wiki_format_updated')
ORDER BY derived_tstamp DESC
LIMIT 100

Web-specific parameters

Snowplow JavaScript adds web-specific parameters to all web events by default.

Related topics

• Snowplow data structure
• Our Iglu schema registry
• List of events used in our codebase (Event Dictionary)
• Analytics Instrumentation Guide
• Service Ping Guide
• Analytics Instrumentation Direction
• Data Analysis Process
• Data for Product Managers
• Data Infrastructure