除雪車ガイド

このガイドでは、Snowplowの仕組みの概要と導入の詳細について説明します。

テレメトリーについては、こちらを参照:

その他の便利なリンク

スノープロウとは

Snowplowはエンタープライズグレードのマーケティングおよび製品分析プラットフォームであり、ユーザーが当社のウェブサイトやアプリケーションにどのように関わるかを追跡するのに役立ちます。

スノープラウは、以下の疎結合サブシステムで構成されています:

  • トラッカーはSnowplowのイベントをファイアします。 Snowplowにはウェブ、モバイル、デスクトップ、サーバー、IoTをカバーする12のトラッカーがあります。
  • コレクターはトラッカーからSnowplowのイベントを受け取ります。 私たちは3つの異なるイベントコレクターを持っており、Amazon S3、Apache Kafka、Amazon Kinesisのいずれかにイベントを同期します。
  • Enrichは生のSnowplowイベントをクリーンアップし、エンリッチしてストレージに格納します。 Hadoopベースのエンリッチプロセスと、KinesisベースまたはKafkaベースのプロセスがあります。
  • Snowplowのイベントは、S3上のフラットファイル構造と、RedshiftとPostgreSQLのデータベースに保存されます。
  • データモデリングとは、イベントレベルのデータを他のデータセットと結合し、より小さなデータセットに集約し、ビジネスロジックを適用することです。 これにより、データ分析をより簡単に行うことができるクリーンなテーブルセットが作成されます。 私たちはRedshiftとLookerのデータモデルを持っています。
  • 分析はスノープラウのイベントまたは集計テーブルで実行されます。

snowplow_flow

除雪スキーマ

Snowplowのスキーマには多くの定義があります。このスキーマを標準化するために、以下の定義を含むイシューがアクティブです:

スノープロウの有効化

トラッキングを有効にするには

  • インスタンスレベルで、フロントエンドとバックエンドの両レイヤーでトラッキングが可能です。
  • GitLabのトラッキングはDo Not Track標準を尊重しているため、ブラウザでDo Not Trackオプションを有効にしているユーザーはユーザーレベルでトラッキングされません。

私たちはトラッキング戦略の大部分にSnowplowを利用しており、GitLab.comで有効にしています。 セルフマネージドインスタンスでは、Snowplowは次のページに移動して有効にすることができます:

  • 管理エリア > 設定 >UIのインテグレーション。
  • admin/application_settings/integrations をブラウザに追加してください。

以下の設定が必要です:

名称
コレクター snowplow.trx.gitlab.net
サイトID gitlab
クッキードメイン .gitlab.com

除雪依頼の流れ

次の例は、以下のコンポーネント間の基本的なリクエスト/レスポンスフローを示しています:

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 S3 Bucket->>Snowflake DW: Import data Snowflake DW->>Snowflake DW: Transform data using dbt Snowflake DW->>Sisense Dashboards: Data available for querying

Snowplow JS(フロントエンド)トラッキングの実装

GitLab はTrackingを提供しています。これはカスタムイベントをトラッキングするためのSnowplow JavaScript Trackerをラップしたインターフェースです。 トラッキングを利用する方法はいくつかありますが、一般的にはそれぞれ最低限categoryactionが必要です。また、Feature instrumentation taxonomyに従った追加データを提供することもできます。

フィールド タイプ デフォルト値 説明
category ドキュメント.ボディ.データセット.ページ イベントがキャプチャされるページまたはページのサブセクション。
action ジェネリック クリックはclick 、アクティビティはactivate。例えば、フォームフィールドにフォーカスを当てる場合はactivate_form_input、ボタンをクリックする場合はclick_button
data オブジェクト {} labelpropertyvaluecontext などの追加データは、Feature Instrumentation分類法で説明されています。

HAML(またはVueテンプレート)でのトラッキング

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の変更時に適切に処理されるようになります。 これらのイベントがバインドされているため、クリック・イベントがDOMツリー上に伝搬するのを止めるべきでないことに注意してください。 何らかの理由でクリック・イベントの伝搬が止まっている場合は、独自のリスナーを実装し、Tracking in raw JavaScriptの指示に従ってください。

以下は、サポートされているdata-track-* 属性のリストです:

属性 必須 説明
data-track-event 真の クリックはclick を、アクティビティはactivateを前につける必要があります。例えば、フォームフィールドにフォーカスする場合はactivate_form_input となり、ボタンをクリックする場合はclick_buttonとなります。
data-track-label false 私たちのFeature Instrumentation分類法で説明されているlabel
data-track-property false 私たちのFeature Instrumentation分類法で説明されているproperty
data-track-value false value Feature Instrumentationタクソノミーで説明されて valueいるvalue 通りです。 省略された場合、要素の valueプロパティか空文字列となります。チェックボックスの場合、デフォルト値は要素のchecked属性か、チェックされていない場合はfalse
data-track-context false 私たちのFeature Instrumentation分類法で説明されているcontext

Vueコンポーネント内のトラッキング

より複雑なトラッキングが必要な場合、コンポーネントで使用できるトラッキングVueミキシンがあります。 これを使用するには、まずTracking ライブラリをインポートし、ミキシンをリクエストします。

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

デフォルトのオプションは、コンポーネント内部からイベントがトラッキングされるたびに渡されます。 例えば、コンポーネント内のすべてのイベントを、指定されたlabelでトラッキングする必要がある場合、この時点で指定することができます。 利用可能なデフォルトは、categorylabelpropertyvalueです。カテゴリが指定されていない場合、document.body.dataset.page がデフォルトとして使用されます。

このミキシンは、mixin Vue 宣言を使って、コンポーネント内で通常通り使用することができます。また、data またはcomputedでトラッキングオプションを指定することもできます。これらは、デフォルト値を上書きし、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>

生のJavaScriptでのトラッキング

Tracking.event 静的関数を Tracking.event直接コールすることで、カスタムイベントのトラッキングやインスツルメンテーションを追加することがTracking.event できます。 以下の例では、 Tracking.event手動で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',
  });
})

テストとテストヘルパー

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',
    });
  });
});

廃止されたカルマのテストでは、以下のように使用されます:

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',
    });
  });
});

Snowplow Ruby(バックエンド)トラッキングの実装

GitLab はGitlab::Trackingを提供しています。これはカスタムイベントをトラッキングするためにSnowplow Ruby Trackerをラップしたインターフェースです。

カスタムのイベントトラッキングとインスツルメンテーションは、GitLab::Tracking.event クラスメソッドを直接呼び出すことで追加できます。 クラスメソッドは、以下の引数を受け付けます:

議論 タイプ デフォルト値 説明
category アプリケーション アプリケーションのエリアまたはアスペクト。例えば、HealthCheckController またはLfs::FileTransformer です。
action ジェネリック アクションは、create のようなコントローラのアクションから、Active Record のコールバックのようなものまで、なんでもかまいません。
data オブジェクト {} label,property,value,context のような追加データは、Feature Instrumentation分類法で説明されています。これらを提供しない場合、空の文字列として設定されます。

トラッキングは、ユーザーの行動を追跡する場合と、コードの領域やアスペクトの経時的なパフォーマンスを監視して可視化するためのインスツルメンテーションに利用する場合があります。

使用例:

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

パフォーマンス

イベントをトラッキングする際にはAsyncEmitterを使用し、バックグラウンドのスレッドでインスツルメンテーションコールを実行できるようにしています。 これはまだ開発中の領域です。

スノープラウの開発とテスト

スノープロウ・イベントを開発しテストするためのツールがいくつかあります。

テストツール フロントエンドのトラッキング バックエンドトラッキング 地域開発者環境 生産環境
Snowplow Analytics デバッガー Chrome 拡張機能 {チェック・サークル} {点線丸} {チェック・サークル} {チェック・サークル}
Snowplow Inspector Chrome 拡張機能 {チェック・サークル} {点線丸} {チェック・サークル} {チェック・サークル}
スノープロウ・マイクロ {チェック・サークル} {チェック・サークル} {チェック・サークル} {点線丸}
スノープロウ・ミニ {チェック・サークル} {チェック・サークル} {点線丸} {チェック・サークル}

Snowplow Analytics デバッガー Chrome 拡張機能

Snowplow Analytics Debuggerは、フロントエンドのイベントをテストするためのブラウザ拡張機能です。 本番環境、ステージング環境、ローカル開発環境で動作します。

  1. Snowplow Analytics DebuggerChromeブラウザ拡張機能をインストールします。
  2. Chrome DevToolsを開き、Snowplow Analytics Debuggerタブを開きます。
  3. 詳しくはIgloo Analyticsをご覧ください。

Snowplow Inspector Chrome 拡張機能

Snowplow Inspector Chrome Extensionはフロントエンドのイベントをテストするためのブラウザ拡張機能です。 本番環境、ステージング環境、ローカル開発環境で動作します。

  1. 除雪車インスペクターのインストール。
  2. アドレスバーの横にあるSnowplow Inspectorアイコンを押して、Chrome拡張機能を開きます。
  3. Snowplowを使ってウェブページをクリックすると、インスペクタウィンドウでJavaScriptのイベントが発生するのが見えるはずです。

スノープロウ・マイクロ

Snowplow Microは完全なSnowplowデータ収集パイプラインの非常に小さなバージョンです。 イベントは完全なSnowplowパイプラインと同じようにSnowplow Microに記録することができます。 Microはクエリ可能なAPIを公開します。

Snowplow Microは、ローカル開発環境でフロントエンドとバックエンドのイベントをテストするためのDockerベースのソリューションです。 これをセットアップするには、以下の手順でGDKを変更する必要があります。

  1. スノープロウ・マイクロのインストール

    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. app/assets/javascripts/tracking.js を更新し、この行を削除してください:

    forceSecureTracker: true
    
  5. lib/gitlab/tracking.rb を更新し、以下の行を追加してください:

    protocol: 'http',
    port: 9090,
    
  6. lib/gitlab/tracking.rb を更新し、async エミッターを https から http に変更しました:

    SnowplowTracker::AsyncEmitter.new(Gitlab::CurrentSettings.snowplow_collector_hostname, protocol: 'http'),
    
  7. 管理エリアのSettings::Integration::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のシングルインスタンスバージョンです。

Snowplow Miniは、本番環境、ステージング環境、ローカル開発環境でフロントエンドとバックエンドのイベントをテストするために使用できます。

GitLab.comでは、Snowplow Miniを使ってQAとテストの環境を構築しています。