iOS RUM 収集

iOS RUM 収集

Datadog の dd-sdk-ios クライアント側 RUM SDK を使用すると、iOS アプリケーションから Datadog へリアルユーザーモニタリングのデータを送信すると共に、次の機能を利用できます。

  • アプリのパフォーマンスおよびデモグラフィックに関する全体像を把握。
  • 最も遅いリソースを特定。
  • OS およびデバイスタイプ別にエラーを分析。

セットアップ

  1. パッケージマネージャーに応じてライブラリを依存関係として宣言します。最新のベータ版については、Datadog のリリースページを参照してください。

    CocoaPods を使用して、dd-sdk-ios をインストールできます。

    pod 'DatadogSDK'
    

    Apple の Swift Package Manager を使用して SDK を統合するには、Package.swift に以下を依存関係として追加します。

    .package(url: "https://github.com/DataDog/dd-sdk-ios.git", .upToNextMajor(from: "1.0.0"))
    

    Carthage を使用して、dd-sdk-ios をインストールできます。

    github "DataDog/dd-sdk-ios"
    
  2. アプリケーションコンテキストと Datadog クライアントトークンでライブラリを初期化します。セキュリティ上の理由から、クライアントトークンを使用する必要があります。API キーがクライアント側の iOS アプリケーションの IPA バイトコードで公開されてしまうため、Datadog API キーを使用して dd-sdk-ios ライブラリを構成することはできません。クライアントトークンの設定に関する詳細は、クライアントトークンに関するドキュメントを参照してください。また、アプリケーション ID を提供する必要があります (RUM の使用方法ページで説明されているように、Javascript RUM アプリケーションを作成します)。

    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(
                rumApplicationID: "<rum_application-id>",
                clientToken: "<client_token>",
                environment: "<environment_name>"
            )
            .set(serviceName: "app-name")
            .build()
    )
    
    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(
                rumApplicationID: "<rum_application-id>",
                clientToken: "<client_token>",
                environment: "<environment_name>"
            )
            .set(serviceName: "app-name")
            .set(endpoint: .eu)
            .build()
    )
    

    GDPR 規制に準拠するために、SDK では初期化時に trackingConsent 値が必要です。 trackingConsent は、次のいずれかの値になります。

    • .pending - SDK はデータの収集とバッチ処理を開始しますが、Datadog に送信しません。SDK は、新しい追跡同意値がバッチデータをどう処理するかを決定するのを待ちます。
    • .granted - SDK はデータの収集を開始し、Datadog に送信します。
    • .notGranted - SDK はデータを収集しません。ログ、トレース、RUM イベントは Datadog に送信されません。

    SDK の初期化後に追跡同意値を変更するには、Datadog.set(trackingConsent:) API 呼び出しを使用します。 SDK は、新しい値に応じて動作を変更します。たとえば、現在の追跡同意が .pending の場合:

    • .granted に変更すると、SDK は現在および将来のすべてのデータを Datadog に送信します。
    • .notGranted に変更すると、SDK は現在のすべてのデータを消去し、将来のデータを収集しません。
  3. RUM Monitor を構成して登録します。通常は AppDelegate コードで、一度だけ実行する必要があります。

    import Datadog
    
    Global.rum = RUMMonitor.initialize()
    

RUM SDK には、次の 2 つのインスツルメンテーション方法があります。

  • 自動インスツルメンテーション (推奨) - SDK は、ビュー、リソース、アクション、エラーを自動的に追跡します。
  • 手動インスツルメンテーション - コードをインスツルメントして RUM イベントを送信します。

: 両方の方法を混在させることができます。

自動インスツルメンテーション

RUM ビュー

RUM ビューの追跡を有効にするには、SDK を構成するときに .trackUIKitRUMViews() オプションを使用します。

Datadog.Configuration
   .builderUsing(...)
   .trackUIKitRUMViews()
   .build()

Global.rum = RUMMonitor.initialize()

RUM ビューの追跡をカスタマイズするには、.trackUIKitRUMViews(using: predicate) を使用し、UIKitRUMViewsPredicate プロトコルに準拠する predicate の独自の実装を提供します。

public protocol UIKitRUMViewsPredicate {
    func rumView(for viewController: UIViewController) -> RUMView?
}

rumView(for:) 実装内で、アプリは特定の UIViewController インスタンスが RUM ビューを開始するかどうかを決定する必要があります (この場合は nil を返します)。RUMView の戻り値は、少なくとも作成された RUM ビューの path を指定する必要があります。詳細については、コードドキュメントのコメントを参照してください。

: SDK は、アプリの実行中に何度も rumView(for:) を呼び出します。predicate の実装は、SDK 呼び出しの順序に依存しないようにする必要があります。

RUM リソース

RUM リソースの追跡を有効にするには、SDK を構成するときに .track(firstPartyHosts:) オプションを使用します。

Datadog.Configuration
   .builderUsing(...)
   .track(firstPartyHosts: ["your.domain.com"])
   .build()

Global.rum = RUMMonitor.initialize()

また、監視する URLSessiondelegate として DDURLSessionDelegate() を割り当てます。次に例を示します。

let session = URLSession(
    configuration: .default,
    delegate: DDURLSessionDelegate(),
    delegateQueue: nil
)

これにより、SDK は URLSession のこのインスタンスから送信されたリクエストを追跡します。URL が firstPartyHosts と一致するリクエストは、RUM Explorer で “first party” として追加でマークされます。

RUM アクション

RUM アクションの追跡を有効にするには、SDK を構成するときに .trackUIKitActions() オプションを使用します。

Datadog.Configuration
   .builderUsing(...)
   .trackUIKitActions()
   .build()

Global.rum = RUMMonitor.initialize()

これにより、SDK はアプリで発生するすべての重要なタップを追跡します。プライバシー上の理由から、オンスクリーンキーボードによるやり取りはすべて無視されます。

RUM エラー

すべての “error” および “critical” ログは RUM エラーとして報告され、現在の RUM ビューにリンクされます。

logger.error("message")
logger.critical("message")

同様に、エラーとしてマークされたすべての終了した APM スパンは、RUM エラーとして報告されます。

span.setTag(key: OTTags.error, value: true)

手動インスツルメンテーション

RUM ビュー

Global.rum で次のメソッドを使用して、RUM リソースを手動で収集します。

  • .startView(viewController:)
  • .stopView(viewController:)

例:

// `UIViewController` で:

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)
  Global.rum.startView(viewController: self)
}

override func viewDidDisappear(_ animated: Bool) {
  super.viewDidDisappear(animated)
  Global.rum.stopView(viewController: self)
}

詳細と使用可能なオプションについては、DDRUMMonitor クラスのコードドキュメントのコメントを参照してください。

RUM リソース

Global.rum で次のメソッドを使用して、RUM リソースを手動で収集します。

  • .startResourceLoading(resourceKey:request:)
  • .stopResourceLoading(resourceKey:response:)
  • .stopResourceLoadingWithError(resourceKey:error:)
  • .stopResourceLoadingWithError(resourceKey:errorMessage:)

例:

// ネットワーククライアントで:

Global.rum.startResourceLoading(
    resourceKey: "resource-key", 
    request: request
)

Global.rum.stopResourceLoading(
    resourceKey: "resource-key",
    response: response
)

: 両方の呼び出しで resourceKey に使用される String は、呼び出すリソースに対して一意である必要があります。これは、SDK がリソースの開始と完了を一致させるために必要です。

詳細と使用可能なオプションについては、DDRUMMonitor クラスのコードドキュメントのコメントを参照してください。

RUM アクション

瞬間的な RUM アクション (例: .tap) を手動で登録するには、次を使用します。

  • .addUserAction(type:name:)

または、継続的な RUM アクション (例: .scroll) の場合は、次を使用します。

  • .startUserAction(type:name:)
  • および .stopUserAction(type:)

Global.rum

例:

// `UIViewController` で:

@IBAction func didTapDownloadResourceButton(_ sender: Any) {
    Global.rum.addUserAction(
        type: .tap,
        name: (sender as? UIButton).currentTitle ?? "",
    )
}

: .startUserAction(type:name:).stopUserAction(type:) を使用する場合、アクション type は同じである必要があります。これは、SDK がリソースの開始と完了を一致させるために必要です。

詳細と使用可能なオプションについては、DDRUMMonitor クラスのコードドキュメントのコメントを参照してください。

RUM エラー

Global.rum で次のメソッドを使用して、RUM エラーを手動で収集します。

  • .addError(message:)
  • .addError(error:)

例:

// コードのどこでも:

Global.rum.addError(message: "error message.")

詳細と使用可能なオプションについては、DDRUMMonitor クラスのコードドキュメントのコメントを参照してください。

データスクラビング

Datadog に送信される前に RUM イベントの属性を変更したり、イベントを完全に削除したりするには、SDK を構成するときにイベントマッパー API を使用します。

Datadog.Configuration
    .builderUsing(...)
    .setRUMViewEventMapper { viewEvent in 
        return viewEvent
    }
    .setRUMErrorEventMapper { errorEvent in
        return errorEvent
    }
    .setRUMResourceEventMapper { resourceEvent in
        return resourceEvent
    }
    .setRUMActionEventMapper { actionEvent in
        return actionEvent
    }
    .build()

各マッパーは、(T) -> T? のシグネチャを持つ Swift クロージャです。ここで、T は具体的な RUM イベントタイプです。これにより、イベントが送信される前にイベントの一部を変更できます。たとえば、RUM リソースの url で機密情報を編集するには、カスタムの redacted(_:) -> String 関数を実装し、それを RUMResourceEventMapper で使用します。

.setRUMResourceEventMapper { resourceEvent in
    var resourceEvent = resourceEvent
    resourceEvent.resource.url = redacted(resourceEvent.resource.url)
    return resourceEvent
}

エラー、リソース、またはアクションマッパーから nil を返すと、イベントは完全にドロップされます (Datadog に送信されません)。ビューイベントマッパーから返される値は nil であってはなりません。

特定のイベントのタイプに応じて、一部の特定のプロパティのみを変更できます。

イベントタイプ属性キー説明
RUMViewEventviewEvent.view.nameビューの名前
viewEvent.view.urlビューの URL
RUMActionEventactionEvent.action.target?.nameアクションの名前
actionEvent.view.urlこのアクションにリンクされているビューの URL
RUMErrorEventerrorEvent.error.messageエラーメッセージ
errorEvent.error.stackエラーのスタックトレース
errorEvent.error.resource?.urlエラーが参照するリソースの URL
errorEvent.view.urlこのエラーにリンクされているビューの URL
RUMResourceEventresourceEvent.resource.urlリソースの URL
resourceEvent.view.urlこのリソースにリンクされているビューの URL