Snowplow Guide

原文：https://docs.gitlab.com/ee/development/telemetry/snowplow.html

• What is Snowplow
• Snowplow schema
• Enabling Snowplow
• Snowplow request flow
• Implementing Snowplow JS (Frontend) tracking
  • Tracking in HAML (or Vue Templates)
  • Tracking within Vue components
  • Tracking in raw JavaScript
  • Tests and test helpers
• Implementing Snowplow Ruby (Backend) tracking
  • Performance
• Developing and testing Snowplow
  • Snowplow Analytics Debugger Chrome Extension
  • Snowplow Inspector Chrome Extension
  • Snowplow Micro
  • Snowplow Mini

Snowplow Guide

本指南概述了 Snowplow 的工作原理以及实施细节.

有关遥测的更多信息，请参见：

• Telemetry Guide
• Usage Ping Guide

更有用的链接：

• Telemetry Direction
• Data Analysis Process
• Data for Product Managers
• Data Infrastructure

What is Snowplow

Snowplow 是企业级营销和产品分析平台，可帮助跟踪用户与我们的网站和应用程序互动的方式.

扫雪机由以下松耦合子系统组成：

• Trackers fire Snowplow events. Snowplow has 12 trackers, covering web, mobile, desktop, server, and IoT.
• 收集器从跟踪器接收 Snowplow 事件. 我们有三个不同的事件收集器，可将事件同步到 Amazon S3，Apache Kafka 或 Amazon Kinesis.
• Enrich清理原始的 Snowplow 事件，丰富它们并将其存储. 我们有一个基于 Hadoop 的扩充流程，以及一个基于 Kinesis 或基于 Kafka 的流程.
• 扫雪机事件所在的位置是存储 . 我们将 Snowplow 事件存储在 S3 上的平面文件结构中以及 Redshift 和 PostgreSQL 数据库中.
• 数据建模是将事件级别的数据与其他数据集合并在一起，并聚合为较小的数据集，然后应用业务逻辑. 这将产生一组干净的表，从而使对数据的分析更加容易. 我们有 Redshift 和 Looker 的数据模型.
• 在 Snowplow 事件或汇总表上执行分析 .

Snowplow schema

我们有 Snowplow 模式的许多定义. 我们有一个积极的问题要对此模式进行标准化，包括以下定义：

• 前端和后端分类法如下所示
• Feature instrumentation taxonomy
• Self describing events
• Iglu schema
• Snowplow authored events

Enabling Snowplow

可以在以下位置启用跟踪：

• 实例级别，可以在前端层和后端层上进行跟踪.
• 用户级别，尽管可以按用户禁用用户跟踪. GitLab 跟踪遵循“不跟踪”标准，因此不会在用户级别跟踪浏览器中启用了”不跟踪”选项的任何用户.

我们将 Snowplow 用作大多数跟踪策略，并且已在 GitLab.com 上启用了它. 在自我管理的实例上，可以通过导航到以下地址来启用 Snowplow：

• 用户界面中的管理区域>设置>集成 .
• 浏览器中的admin/application_settings/integrations .

需要以下配置：

Snowplow request flow

下面的示例显示以下组件之间的基本请求/响应流：

• GitLab.com 上的 Snowplow JS / Ruby Trackers
• GitLab.com Snowplow Collector
• 亚搏体育 app 的 S3 桶
• GitLab 的 Snowflake 数据仓库
• Sisense:

sequenceDiagram 参与者 Snowplow JS（前端）参与者 Snowplow Ruby（后端）参与者 GitLab.com Snowplow Collector 参与者 S3 Bucket 参与者 Snowflake DW 参与者 Sisense Dashboards Snowplow JS（前端）->> GitLab.com Snowplow Collector：FE 跟踪事件 Snowplow Ruby（后端） ->> GitLab.com Snowplow 收集器：使用 Kinesis Stream 跟踪事件循环过程 GitLab.com Snowplow 收集器->> GitLab.com Snowplow 收集器：记录原始事件 GitLab.com Snowplow 收集器->> GitLab.com Snowplow 收集器：丰富事件 GitLab.com 扫雪机-> GitLab.com 扫雪机：写入磁盘端 GitLab.com 扫雪机->> S3 桶：K​​inesis Firehose S3 桶->>雪花 DW：导入数据 Snowflake DW->> Snowflake DW：转换 dbt Snowflake DW->> Sisense 仪表盘获取数据：可用于查询的数据

Implementing Snowplow JS (Frontend) tracking

GitLab 提供了Tracking ，该接口包装了Snowplow JavaScript Tracker以跟踪自定义事件. 有几种利用跟踪的方法，但是每种方法通常至少需要一个category和一个action . 可以提供符合我们功能仪表分类法的其他数据.

Tracking in HAML (or Vue Templates)

在 HAML（或 Vue 模板）中工作时，我们可以向感兴趣的元素添加data-track-*属性. 具有data-track-event属性的所有元素都会自动对点击绑定事件跟踪.

以下是分配给按钮的data-track-*属性的示例：

%button.btn{ data: { track: { event: "click_button", label: "template_preview", property: "my-template" } } }

<button class="btn"
  data-track-event="click_button"
  data-track-label="template_preview"
  data-track-property="my-template"
/>

事件侦听器在文档级别绑定，以处理具有这些数据属性的元素上或元素内的单击事件. 这样可以在重新渲染和更改 DOM 时正确处理它们. 请注意，由于绑定了这些事件的方式，不应阻止 click 事件传播 DOM 树. 如果出于某种原因阻止了点击事件的传播，则需要实现自己的侦听器，并按照原始 JavaScript中的跟踪中的说明进行操作.

Below is a list of supported data-track-* attributes:

Tracking within Vue components

如果需要更复杂的跟踪，可以在组件中使用跟踪 Vue mixin. 要使用它，请首先导入Tracking库并请求一个混合.

import Tracking from '~/tracking';
const trackingMixin = Tracking.mixin({ label: 'right_sidebar' });

您可以提供在组件中跟踪事件时都会传递的默认选项. 例如，如果应使用给定label跟踪组件中的所有事件，则此时可以提供一个. 可用的默认值是category ， label ， property和value . 如果未指定类别，则将document.body.dataset.page用作默认值.

然后，您可以通过mixin Vue 声明在组件中正常使用 mixin. mixin 还提供了在data或computed指定跟踪选项的data . 这些将覆盖所有默认值，并允许这些值从 props 或基于状态是动态的.

export default {
  mixins: [trackingMixin],
  // ...[component implementation]...
  data() {
    return {
      expanded: false,
      tracking: {
        label: 'left_sidebar'
      }
    };
  },
}

mixin 提供了可以在模板中或从组件方法中调用的track方法. 整个实现的示例可能如下所示.

export default {
  mixins: [Tracking.mixin({ label: 'right_sidebar' })],
  data() {
    return {
      expanded: false,
    };
  },
  methods: {
    toggle() {
      this.expanded = !this.expanded;
      this.track('click_toggle', { value: this.expanded })
    }
  }
};

而且，如果需要模板中的内容，也可以直接使用track方法.

<template>
  <div>
    <a class="toggle" @click.prevent="toggle">Toggle</a>
    <div v-if="expanded">
      <p>Hello world!</p>
      <a @click.prevent="track('click_action')">Track an event</a>
    </div>
  </div>
</template>

Tracking in raw JavaScript

可以通过直接调用Tracking.event静态函数来添加自定义事件跟踪和检测. 下面的示例演示如何通过手动调用Tracking.event按钮的单击.

import Tracking from '~/tracking';
const button = document.getElementById('create_from_template_button');
button.addEventListener('click', () => {
  Tracking.event('dashboard:projects:index', 'click_button', {
    label: 'create_from_template',
    property: 'template_preview',
    value: 'rails',
  });
})

Tests and test helpers

在 Jest 中，尤其是在 Vue 测试中，可以使用以下命令：

import { mockTracking } from 'helpers/tracking_helper';
describe('MyTracking', () => {
  let spy;
  beforeEach(() => {
    spy = mockTracking('_category_', wrapper.element, jest.spyOn);
  });
  it('tracks an event when clicked on feedback', () => {
    wrapper.find('.discover-feedback-icon').trigger('click');
    expect(spy).toHaveBeenCalledWith('_category_', 'click_button', {
      label: 'security-discover-feedback-cta',
      property: '0',
    });
  });
});

在过时的 Karma 测试中，其用法如下：

import { mockTracking, triggerEvent } from 'spec/helpers/tracking_helper';
describe('my component', () => {
  let trackingSpy;
  beforeEach(() => {
    trackingSpy = mockTracking('_category_', vm.$el, spyOn);
  });
  const triggerEvent = () => {
    // action which should trigger a event
  };
  it('tracks an event when toggled', () => {
    expect(trackingSpy).not.toHaveBeenCalled();
    triggerEvent('a.toggle');
    expect(trackingSpy).toHaveBeenCalledWith('_category_', 'click_edit_button', {
      label: 'right_sidebar',
      property: 'confidentiality',
    });
  });
});

Implementing Snowplow Ruby (Backend) tracking

GitLab 提供Gitlab::Tracking ，该接口包装Snowplow Ruby Tracker以跟踪自定义事件.

可以通过直接调用GitLab::Tracking.event类方法来添加自定义事件跟踪和检测，该方法接受以下参数：

跟踪既可以看作是跟踪用户的行为，也可以用于检测和监视代码区域或方面随时间变化的性能.

例如：

class Projects::CreateService < BaseService
  def execute
    project = Project.create(params)
    Gitlab::Tracking.event('Projects::CreateService', 'create_project',
      label: project.errors.full_messages.to_sentence,
      value: project.valid?
    )
  end
end

Performance

跟踪事件时，我们使用AsyncEmitter ，它允许在后台线程中运行检测调用. 这仍然是一个活跃的发展领域.

Developing and testing Snowplow

有几种工具可以开发和测试 Snowplow Event

Snowplow Analytics Debugger Chrome Extension

Snowplow Analytics Debugger 是用于测试前端事件的浏览器扩展. 这适用于生产，暂存和本地开发环境.

1. 安装Snowplow Analytics Debugger Chrome 浏览器扩展程序.
2. 将 Chrome DevTools 打开到 Snowplow Analytics 调试器选项卡.
3. 在Igloo Analytics 上了解更多信息.

Snowplow Inspector Chrome Extension

Snowplow Inspector Chrome 扩展程序是用于测试前端事件的浏览器扩展程序. 这适用于生产，暂存和本地开发环境.

1. Install Snowplow Inspector.
2. 按下地址栏旁边的 Snowplow Inspector 图标，打开 Chrome 扩展程序.
3. 单击带有 Snowplow 的网页，您应该会在检查器窗口中看到触发 JavaScript 事件.

Snowplow Micro

Snowplow Micro 是完整 Snowplow 数据收集管道的非常小版本：足够小，可以由测试套件启动. 就像完整的 Snowplow 管道一样，事件可以记录到 Snowplow Micro 中. Micro 然后公开了可以查询的 API.

Snowplow Micro 是基于 Docker 的解决方案，用于在本地开发环境中测试前端和后端事件. 您需要按照以下说明修改 GDK 进行设置.

• Read Introducing Snowplow Micro
• 查看Snowplow Micro 存储库
• 观看我们的安装指南记录

1. Install Snowplow Micro:

   docker run --mount type=bind,source=$(pwd)/example,destination=/config -p 9090:9090 snowplow/snowplow-micro:latest --collector-config /config/micro.conf --iglu /config/iglu.json

2. 通过克隆此项目中的设置来安装 Snowplow micro：

   git clone git@gitlab.com:a_akgun/snowplow-micro.git
   ./snowplow-micro.sh

3. 在 SQL 中更新端口以设置9090 ：

   gdk psql -d gitlabhq_development
   update application_settings set snowplow_collector_hostname='localhost:9090', snowplow_enabled=true, snowplow_cookie_domain='.gitlab.com';

4. Update app/assets/javascripts/tracking.js to remove this line:

   forceSecureTracker: true

5. Update lib/gitlab/tracking.rb to add these lines:

   protocol: 'http',
   port: 9090,

6. Update lib/gitlab/tracking.rb to change async emitter from https to http:

   SnowplowTracker::AsyncEmitter.new(Gitlab::CurrentSettings.snowplow_collector_hostname, protocol: 'http'),

7. 在管理区域 Settings :: Integrations :: Snowplow 中启用 Snowplow，以指向： http://localhost:3000/admin/application_settings/integrations#js-snowplow-settings .

8. 重新启动 GDK：

   `gdk restart`

9. 从 Rails 控制台发送测试 Snowplow 事件：

   Gitlab::Tracking.self_describing_event('iglu:com.gitlab/pageview_context/jsonschema/1-0-0', { page_type: ‘MY_TYPE' }, context: nil )

Snowplow Mini

Snowplow Mini是Snowplow的易于部署的单实例版本.

Snowplow Mini 可用于在生产，暂存和本地开发环境上测试前端和后端事件.

对于 GitLab.com，我们正在使用 Snowplow Mini 设置质量检查和测试环境 .