ブラウザログ SDK で、Web ブラウザや JavaScript クライアントから Datadog にログを送信できます。
ブラウザログ SDK を使用すると、JS クライアントから Datadog にログを直接送信すると共に、次の機能を利用できます。
context およびカスタム属性を追加する。Datadog クライアントトークン: セキュリティ上の理由から、API キー を使用してブラウザログ SDK を構成することはできません。JavaScript コードでクライアント側に公開されるためです。ウェブブラウザーからログを収集するには、クライアントトークンを使用する必要があります。詳細は、クライアントトークンに関するドキュメントを参照してください。
Datadog ブラウザログ SDK: NPM を使用して SDK を構成するか、head タグで CDN 非同期 または CDN 同期 コードスニペットを使用します。
対応ブラウザ: ブラウザログ SDK は、IE10 および IE11 を含む最新のデスクトップブラウザとモバイルブラウザをすべてサポートします。下記のブラウザサポート表をご参照ください。
| インストール方法 | 使用例 |
|---|---|
| npm (node package manager) | 最新の Web アプリケーションには、この方法が推奨されます。ブラウザログ SDK は、残りのフロントエンド JavaScript コードとともにパッケージ化されます。ページの読み込みパフォーマンスに影響は出ませんが、SDK が初期化される前にトリガーされたエラー、リソース、ユーザーアクションは取りこぼされる場合があります。注: 使用する場合、RUM SDK と一致するバージョンの使用が推奨されます。 |
| CDN 非同期 | この方法は、パフォーマンス目標のある Web アプリケーションに推奨されます。ブラウザログ SDK は、CDN から非同期的に読み込まれます。この方法を使用すると、SDK のダウンロードによるページの読み込みパフォーマンスへの影響を回避できます。ただし、SDK が初期化される前にトリガーされたエラー、リソース、ユーザーアクションは取りこぼされる場合があります。 |
| CDN 同期 | この方法は、すべての RUM イベントを収集する場合に推奨されます。ブラウザログ SDK は、CDN から同期的に読み込まれます。この方法を使用すると、最初に SDK を読み込み、すべてのエラー、リソース、ユーザーアクションを収集することができます。この方法は、ページの読み込みパフォーマンスに影響を与える可能性があります。 |
package.json ファイルに @datadog/browser-logs を追加したら、以下を使い初期化します。
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.init({
clientToken: '<DATADOG_CLIENT_TOKEN>',
site: '<DATADOG_SITE>',
forwardErrorsToLogs: true,
sampleRate: 100,
})
ページの head セクションで SDK の読み込みと構成を行います。
<html>
<head>
<title>Example to send logs to Datadog</title>
<script>
(function(h,o,u,n,d) {
h=h[d]=h[d]||{q:[],onReady:function(c){h.q.push(c)}}
d=o.createElement(u);d.async=1;d.src=n
n=o.getElementsByTagName(u)[0];n.parentNode.insertBefore(d,n)
})(window,document,'script','https://www.datadoghq-browser-agent.com/datadog-logs.js','DD_LOGS')
DD_LOGS.onReady(function() {
DD_LOGS.init({
clientToken: 'XXX',
site: 'datadoghq.com',
forwardErrorsToLogs: true,
sampleRate: 100,
})
})
</script>
</head>
</html>
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
すべてのログとエラーを受信するには、ページの head セクションの先頭で SDK を読み込み構成します。
<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: '<DATADOG_SITE>',
forwardErrorsToLogs: true,
sampleRate: 100,
})
</script>
</head>
</html>
注: window.DD_LOGS チェックは、SDK で読み込みエラーが起きた際に問題を防ぐために使用されます。
タイプは TypeScript >= 3.0 と互換性があります。以前のバージョンの場合は、JS ソースをインポートし、グローバル変数を使用してコンパイルの問題を回避します。
import '@datadog/browser-logs/bundle/datadog-logs'
window.DD_LOGS.init({
clientToken: '<CLIENT_TOKEN>',
site: '<DATADOG_SITE>',
forwardErrorsToLogs: true,
sampleRate: 100,
})
以下のパラメーターを使用して、Datadog にログを送信するように Datadog ブラウザログ SDK を構成できます。
| パラメーター | タイプ | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
clientToken | 文字列 | 〇 | Datadog クライアントトークン。 | |
site | 文字列 | 〇 | datadoghq.com | 組織の Datadog サイト。US: datadoghq.com、EU: datadoghq.eu |
service | 文字列 | ✕ | アプリケーションのサービス名。 | |
env | 文字列 | ✕ | アプリケーションの環境 (例: prod、pre-prod、staging) | |
version | 文字列 | ✕ | アプリケーションのバージョン (例: 1.2.3、6c44da20、2020.02.13) | |
forwardErrorsToLogs | Boolean | ✕ | true | false に設定すると、console.error ログ、キャッチされない例外、ネットワークエラーは Datadog へ送信されません。 |
sampleRate | 数値 | ✕ | 100 | 追跡するセッションの割合。100 は全てを、0 は皆無を意味します。追跡されたセッションのみがログを送信します。 |
silentMultipleInit | Boolean | ✕ | 複数の init を使用しながらログエラーを防ぎます。 |
RUM SDK を使用するときに一致するコンフィギュレーションが必要なオプション:
| パラメーター | タイプ | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
trackSessionAcrossSubdomains | Boolean | ✕ | false | 同じサイトのサブドメイン間でセッションを保持します。 |
useSecureSessionCookie | Boolean | ✕ | false | 安全なセッション Cookie を使用します。これにより、安全でない (HTTPS 以外の) 接続で送信されるログが無効になります。 |
useCrossSiteSessionCookie | Boolean | ✕ | false | 安全なクロスサイトセッション Cookie を使用します。これにより、サイトが別のサイトから読み込まれたときに、logs SDK を実行できます (iframe)。useSecureSessionCookie を意味します。 |
Datadog ブラウザログ SDK が初期化されると、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 })
DD_LOGS.onReady(function () {
DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })
})
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
window.DD_LOGS && DD_LOGS.logger.info('Button clicked', { name: 'buttonName', id: 123 })
注: window.DD_LOGS チェックは、SDK で読み込みエラーが起きた際に問題を防ぐために使用されます。
結果は、NPM、CDN 非同期、CDN 同期を使用した時と同じです。
{
"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.urlsession_idhttp.useragentnetwork.client.ipDatadog ブラウザログ SDK が初期化されると、ステータスをパラメーターとして使用して、API でカスタムログエントリを Datadog へ送信します。
log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error')
NPM の場合は以下を使用します。
import { datadogLogs } from '@datadog/browser-logs';
datadogLogs.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
CDN 非同期の場合は以下を使用します。
DD_LOGS.onReady(function() {
DD_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
})
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
CDN 同期の場合は以下を使用します。
window.DD_LOGS && DD_LOGS.logger.log(<MESSAGE>,<JSON_ATTRIBUTES>,<STATUS>);
上記例のプレースホルダーは、以下に説明されています。
| プレースホルダー | 説明 |
|---|---|
<MESSAGE> | Datadog によって完全にインデックス化されたログメッセージ。 |
<JSON_ATTRIBUTES> | <MESSAGE> にアタッチされているすべての属性を含む有効な JSON オブジェクト。 |
<STATUS> | ログのステータス。使用できるステータス値は、debug、info、warn、error。 |
Browser ログに編集が必要な機密情報が含まれている場合は、Browser Log Collector を初期化するときに beforeSend コールバックを使用して、機密シーケンスをスクラブするように Browser SDK を構成します。
beforeSend コールバック関数を使用すると、Datadog に送信される前に Browser SDK によって収集された各イベントにアクセスでき、一般的に編集されたプロパティを更新できます。
たとえば、Web アプリケーションの URL からメールアドレスを編集するには
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.init({
...,
beforeSend: (event) => {
// ビューの URL からメールを削除します
event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
},
...
});
DD_LOGS.onReady(function() {
DD_LOGS.init({
...,
beforeSend: (event) => {
// ビューの URL からメールを削除します
event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
},
...
})
})
window.DD_LOGS &&
window.DD_LOGS.init({
...,
beforeSend: (event) => {
// ビューの URL からメールを削除します
event.view.url = event.view.url.replace(/email=[^&]*/, "email=REDACTED")
},
...
});
次のイベントプロパティを更新できます。
| 属性 | タイプ | 説明 |
|---|---|---|
view.url | 文字列 | アクティブな Web ページの URL。 |
view.referrer | 文字列 | 現在リクエストされているページへのリンクがたどられた前のウェブページの URL。 |
message | 文字列 | ログの内容。 |
error.stack | 文字列 | スタックトレースまたはエラーに関する補足情報。 |
http.url | 文字列 | HTTP URL。 |
注: Browser SDK は、上記にリストされていないイベントプロパティに加えられた変更を無視します。イベントプロパティの詳細については、Browser SDK リポジトリを参照してください。
Datadog ブラウザログ SDK にはデフォルトのロガーが含まれていますが、さまざまなロガーを定義することもできます。
Datadog ブラウザログ SDK を初期化したら、API createLogger を使用して新しいロガーを定義します。
createLogger (name: string, conf?: {
level?: 'debug' | 'info' | 'warn' | 'error',
handler?: 'http' | 'console' | 'silent',
context?: Context
})
注: パラメーターは、setLevel、setHandler、setContext 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')
たとえば、他のロガーと共に定義された signupLogger があります。
DD_LOGS.onReady(function () {
const signupLogger = DD_LOGS.createLogger('signupLogger', 'info', 'http', { env: 'staging' })
})
これで、次のように、このロガーをコードの別の場所で使用できます。
DD_LOGS.onReady(function () {
const signupLogger = DD_LOGS.getLogger('signupLogger')
signupLogger.info('Test sign up completed')
})
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
たとえば、他のロガーと共に定義された signupLogger があります。
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 チェックは、SDK で読み込みエラーが起きた際に問題を防ぐために使用されます。
Datadog ブラウザログ SDK を初期化すると、以下のことが可能になります。
setLoggerGlobalContext (context: Context) API を使用して、すべてのロガーのコンテキスト全てを設定。addLoggerGlobalContext (key: string, value: any) API を使用して、あなたのすべてのロガーにコンテキストを追加。getLoggerGlobalContext () API を使用して、グローバルコンテキスト全体を取得。NPM の場合は以下を使用します。
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.setLoggerGlobalContext({ env: 'staging' })
datadogLogs.addLoggerGlobalContext('referrer', document.referrer)
const context = datadogLogs.getLoggerGlobalContext() // => {env: 'staging', referrer: ...}
CDN 非同期の場合は以下を使用します。
DD_LOGS.onReady(function () {
DD_LOGS.setLoggerGlobalContext({ env: 'staging' })
})
DD_LOGS.onReady(function () {
DD_LOGS.addLoggerGlobalContext('referrer', document.referrer)
})
DD_LOGS.onReady(function () {
var context = DD_LOGS.getLoggerGlobalContext() // => {env: 'staging', referrer: ...}
})
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
CDN 同期の場合は以下を使用します。
window.DD_LOGS && DD_LOGS.setLoggerGlobalContext({ env: 'staging' })
window.DD_LOGS && DD_LOGS.addLoggerGlobalContext('referrer', document.referrer)
var context = window.DD_LOGS && DD_LOGS.getLoggerGlobalContext() // => {env: 'staging', referrer: ...}
注: window.DD_LOGS チェックは、SDK で読み込みエラーが起きた際に問題を防ぐために使用されます。
ロガーを作成すると、以下のことができます。
setContext (context: Context) API を使用して、すべてのロガーのコンテキスト全てを設定。addContext (key: string, value: any) API を使用して、あなたのロガーにコンテキストを追加。NPM の場合は以下を使用します。
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.setContext("{'env': 'staging'}")
datadogLogs.addContext('referrer', document.referrer)
CDN 非同期の場合は以下を使用します。
DD_LOGS.onReady(function () {
DD_LOGS.setContext("{'env': 'staging'}")
})
DD_LOGS.onReady(function () {
DD_LOGS.addContext('referrer', document.referrer)
})
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
CDN 同期の場合は以下を使用します。
window.DD_LOGS && DD_LOGS.setContext("{'env': 'staging'}")
window.DD_LOGS && DD_LOGS.addContext('referrer', document.referrer)
注: window.DD_LOGS チェックは、SDK で読み込みエラーが起きた際に問題を防ぐために使用されます。
Datadog ブラウザログ SDK が初期化されると、API を使用してロガーの最小ログレベルが設定されます。
setLevel (level?: 'debug' | 'info' | 'warn' | 'error')
指定したレベル以上のステータスのログだけが送信されます。
NPM の場合は以下を使用します。
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.logger.setLevel('<LEVEL>')
CDN 非同期の場合は以下を使用します。
DD_LOGS.onReady(function () {
DD_LOGS.logger.setLevel('<LEVEL>')
})
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
CDN 同期の場合は以下を使用します。
window.DD_LOGS && DD_LOGS.logger.setLevel('<LEVEL>')
注: window.DD_LOGS チェックは、SDK で読み込みエラーが起きた際に問題を防ぐために使用されます。
デフォルトでは、Datadog ブラウザログ SDK が作成したロガーは、ログを Datadog に送信します。
Datadog ブラウザログ SDK が初期化されると、ログを console に送信したり、ログをまったく送信しない (silent) よう、API を使用してロガーを構成することもできます。
setHandler (handler?: 'http' | 'console' | 'silent')
NPM の場合は以下を使用します。
import { datadogLogs } from '@datadog/browser-logs'
datadogLogs.logger.setHandler('<HANDLER>')
CDN 非同期の場合は以下を使用します。
DD_LOGS.onReady(function () {
DD_LOGS.logger.setHandler('<HANDLER>')
})
注: 始めの API 呼び出しは DD_LOGS.onReady() コールバックにラップされている必要があります。こうすることで、SDK が適切に読み込まれたときにのみコードが実行されるようにできます。
CDN 同期の場合は以下を使用します。
window.DD_LOGS && DD_LOGS.logger.setHandler('<HANDLER>')
注: window.DD_LOGS チェックは、SDK で読み込みエラーが起きた際に問題を防ぐために使用されます。