RUM とトレースの接続

概要

APM と Real User Monitoring のインテグレーションにより、Web およびモバイルアプリケーションからのリクエストを対応するバックエンドトレースにリンクできます。この組み合わせにより、1 つのレンズを通してフロントエンドとバックエンドの完全なデータを確認できます。

RUM のフロントエンドデータに加えて、トレース ID 挿入のバックエンド、インフラストラクチャー、ログ情報を使用して、スタック内の問題を特定し、ユーザーに起こっていることを理解します。

iOS アプリケーションのトレースだけを Datadog に送信し始めるには、iOS トレース収集をご覧ください。

使用方法

前提条件

RUM アプリケーションの対象となるサービスに APM トレースを設定していること。
サービスが HTTP サーバーを使用していること。
HTTP サーバーで、分散型トレーシングをサポートするライブラリが使用されていること。
ご利用の SDK に応じて次の設定を行っていること。
- Browser SDK の場合は、RUM エクスプローラーで XMLHttpRequest (XHR) または Fetch リソースを allowedTracingUrls に追加していること。
- Mobile SDK の場合は、Native または XMLHttpRequest (XHR) を firstPartyHosts に追加していること。
allowedTracingUrls または firstPartyHosts へのリクエストに対応するトレースがあること。

RUM の設定

注: RUM とトレースの構成では、RUM で APM の有料データを使用するため、APM の請求に影響を与える可能性があります。

RUM ブラウザモニタリングを設定します。

RUM SDK を初期化します。ブラウザアプリケーションによって呼び出される内部のファーストパーティオリジンのリストを使用して、allowedTracingUrls 初期化パラメーターを設定します。

npm インストールの場合:

import { datadogRum } from '@datadog/browser-rum'

datadogRum.init({
    applicationId: '<DATADOG_APPLICATION_ID>',
    clientToken: '<DATADOG_CLIENT_TOKEN>',
    ...otherConfig,
    service: "my-web-application",
    allowedTracingUrls: ["https://api.example.com", /https:\/\/.*\.my-api-domain\.com/, (url) => url.startsWith("https://api.example.com")]
})

CDN インストールの場合:

window.DD_RUM.init({
   clientToken: '<CLIENT_TOKEN>',
   applicationId: '<APPLICATION_ID>',
   site: '<http://datadoghq.com|datadoghq.com>',
   //  service: 'my-web-application',
   //  env: 'production',
   //  version: '1.0.0',
   allowedTracingUrls: ["<https://api.example.com>", /https:\/\/.*\.my-api-domain\.com/, (url) => url.startsWith("<https://api.example.com>")]
   sessionSampleRate: 100,
   sessionReplaySampleRate: 100, // if not included, the default is 100
   trackResources: true,
   trackLongTasks: true,
   trackUserInteractions: true,
 })

RUM をトレースに接続するには、service フィールドにブラウザアプリケーションを指定する必要があります。

allowedTracingUrls は完全な URL (<scheme>://<host>[:<port>]/<path>[?<query>][#<fragment>]) に一致します。次のタイプを指定できます。

string: 指定した値で始まるすべての URL に一致します。したがって、https://api.example.com は https://api.example.com/v1/resource に一致します。
RegExp: 指定された正規表現と URL で検証を実行します。
function: URL をパラメーターとして評価を実行します。戻り値の boolean が true に設定されていた場合は、一致することを示します。

(オプション) traceSampleRate 初期化パラメーターを構成して、バックエンドトレースの定義されたパーセンテージを保持するように設定します。設定しない場合、ブラウザのリクエストから来るトレースの 100% が Datadog に送信されます。バックエンドトレースの 20% を保持する場合:
```
import { datadogRum } from '@datadog/browser-rum'

datadogRum.init({
    ...otherConfig,
    traceSampleRate: 20
})
```

注: traceSampleRate は RUM セッションのサンプリングには影響しません。バックエンドのトレースのみがサンプリングされます。

ブラウザ SDK の初期化後に生成されたリクエストには、エンドツーエンドのトレーシングを利用できます。初めの HTML 文書のエンドツーエンドトレースおよび始めのブラウザリクエストはサポートされません。

RUM Android モニタリングを設定します。
Android アプリケーションによって呼び出される内部のファーストパーティオリジンのリストを使用して、OkHttpClient インターセプターを構成します。
```
val tracedHosts = listOf("example.com", "example.eu")

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(DatadogInterceptor(tracedHosts))
    .addNetworkInterceptor(TracingInterceptor(tracedHosts))
    .eventListenerFactory(DatadogEventListener.Factory())
   .build()
```
デフォルトでは、リストされたホストのすべてのサブドメインがトレースされます。たとえば、example.com を追加すると、api.example.com と foo.example.com のトレースも有効になります。
(オプション) traceSamplingRate パラメーターを構成して、バックエンドトレースの定義されたパーセンテージを保持するように設定します。設定しない場合、アプリケーションのリクエストから来るトレースの 20% が Datadog に送信されます。バックエンドトレースの 100% を保持する場合:

    val okHttpClient = OkHttpClient.Builder()
        .addInterceptor(RumInterceptor(traceSamplingRate = 100f))
       .build()

注: traceSamplingRate は RUM セッションのサンプリングには影響しません。バックエンドのトレースのみがサンプリングされます。

RUM iOS モニタリングを設定します。

iOS アプリケーションによって呼び出される内部のファーストパーティオリジンのリストを使用して、ビルダー関数 trackURLSession(firstPartyHosts:) を呼び出します。

Datadog.initialize(
    appContext: .init(),
    configuration: Datadog.Configuration
        .builderUsing(
            rumApplicationID: "<rum_app_id>", 
            clientToken: "<client_token>", 
            environment: "<env_name>"
        )
        .trackURLSession(firstPartyHosts: ["example.com", "api.yourdomain.com"])
        .build()
)

グローバル Tracer を初期化します。

Global.sharedTracer = Tracer.initialize(
    configuration: Tracer.Configuration(...)
)

セットアップにあるように、URLSession を初期化します。
```
let session =  URLSession(
    configuration: ...,
    delegate: DDURLSessionDelegate(),
    delegateQueue: ...
)
```
デフォルトでは、リストされたホストのすべてのサブドメインがトレースされます。たとえば、example.com を追加すると、api.example.com と foo.example.com のトレースも有効になります。
URLSession に URLRequest を指定した場合、トレース ID 挿入が機能します。URL オブジェクトを使用した場合、分散型トレーシングは機能しません。
(オプション) tracingSamplingRate 初期化パラメーターを設定して、バックエンドトレースの定義されたパーセンテージを保持するように設定します。設定しない場合、アプリケーションのリクエストから来るトレースの 20% が Datadog に送信されます。
バックエンドトレースの 100% を保持する場合:
```
Datadog.initialize(
    appContext: .init(),
    configuration: Datadog.Configuration
        .builderUsing(rumApplicationID: "<rum_app_id>", clientToken: "<client_token>", environment: "<env_name>")
        .set(tracingSamplingRate: 100)
        .build()
)
```

注: tracingSamplingRate は RUM セッションのサンプリングには影響しません。バックエンドのトレースのみがサンプリングされます。

RUM React Native モニタリングを設定します。
firstPartyHosts の初期化パラメーターを設定して、React Native アプリケーションが呼び出す内部のファーストパーティオリジンのリストを定義します。
```
const config = new DatadogProviderConfiguration(
    // ...
);
config.firstPartyHosts = ["example.com", "api.yourdomain.com"];
```
デフォルトでは、リストされたホストのすべてのサブドメインがトレースされます。たとえば、example.com を追加すると、api.example.com と foo.example.com のトレースも有効になります。
(オプション) resourceTracingSamplingRate 初期化パラメーターを設定して、バックエンドトレースの定義されたパーセンテージを保持するように設定します。設定しない場合、アプリケーションのリクエストから来るトレースの 20% が Datadog に送信されます。
バックエンドトレースの 100% を保持する場合:
```
const config = new DatadogProviderConfiguration(
    // ...
);
config.resourceTracingSamplingRate = 100;
```
注: resourceTracingSamplingRate は RUM セッションのサンプリングには影響しません。バックエンドのトレースのみがサンプリングされます。

RUM Flutter モニタリングを設定します。
Automatic Resource Tracking の説明に従って、Datadog Tracking HTTP Client パッケージを含め、HTTP 追跡を有効にします。これには、Flutter アプリケーションによって呼び出される内部、ファーストパーティーのオリジンのリストを追加するために、初期化に対する以下の変更が含まれます。
```
final configuration = DdSdkConfiguration(
  // ...
  // added configuration
  firstPartyHosts: ['example.com', 'api.yourdomain.com'],
)..enableHttpTracking()
```

RUM for Roku はベータ版です。

RUM Roku モニタリングを設定します。

ネットワークリクエストを行うには、datadogroku_DdUrlTransfer コンポーネントを使用します。

    ddUrlTransfer = datadogroku_DdUrlTransfer(m.global.datadogRumAgent)
    ddUrlTransfer.SetUrl(url)
    ddUrlTransfer.EnablePeerVerification(false)
    ddUrlTransfer.EnableHostVerification(false)
    result = ddUrlTransfer.GetToString()

サポートされるライブラリ

以下の Datadog トレーシングライブラリがサポートされています。

ライブラリ	最小バージョン
Python	0.22.0
Go	1.10.0
Java	0.24.1
Ruby	0.20.0
JavaScript	0.10.0
PHP	0.33.0
.NET	1.18.2

OpenTelemetry のサポート

RUM は、OpenTelemetry ライブラリを使ってインスツルメントされたバックエンドとリソースを接続するため、複数のプロパゲータータイプをサポートしています。

上記に従い、RUM を APM に接続するためのセットアップを行います。
allowedTracingUrls を次のように変更します。
```
import { datadogRum } from '@datadog/browser-rum'

datadogRum.init({
    ...otherConfig,
    allowedTracingUrls: [
      { match: "https://api.example.com", propagatorTypes: ["tracecontext"]}
    ]
})
```
match では、上記のようにシンプルな形式で使用した場合と同じパラメータータイプ (string、RegExp、function) を指定できます。
propagatorTypes には、使用したいプロパゲーターに対応する文字列をリストで指定します。
- datadog: Datadog のプロパゲーター (x-datadog-*)
- tracecontext: W3C Trace Context (traceparent)
- b3: B3 シングルヘッダー (b3)
- b3multi: B3 マルチヘッダー (X-B3-*)

上記に従い、RUM を APM に接続するためのセットアップを行います。
次のように、trackURLSession(firstPartyHosts:) の代わりに trackURLSession(firstPartyHostsWithHeaderTypes:) を使用します。
```
Datadog.initialize(
    appContext: .init(),
    configuration: Datadog.Configuration
        .builderUsing(
            rumApplicationID: "<rum_app_id>", 
            clientToken: "<client_token>", 
            environment: "<env_name>"
        )
        .trackURLSession(
            firstPartyHostsWithHeaderTypes: [
                "api.example.com": [.tracecontext]
            ]
        )
        .build()
    )
```
trackURLSession(firstPartyHostsWithHeaderTypes:) には Dictionary<String, Set<TracingHeaderType>> をパラメーターとして指定します。キーはホスト、値はサポートされるサポートトレーシングヘッダータイプのリストになります。
TracingHeaderType は列挙型で、次のトレーシングヘッダータイプを表します。
- .datadog: Datadog のプロパゲーター (x-datadog-*)
- .tracecontext: W3C Trace Context (traceparent)
- .b3: B3 シングルヘッダー (b3)
- .b3multi: B3 マルチヘッダー (X-B3-*)

上記に従い、RUM を APM に接続するためのセットアップを行います。
内部のファーストパーティオリジンのリストと、使用するトレーシングヘッダータイプを指定して、次のように OkHttpClient インターセプターを構成します。
```
val tracedHosts = mapOf("example.com" to setOf(TracingHeaderType.TRACECONTEXT), 
                      "example.eu" to setOf(TracingHeaderType.DATADOG))

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(DatadogInterceptor(tracedHosts))
    .addNetworkInterceptor(TracingInterceptor(tracedHosts))
    .eventListenerFactory(DatadogEventListener.Factory())
   .build()
```
TracingHeaderType は列挙型で、次のトレーシングヘッダータイプを表します。
- .DATADOG: Datadog のプロパゲーター (x-datadog-*)
- .TRACECONTEXT: W3C Trace Context (traceparent)
- .B3: B3 シングルヘッダー (b3)
- .B3MULTI: B3 マルチヘッダー (X-B3-*)

RUM を APM と接続するように設定します。
内部のファーストパーティオリジンのリストと、使用するトレーシングヘッダータイプを指定して、次のように RUM SDK を構成します。
```
const config = new DatadogProviderConfiguration(
    // ...
);
config.firstPartyHosts = [
    {match: "example.com", propagatorTypes: PropagatorType.TRACECONTEXT},
    {match: "example.com", propagatorTypes: PropagatorType.DATADOG}
];
```
PropagatorType は列挙型で、次のトレーシングヘッダータイプを表します。
- PropagatorType.DATADOG: Datadog のプロパゲーター (x-datadog-*)
- PropagatorType.TRACECONTEXT: W3C Trace Context (traceparent)
- PropagatorType.B3: B3 シングルヘッダー (b3)
- PropagatorType.B3MULTI: B3 マルチヘッダー (X-B3-*)

上記に従い、RUM を APM に接続するためのセットアップを行います。
以下のように、firstPartyHosts の代わりに firstPartyHostsWithTracingHeaders を使用します。
```
final configuration = DdSdkConfiguration(
  // ...
  // added configuration
  firstPartyHostsWithTracingHeaders: {
    'example.com': { TracingHeaderType.tracecontext },
  },
)..enableHttpTracking()
```
firstPartyHostsWithTracingHeaders には Map<String, Set<TracingHeaderType>> をパラメーターとして指定します。キーはホスト、値はサポートされるサポートトレーシングヘッダータイプのリストになります。
TracingHeaderType は列挙型で、次のトレーシングヘッダータイプを表します。
- TracingHeaderType.datadog: Datadog のプロパゲーター (x-datadog-*)
- TracingHeaderType.tracecontext: W3C Trace Context (traceparent)
- TracingHeaderType.b3: B3 シングルヘッダー (b3)
- TracingHeaderType.b3multi: B3 マルチヘッダー (X-B3-*)

RUM リソースはどのようにトレースにリンクされていますか？

Datadog は分散型トレーシングプロトコルを使用し、次の HTTP ヘッダーをセットアップします。

x-datadog-trace-id: リアルユーザーモニタリング SDK から生成されます。Datadog がトレースを RUM リソースにリンクできるようにします。

x-datadog-parent-id Real User Monitoring SDK から生成されます。Datadog がトレースから最初のスパンを生成できるようにします。

x-datadog-origin: rum リアルユーザーモニタリングから生成されたトレースが、APM インデックススパン数に影響を与えないようにします。

x-datadog-sampling-priority: 1: Agent がトレースを保持できるようにします。

traceparent: [version]-[trace id]-[parent id]-[trace flags]: version: 現行の仕様では、バージョンは 00 に設定することを想定しています。; trace id: 128 ビットのトレース ID (16 進数で 32 桁)。ソーストレース ID は APM との互換性を維持するため 64 ビットになっています。; parent id: 64 ビットのスパン ID (16 進数で 16 桁)。; trace flags: サンプリングあり (01)、またはサンプリングなし (00)
例:: traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331s-01

b3: [trace id]-[span id]-[sampled]: trace id: 64 ビットのトレース ID (16 進数で 16 桁)。; span id: 64 ビットのスパン ID (16 進数で 16 桁)。; sampled: True (1) または False (0)
b3 シングルヘッダーの例:: b3: 8448eb211c80319c-b7ad6b7169203331-1
b3 マルチヘッダーの例:: X-B3-TraceId: 8448eb211c80319c; X-B3-SpanId: b7ad6b7169203331; X-B3-Sampled: 1

上記 HTTP ヘッダーは CORS セーフリストに登録されていないため、SDK が監視するように設定されているリクエストを扱うサーバーで Access-Control-Allow-Headers を構成する必要があります。サーバーは、すべてのリクエストの前に SDK によって作られるプレフライトリクエストも許可する必要があります (OPTIONS リクエスト)。