• スノープロウとは
• 除雪スキーマ
• スノープロウの有効化
• 除雪依頼の流れ
• Snowplow JS（フロントエンド）トラッキングの実装
  • HAML（またはVueテンプレート）でのトラッキング
  • Vueコンポーネント内のトラッキング
  • 生のJavaScriptでのトラッキング
  • テストとテストヘルパー
• Snowplow Ruby（バックエンド）トラッキングの実装
  • パフォーマンス
• スノープラウの開発とテスト
  • Snowplow Analytics デバッガー Chrome 拡張機能
  • Snowplow Inspector Chrome 拡張機能
  • スノープロウ・マイクロ
  • スノープロウ・ミニ

除雪車ガイド

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

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

• テレメトリーガイド
• 使用法 Pingガイド

その他の便利なリンク

• テレメトリ方向
• データ分析プロセス
• プロダクトマネージャーのためのデータ
• データインフラ

スノープロウとは

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のスキーマには多くの定義があります。このスキーマを標準化するために、以下の定義を含むイシューがアクティブです：

• フロントエンドとバックエンドのタクソノミーを以下に示します。
• フィーチャー・インストゥルメント分類法
• 自己紹介イベント
• イグル スキーマ
• スノープロウ作成者イベント

スノープロウの有効化

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

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

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

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

以下の設定が必要です：

除雪依頼の流れ

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

• GitLab.com の Snowplow JS / Ruby トラッカー
• GitLab.com 除雪車コレクター
• GitLabのS3バケット
• GitLabのSnowflakeデータウェアハウス
• サイセンス

Snowplow JS（フロントエンド）トラッキングの実装

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

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-* 属性のリストです：

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

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

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

デフォルトのオプションは、コンポーネント内部からイベントがトラッキングされるたびに渡されます。 例えば、コンポーネント内のすべてのイベントを、指定されたlabelでトラッキングする必要がある場合、この時点で指定することができます。 利用可能なデフォルトは、category、label、property、valueです。カテゴリが指定されていない場合、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 クラスメソッドを直接呼び出すことで追加できます。 クラスメソッドは、以下の引数を受け付けます：

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

使用例：

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 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を変更する必要があります。

• スノープラウ・マイクロの紹介を読む
• Snowplow Microのリポジトリを見てください。
• インストールガイドを見る

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とテストの環境を構築しています。