ブラウザログ収集
Dash が新機能を発表!インシデントマネジメント、Continuous Profiler など多数の機能が追加されました! Dash イベントで発表された新機能!

ブラウザログ収集

Datadog のクライアント側 JavaScript ロギングライブラリ datadog-logs を利用して、Web ブラウザなどの JavaScript クライアントから Datadog にログを送信できます。

datadog-logs ライブラリを使用すると、JS クライアントから Datadog にログを直接送信すると共に、次の機能を利用できます。

  • ライブラリをロガーとして使用する。すべてが JSON ドキュメントとして Datadog に転送されます。
  • 送信される各ログに context およびカスタム属性を追加する。
  • すべてのフロントエンドエラーを自動的にラップして転送する。
  • フロントエンドエラーの送信
  • 実際のクライアント IP アドレスとユーザーエージェントを記録する。
  • 自動一括ポストによってネットワークの利用を最適化する。

セットアップ

  1. Datadog クライアントトークンを取得: セキュリティ上の理由から、API キー を使用して datadog-logs ライブラリを構成することはできません。JavaScript キーでクライアント側に公開されるためです。ウェブブラウザーからログを収集するには、クライアントトークンを使用する必要があります。クライアントトークンの設定に関する詳細は、クライアントトークンに関するドキュメントを参照してください。
  2. NPM を使いDatadog ブラウザのログライブラリを構成するか、バンドルをヘッドタグに直接貼り付けます。

NPM の設定

package.json ファイルに @datadog/browser-logs を追加したら、以下を使い初期化します。

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.init({
  clientToken: '<DATADOG_CLIENT_TOKEN>',
  site: 'datadoghq.com',
  forwardErrorsToLogs: true,
  sampleRate: 100
});
import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.init({
  clientToken: '<DATADOG_CLIENT_TOKEN>',
  site: 'datadoghq.eu',
  forwardErrorsToLogs: true,
  sampleRate: 100
});

バンドルの設定

ログやエラーを取りこぼさないよう、ライブラリのロードと構成をページのヘッドセクションの先頭で行います。

<html>
  <head>
    <title>Example to send logs to Datadog</title>
    <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-logs.js"></script>
    <script>
      window.DD_LOGS && DD_LOGS.init({
        clientToken: '<CLIENT_TOKEN>',
        site: 'datadoghq.com',
        forwardErrorsToLogs: true,
        sampleRate: 100
      });
    </script>
  </head>
</html>
<html>
  <head>
    <title>Example to send logs to Datadog</title>
    <script type="text/javascript" src="https://www.datadoghq-browser-agent.com/datadog-logs.js"></script>
    <script>
      window.DD_LOGS && DD_LOGS.init({
        clientToken: '<CLIENT_TOKEN>',
        site: 'datadoghq.eu',
        forwardErrorsToLogs: true,
        sampleRate: 100
      });
    </script>
  </head>
</html>

: window.DD_LOGS チェックは、ライブラリで読み込みエラーが起きた際に問題を防ぐために使用されます。

初期化パラメーター

以下のパラメーターを使用して、Datadog にログを送信するように Datadog ブラウザのログライブラリを構成できます。

パラメーター種類必須デフォルト説明
clientToken文字列はい-Datadog クライアントトークン
site文字列はいdatadoghq.com所属する組織の Datadog サイト。datadoghq.com はアメリカの Datadog のサイト、 datadoghq.eu は EU の Datadog サイト。
service文字列``このアプリケーションのサービス名。
env文字列``アプリケーションの環境 (例: prod、pre-prod、staging)
version文字列``アプリケーションのバージョン (例: 1.2.3、6c44da20、2020.02.13)
forwardErrorsToLogsBooleanいいえtruefalse に設定すると、console.error ログ、キャッチされない例外、ネットワークエラーは Datadog へ送信されません。
sampleRate数値いいえ100追跡するセッションの割合。追跡されたセッションのみログを送信します。100 は全てを、0 は皆無を意味します。

カスタムログエントリの送信

Datadog ブラウザのログライブラリが初期化されると、API を使用してカスタムログエントリを Datadog へ直接送信します。

logger.debug | info | warn | error (message: string, messageContext = Context)

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.info('Button clicked', { name: 'buttonName', id: 123 });
window.DD_LOGS && DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 });

: window.DD_LOGS チェックは、ライブラリで読み込みエラーが起きた際に問題を防ぐために使用されます。

上の結果は次のようになります。

{
  "status": "info",
  "session_id": "1234",
  "name": "buttonName",
  "id": 123,
  "message": "Button clicked",
  "http": {
    "url": "...",
    "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/44.0.2403.130 Safari/537.36"
  },
  "network": {"client": {"ip": "109.30.xx.xxx"}}
}

ロガーは、デフォルトで次の情報を追加します。

  • view.url
  • session_id
  • http.useragent
  • network.client.ip

パラメーターとしてのステータスの使用

Datadog ブラウザのログライブラリが初期化されると、API を使用してカスタムログエントリをそのステータスをパラメーターとして Datadog へ直接送信します。

log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error')

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
window.DD_LOGS && DD_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
プレースホルダー説明
<MESSAGE>Datadog によって完全にインデックス化されたログメッセージ
<JSON_ATTRIBUTES><MESSAGE> にアタッチされているすべての属性を含む有効な JSON オブジェクト
<STATUS>ログのステータス。使用できるステータス値は、debuginfowarnerror です。

高度な使用方法

複数のロガーの定義

Datadog ブラウザのログライブラリにはデフォルトのロガーが含まれていますが、さまざまなロガーを定義することもできます。これは、同じプロジェクトで複数のチームが作業している場合に便利です。

新しいロガーの作成

Datadog ブラウザのログライブラリが初期化されると、API createLogger を使用して新しいロガーを定義します。

createLogger (name: string, conf?: {
    level?: 'debug' | 'info' | 'warn' | 'error'
    handler?: 'http' | 'console' | 'silent'
    context?: Context
})

: パラメーターは、setLevelsetHandlersetContext API と共に設定することができます。

カスタムロガーを取得

ロガーを作成すると、API を使い JavaScript コードのどこからでもロガーにアクセスすることができます。

getLogger (name: string)

他のロガーと共に、signupLogger のロガーを次のように定義したとします。

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.createLogger('signupLogger', 'info', 'http', {'env': 'staging'})

これで、次のように、このロガーをコードの別の場所で使用できます。

import { datadogLogs } from '@datadog/browser-logs';

const signupLogger = datadogLogs.getLogger('signupLogger')
signupLogger.info('Test sign up completed')
if (window.DD_LOGS) {
    const signupLogger = DD_LOGS.createLogger('signupLogger', 'info', 'http', {'env': 'staging'})
}

これで、次のように、このロガーをコードの別の場所で使用できます。

if (window.DD_LOGS) {
    const signupLogger = DD_LOGS.getLogger('signupLogger')
    signupLogger.info('Test sign up completed')
}

: window.DD_LOGS チェックは、ライブラリで読み込みエラーが起きた際に問題を防ぐために使用されます。

コンテキストの上書き

グローバルコンテキスト

Datadog ブラウザのログライブラリを初期化すると、以下のことが可能になります。

  • setLoggerGlobalContext (context: Context) API を使用して、すべてのロガーのコンテキスト全てを設定。
  • addLoggerGlobalContext (key: string, value: any) API を使用して、あなたのすべてのロガーにコンテキストを追加。
import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.setLoggerGlobalContext("{'env': 'staging'}");

datadogLogs.addLoggerGlobalContext('referrer', document.referrer);
window.DD_LOGS && DD_LOGS.setLoggerGlobalContext({env: 'staging'});

window.DD_LOGS && DD_LOGS.addLoggerGlobalContext('referrer', document.referrer);

: window.DD_LOGS チェックは、ライブラリで読み込みエラーが起きた際に問題を防ぐために使用されます。

ロガーのコンテキスト

ロガーを作成すると、以下のことができます。

  • setContext (context: Context) API を使用して、すべてのロガーのコンテキスト全てを設定。
  • addContext (key: string, value: any) API を使用して、あなたのロガーにコンテキストを追加。
import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.setContext("{'env': 'staging'}");

datadogLogs.addContext('referrer', document.referrer);
window.DD_LOGS && DD_LOGS.setContext("{'env': 'staging'}");

window.DD_LOGS && DD_LOGS.addContext('referrer', document.referrer);

: window.DD_LOGS チェックは、ライブラリで読み込みエラーが起きた際に問題を防ぐために使用されます。

ステータスに基づくフィルタリング

Datadog ブラウザのログライブラリが初期化されると、API を使用してロガーにの最小ログレベルを設定できます。

setLevel (level?: 'debug' | 'info' | 'warn' | 'error')

指定したレベル以上のステータスのログだけが送信されます。

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.setLevel('<レベル>');
window.DD_LOGS && DD_LOGS.logger.setLevel('<LEVEL>');

: window.DD_LOGS チェックは、ライブラリで読み込みエラーが起きた際に問題を防ぐために使用されます。

送信先の変更

デフォルトでは、Datadog ブラウザのログライブラリが作成したロガーは、ログを Datadog に送信します。 Datadog ブラウザのログライブラリが初期化されると、ログを console に送信したり、ログをまったく送信しない (silent) よう、API を使用してロガーを構成することもできます。

setHandler (handler?: 'http' | 'console' | 'silent')

import { datadogLogs } from '@datadog/browser-logs';

datadogLogs.logger.setHandler('<ハンドラー>');
window.DD_LOGS && DD_LOGS.logger.setHandler('<ハンドラー>');

: window.DD_LOGS チェックは、ライブラリで読み込みエラーが起きた際に問題を防ぐために使用されます。

サポートされるブラウザ

datadog-logs ライブラリは、最新のデスクトップブラウザとモバイルブラウザをすべてサポートします。IE10 および IE11 もサポートしています。

その他の参考資料