ユーザー定義ログの収集

ブラウザエージェントは、Webアプリケーションが任意のログメッセージを直接収集できるようloggerインターフェースを提供します。メッセージにレベル、コンテキスト、エラー情報を付けて送信すると、WhaTapコンソールで検索・フィルタリングできます。ユーザー定義イベントの収集がイベントの実行時間と結果を扱うのに対し、ユーザー定義ログはアプリケーションの動作中に出力されるメッセージをレベルごとに記録します。

ノート

ユーザー定義ログは、ブラウザエージェント3.0以上でのみ動作します。以前のバージョンの場合は、本機能を使用する前にエージェントをアップグレードしてください。

注意

ログモニタリングは課金対象の機能です。有効化した日から15日間無料で体験でき、その後は収集したログに基づいて料金が課金されます。

事前準備

WhaTapコンソールで次の値を発行してください。

Item	Description
アクセスキー	プロジェクトアクセスキー(`projectAccessKey`)
プロジェクトコード	数値型プロジェクトコード(`pcode`)
コレクターアドレス	データを受け取るコレクターURL(`proxyBaseUrl`)

注意

proxyBaseUrlが空の場合、すべてのログが警告なく破棄されます。必ず設定してください。

有効化

ユーザー定義ログを使用するには、次の2つを設定する必要があります。

ログ設定: ログ設定画面でログモニタリング機能の活性化トグルをオンにしてください。ログモニタリングがオンの間のみログが収集され、トグルをオフにするとログは保存されなくなります。
ユーザー定義ログオプション: ブラウザエージェントはデフォルトで非同期にロードされます。WhaTapコンソールで発行される標準インストールスニペットをそのまま使用し、configオブジェクトにenableCustomLog: trueを追加してください。

<script>
  (function (w, h, _a, t, a, b) {
    w = w[a] = w[a] || {
      config: {
        projectAccessKey: 'YOUR_ACCESS_KEY',
        pcode: 12345,
        sampleRate: 100,
        proxyBaseUrl: 'https://your-collector.example.com/',
        enableCustomLog: true,   // ユーザー定義ログの有効化
        env: 'prod',
        version: '1.0.0'
      }
    };
    a = h.createElement(_a);
    a.async = 1;
    a.src = t;
    t = h.getElementsByTagName(_a)[0];
    t.parentNode.insertBefore(a, t);
  })(window, document, 'script',
     'https://repo.whatap-browser-agent.io/rum/v3/whatap-browser-agent.js',
     'WhatapBrowserAgent', '');
</script>

設定オプション

Option	Type	Required	Description
`projectAccessKey`	`string`	必須	WhaTapコンソールで発行されたアクセスキー
`pcode`	`number`	必須	プロジェクトコード
`proxyBaseUrl`	`string`	必須	コレクターのベースURL。未設定の場合はログが送信されません
`enableCustomLog`	`boolean`	必須	`true`に指定する必要があります(デフォルト`false`)
`env`	`string`	任意	環境区分(例: `prod`、`staging`、`dev`)。デフォルト`default_env`
`version`	`string`	任意	アプリケーションのバージョン。デプロイごとにログを区別する際に使用。デフォルト`default_version`

ノート

loggerインターフェースは、エージェントスクリプトがダウンロード・実行された後にのみ公開されます。ページロードの非常に早い時点での呼び出しは無視される場合があります。安全な呼び出し方法は非同期ロードと安全な呼び出しを参照してください。

注意

ユーザー定義ログはセッションのサンプリング決定に従います。sampleRateにより現在のセッションが収集対象から除外されると、そのセッションのユーザー定義ログも送信されません。すべてのセッションのログを収集するには、sampleRate: 100(デフォルト)を維持してください。

インターフェース

loggerインターフェースは、windowのWhatapBrowserAgentオブジェクトに含まれています。

Typescript
window.WhatapBrowserAgent.logger.debug(message, context, error);
window.WhatapBrowserAgent.logger.info (message, context, error);
window.WhatapBrowserAgent.logger.warn (message, context, error);
window.WhatapBrowserAgent.logger.error(message, context, error);
window.WhatapBrowserAgent.logger.log  (message, context, status, error);

Argument	Type	Required	Description
`message`	`string`	必須	ログ本文。最大8KB
`context`	`object`	任意	追加メタ。検索・フィルターに使用
`error`	`Error` または類似オブジェクト	任意	スタックと併せて送信する際に使用

すべてのメソッドは同期的であり、戻り値がありません。
呼び出し直後に内部に蓄積され、約1秒後にまとめて送信されます。
引数を誤って渡しても例外をスローしないため、アプリケーションの動作に影響はありません。
logger.log()は3番目の引数としてstatus('debug' | 'info' | 'warn' | 'error')を受け取り、不正な値は'info'として処理されます。

使用方法

基本的な呼び出し

window.WhatapBrowserAgent.logger.info('checkout button clicked');

コンテキストを併せて送信

2番目の引数にオブジェクトを渡すと、WhaTapコンソールでの検索・フィルターに利用できます。

window.WhatapBrowserAgent.logger.info('checkout step', {
  step: 'shipping',
  cartItems: 3,
  isPremiumUser: true
});

contextには文字列、数値、ブール値のみがそのまま送信されます。オブジェクト・配列・null・undefined・関数は自動的に除外されるため、ネストした値は平坦化するか文字列にシリアライズしてください。

// 無視される: userがオブジェクト
window.WhatapBrowserAgent.logger.info('login', {
  user: { id: 42, name: 'jihoon' }
});

// 平坦化
window.WhatapBrowserAgent.logger.info('login', {
  userId: 42,
  userName: 'jihoon'
});

// シリアライズ
window.WhatapBrowserAgent.logger.info('login', {
  userJson: JSON.stringify({ id: 42, name: 'jihoon' })
});

エラーを併せて送信

3番目の引数にErrorオブジェクトやcatchした値をそのまま渡すと、name、message、stackが併せて送信されます。

try {
  riskyOperation();
} catch (e) {
  window.WhatapBrowserAgent.logger.error(
    'riskyOperation failed',
    { feature: 'checkout' },
    e
  );
}

Errorインスタンス: name、message、stackをそのまま抽出
一般オブジェクト: name / message / stackプロパティがあれば使用
それ以外(文字列・数値など): 文字列に変換されmessageに入る

ログレベル

レベル	推奨用途
`debug`	開発中の詳細トレース。運用環境では使用を控える
`info`	正常フローのイベント(ページ進入、ビジネスマイルストーン)
`warn`	復旧された異常状況(リトライ成功、フォールバック使用)
`error`	ユーザー体験に影響を与えた失敗(決済失敗、データ欠落)

WhaTapコンソールでは各レベルが色分けで表示されます。

活用パターン

決済フローのトレース

const log = window.WhatapBrowserAgent.logger;

log.info('checkout:start', { cartId, items: cartItems.length, total });

try {
  const result = await pay(cartId);
  log.info('checkout:success', { cartId, paymentId: result.id });
} catch (e) {
  log.error('checkout:fail', { cartId, gateway: 'PG_X' }, e);
}

グローバルエラーの補強

デフォルトのエラー収集とは別に、コンテキストを付け加えて送信できます。

window.addEventListener('error', (event) => {
  window.WhatapBrowserAgent.logger.error(
    'uncaught: ' + event.message,
    { filename: event.filename, line: event.lineno },
    event.error
  );
});

送信タイミング

最後の呼び出し以降、約1秒間に追加の呼び出しがなければ、まとめて送信します。
最初の呼び出しから5秒が経過すると、強制的に送信します。
短時間に500件または約512KBが蓄積されると、すぐに送信します。
メッセージ1件は最大8KBまで送信され、それ以上は切り捨てられます。

ほとんどの場合、特別な調整なしにそのまま使用できます。

注意事項

注意	理由
個人情報の直接送信禁止	住民登録番号・カード番号・電話番号などは呼び出し側でマスキングしたうえで送信してください
ループ内での無条件呼び出し禁止	呼び出しが頻繁すぎると、ネットワークに負荷をかける可能性があります
8KB超過メッセージ	自動的に切り捨てられます。大きなペイロードは`context`フィールドに分割してください
オブジェクト・配列を`context`にそのまま渡すのは禁止	無視されます。平坦化するか文字列にシリアライズしてください

非同期ロードと安全な呼び出し

ページが開いた直後にlogger.*を呼び出す必要がある場合は、loggerの存在有無を先に確認してください。

function safeLog(level, message, context, error) {
  const agent = window.WhatapBrowserAgent;
  if (agent && agent.logger && typeof agent.logger[level] === 'function') {
    agent.logger[level](message, context, error);
  }
  // ロード前であれば無視されます。
}

safeLog('info', 'app boot', { route: location.pathname });

Tips

ユーザーイベント(クリック、フォーム送信など)の時点での呼び出しは、通常エージェントのロードが終わった後であるため、別途の防御は必要ありません。上記のパターンはページのブートコードでのみ使用してください。

トラブルシューティング

症状	原因 / 対処
`window.WhatapBrowserAgent.logger`が`undefined`	(1) エージェントが3.0未満のバージョン (2) 非同期ロードがまだ終わっていない (3) CSP・広告ブロックなどでスクリプトがブロックされている
コンソールに`Custom log call was dropped`の警告	`enableCustomLog`が`false`です。configに`enableCustomLog: true`を追加してください。この警告は最初の1回のみ出力されます
呼び出してもネットワークリクエストがない	`enableCustomLog: true`の欠落、`proxyBaseUrl`の未設定、または設定より呼び出しが先に実行された
401 / 403応答	アクセスキーまたは`pcode`のエラー
特定のセッションのログが全て欠落	`sampleRate`により該当セッションが収集対象から除外されています。すべてのセッションを収集するには`sampleRate: 100`に設定してください
一部のログのみ欠落	短時間に500件または約512KB超過分はすぐに送信されます(正常動作)
メッセージが切り捨てられて到着	単一メッセージ8KBの上限。超過分は自動的に切り捨てられます

送信されたログは、WhaTapコンソールの分析 > ユーザーセッションログ検索メニューで確認できます。status、message、contextキー、error.messageなどで検索・フィルタリングしてください。

事前準備​

有効化​

設定オプション​

インターフェース​

使用方法​

基本的な呼び出し​

コンテキストを併せて送信​

エラーを併せて送信​

ログレベル​

活用パターン​

決済フローのトレース​

グローバルエラーの補強​

送信タイミング​

注意事項​

非同期ロードと安全な呼び出し​

トラブルシューティング​