- スノープロウとは
- 除雪スキーマ
- スノープロウの有効化
- 除雪依頼の流れ
- Snowplow JS(フロントエンド)トラッキングの実装
- Snowplow Ruby(バックエンド)トラッキングの実装
- スノープラウの開発とテスト
除雪車ガイド
このガイドでは、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のスキーマには多くの定義があります。このスキーマを標準化するために、以下の定義を含むイシューがアクティブです:
- フロントエンドとバックエンドのタクソノミーを以下に示します。
- フィーチャー・インストゥルメント分類法
- 自己紹介イベント
- イグル スキーマ
- スノープロウ作成者イベント
スノープロウの有効化
トラッキングを有効にするには
- インスタンスレベルで、フロントエンドとバックエンドの両レイヤーでトラッキングが可能です。
- GitLabのトラッキングはDo Not Track標準を尊重しているため、ブラウザでDo Not Trackオプションを有効にしているユーザーはユーザーレベルでトラッキングされません。
私たちはトラッキング戦略の大部分にSnowplowを利用しており、GitLab.comで有効にしています。 セルフマネージドインスタンスでは、Snowplowは次のページに移動して有効にすることができます:
- 管理エリア > 設定 >UIのインテグレーション。
-
admin/application_settings/integrations
をブラウザに追加してください。
以下の設定が必要です:
名称 | 値 |
---|---|
コレクター | snowplow.trx.gitlab.net
|
サイトID | gitlab
|
クッキードメイン | .gitlab.com
|
除雪依頼の流れ
次の例は、以下のコンポーネント間の基本的なリクエスト/レスポンスフローを示しています:
- GitLab.com の Snowplow JS / Ruby トラッカー
- GitLab.com 除雪車コレクター
- GitLabのS3バケット
- GitLabのSnowflakeデータウェアハウス
- サイセンス
Snowplow JS(フロントエンド)トラッキングの実装
GitLab はTracking
を提供しています。これはカスタムイベントをトラッキングするためのSnowplow JavaScript Trackerをラップしたインターフェースです。 トラッキングを利用する方法はいくつかありますが、一般的にはそれぞれ最低限category
とaction
が必要です。また、Feature instrumentation taxonomyに従った追加データを提供することもできます。
フィールド | タイプ | デフォルト値 | 説明 |
---|---|---|---|
category
| 列 | ドキュメント.ボディ.データセット.ページ | イベントがキャプチャされるページまたはページのサブセクション。 |
action
| 列 | ジェネリック | クリックはclick 、アクティビティはactivate 。例えば、フォームフィールドにフォーカスを当てる場合はactivate_form_input 、ボタンをクリックする場合はclick_button 。
|
data
| オブジェクト | {} |
label 、property 、value 、context などの追加データは、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
でトラッキングする必要がある場合、この時点で指定することができます。 利用可能なデフォルトは、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
クラスメソッドを直接呼び出すことで追加できます。 クラスメソッドは、以下の引数を受け付けます:
議論 | タイプ | デフォルト値 | 説明 |
---|---|---|---|
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は、フロントエンドのイベントをテストするためのブラウザ拡張機能です。 本番環境、ステージング環境、ローカル開発環境で動作します。
- Snowplow Analytics DebuggerChromeブラウザ拡張機能をインストールします。
- Chrome DevToolsを開き、Snowplow Analytics Debuggerタブを開きます。
- 詳しくはIgloo Analyticsをご覧ください。
Snowplow Inspector Chrome 拡張機能
Snowplow Inspector Chrome Extensionはフロントエンドのイベントをテストするためのブラウザ拡張機能です。 本番環境、ステージング環境、ローカル開発環境で動作します。
- 除雪車インスペクターのインストール。
- アドレスバーの横にあるSnowplow Inspectorアイコンを押して、Chrome拡張機能を開きます。
- Snowplowを使ってウェブページをクリックすると、インスペクタウィンドウでJavaScriptのイベントが発生するのが見えるはずです。
スノープロウ・マイクロ
Snowplow Microは完全なSnowplowデータ収集パイプラインの非常に小さなバージョンです。 イベントは完全なSnowplowパイプラインと同じようにSnowplow Microに記録することができます。 Microはクエリ可能なAPIを公開します。
Snowplow Microは、ローカル開発環境でフロントエンドとバックエンドのイベントをテストするためのDockerベースのソリューションです。 これをセットアップするには、以下の手順でGDKを変更する必要があります。
- スノープラウ・マイクロの紹介を読む
- 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
-
このプロジェクトの設定をクローンしてsnowplow microをインストールします:
git clone git@gitlab.com:a_akgun/snowplow-micro.git ./snowplow-micro.sh
-
SQLでポートを更新し、
9090
:gdk psql -d gitlabhq_development update application_settings set snowplow_collector_hostname='localhost:9090', snowplow_enabled=true, snowplow_cookie_domain='.gitlab.com';
-
app/assets/javascripts/tracking.js
を更新し、この行を削除してください:forceSecureTracker: true
-
lib/gitlab/tracking.rb
を更新し、以下の行を追加してください:protocol: 'http', port: 9090,
-
lib/gitlab/tracking.rb
を更新し、async エミッターを https から http に変更しました:SnowplowTracker::AsyncEmitter.new(Gitlab::CurrentSettings.snowplow_collector_hostname, protocol: 'http'),
-
管理エリアのSettings::Integration::SnowplowでSnowplowを有効にし、
http://localhost:3000/admin/application_settings/integrations#js-snowplow-settings
。 -
GDKを再起動します:
`gdk restart`
-
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とテストの環境を構築しています。