概要

Datadog の dd-sdk-ios クライアント側ロギングライブラリを使用すると、iOS アプリケーションから Datadog へログを送信すると共に、次の機能を利用できます。

  • Datadog に JSON 形式でネイティブに記録する。
  • デフォルトを使用し、送信される各ログにカスタム属性を追加する。
  • 実際のクライアント IP アドレスとユーザーエージェントを記録する。
  • 自動一括ポストによって最適化されたネットワークの利用を活用します。

dd-sdk-ios ライブラリは、iOS 11 以降の全バージョンをサポートしています。

セットアップ

  1. パッケージマネージャーに応じてライブラリを依存関係として宣言します。

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

    pod 'DatadogSDK'
    

    Apple の Swift Package Manager を使用して統合するには、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 ライブラリを構成することはできません。

    クライアントトークンのセットアップについて、詳しくはクライアントトークンに関するドキュメントを参照してください。

    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(clientToken: "<client_token>", environment: "<environment_name>")
            .set(serviceName: "app-name")
            .set(endpoint: .us1)
            .build()
    )
    
    DDConfigurationBuilder *builder = [DDConfiguration builderWithClientToken:@"<client_token>"
                                                                environment:@"<environment_name>"];
    [builder setWithServiceName:@"app-name"];
    [builder setWithEndpoint:[DDEndpoint us1]];
    
    [DDDatadog initializeWithAppContext:[DDAppContext new]
                        trackingConsent:trackingConsent
                        configuration:[builder build]];
    

    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(clientToken: "<client_token>", environment: "<environment_name>")
            .set(serviceName: "app-name")
            .set(endpoint: .eu1)
            .build()
    )
    
    DDConfigurationBuilder *builder = [DDConfiguration builderWithClientToken:@"<client_token>"
                                                                environment:@"<environment_name>"];
    [builder setWithServiceName:@"app-name"];
    [builder setWithEndpoint:[DDEndpoint eu1]];
    
    [DDDatadog initializeWithAppContext:[DDAppContext new]
                         trackingConsent:trackingConsent
                         configuration:[builder build]];
    

    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(clientToken: "<client_token>", environment: "<environment_name>")
            .set(serviceName: "app-name")
            .set(endpoint: .us3)
            .build()
    )
    
    DDConfigurationBuilder *builder = [DDConfiguration builderWithClientToken:@"<client_token>"
                                                                environment:@"<environment_name>"];
    [builder setWithServiceName:@"app-name"];
    [builder setWithEndpoint:[DDEndpoint us3]];
    
    [DDDatadog initializeWithAppContext:[DDAppContext new]
                        trackingConsent:trackingConsent
                        configuration:[builder build]];
    

    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(clientToken: "<client_token>", environment: "<environment_name>")
            .set(serviceName: "app-name")
            .set(endpoint: .us5)
            .build()
    )
    
    DDConfigurationBuilder *builder = [DDConfiguration builderWithClientToken:@"<client_token>"
                                                                environment:@"<environment_name>"];
    [builder setWithServiceName:@"app-name"];
    [builder setWithEndpoint:[DDEndpoint us5]];
    
    [DDDatadog initializeWithAppContext:[DDAppContext new]
                        trackingConsent:trackingConsent
                        configuration:[builder build]];
    

    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(clientToken: "<client_token>", environment: "<environment_name>")
            .set(serviceName: "app-name")
            .set(endpoint: .us1_fed)
            .build()
    )
    
    DDConfigurationBuilder *builder = [DDConfiguration builderWithClientToken:@"<client_token>"
                                                                environment:@"<environment_name>"];
    [builder setWithServiceName:@"app-name"];
    [builder setWithEndpoint:[DDEndpoint us1_fed]];
    
    [DDDatadog initializeWithAppContext:[DDAppContext new]
                        trackingConsent:trackingConsent
                        configuration:[builder build]];
    

    Datadog.initialize(
        appContext: .init(),
        trackingConsent: trackingConsent,
        configuration: Datadog.Configuration
            .builderUsing(clientToken: "<client_token>", environment: "<environment_name>")
            .set(serviceName: "app-name")
            .set(endpoint: .ap1)
            .build()
    )
    
    DDConfigurationBuilder *builder = [DDConfiguration builderWithClientToken:@"<client_token>"
                                                                environment:@"<environment_name>"];
    [builder setWithServiceName:@"app-name"];
    [builder setWithEndpoint:[DDEndpoint ap1]];
    
    [DDDatadog initializeWithAppContext:[DDAppContext new]
                        trackingConsent:trackingConsent
                        configuration:[builder 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 は現在のすべてのデータを消去し、今後のデータを収集しません。

    データは Datadog にアップロードされる前に、アプリケーションサンドボックスのキャッシュディレクトリ (Library/Caches) に平文で保存され、デバイスにインストールされた他のアプリからは読み取ることができません。

    アプリケーションを作成する際、開発ログを有効にし、提供されたレベルと同等以上の優先度を持つ SDK のすべての内部メッセージをコンソールにログ出力するようにしてください。

    Datadog.verbosityLevel = .debug
    
    DDDatadog.verbosityLevel = DDSDKVerbosityLevelDebug;
    
  3. Logger の構成:

    ```swift
    let logger = Logger.builder
        .sendNetworkInfo(true)
        .printLogsToConsole(true, usingFormat: .shortWith(prefix: "[iOS App] "))
        .set(datadogReportingThreshold: .info)
        .build()
    ```
    
    ```objective-c
    DDLoggerBuilder *builder = [DDLogger builder];
    [builder sendNetworkInfo:YES];
    [builder setWithDatadogReportingThreshold:.info];
    [builder printLogsToConsole:YES];
    
    DDLogger *logger = [builder build];
    ```
    
  4. 次のいずれかのメソッドで、カスタムログエントリを Datadog に直接送信します。

    ```swift
    logger.debug("A debug message.")
    logger.info("Some relevant information?")
    logger.notice("Have you noticed?")
    logger.warn("An important warning...")
    logger.error("An error was met!")
    logger.critical("Something critical happened!")
    ```
    
    ```objective-c
    [logger debug:@"A debug message."];
    [logger info:@"Some relevant information?"];
    [logger notice:@"Have you noticed?"];
    [logger warn:@"An important warning..."];
    [logger error:@"An error was met!"];
    [logger critical:@"Something critical happened!"];
    ```
    
  5. (任意) ログメッセージと一緒に attributes のマップを提供し、発行されたログに属性を追加します。マップの各エントリーは属性として追加されます。

    ```swift
    logger.info("Clicked OK", attributes: ["context": "onboarding flow"])
    ```
    
    ```objective-c
    [logger info:@"Clicked OK" attributes:@{@"context": @"onboarding flow"}];
    ```
    

高度なロギング

初期化

ログを Datadog に送信するようにロガーを初期化する際に、Logger.Builder の次のメソッドを使用できます。

メソッド説明
sendNetworkInfo(true)すべてのログに network.client.* 属性を追加します。デフォルトで記録されるデータには、reachability (yesnomaybe)、available_interfaces (wificellular など)、sim_carrier.name (例: AT&T - US)、sim_carrier.technology (3GLTE など)、sim_carrier.iso_country (例: US)があります。
set(serviceName: "<サービス名>")Datadog に送信されるすべてのログに添付される service 標準属性 の値として <サービス名> を設定します。
printLogsToConsole(true)デバッガコンソールにログを送信するには、true とします。
sendLogsToDatadog(true)Datadog にログを送信するには、true とします。
set(loggerName: "<ロガー名>")Datadog に送信されるすべてのログに添付される logger.name 標準属性の値として <ロガー名> を設定します。
build()すべてのオプションを設定して新しいロガーインスタンスをビルドします。

グローバルコンフィギュレーション

以下の方法に従って、指定されたロガーによって送信されるすべてのログにタグと属性を追加または削除します。

グローバルタグ

タグを追加

addTag(withKey:value:) メソッドを使い、指定されたロガーから送信されるすべてのログにタグを追加します。

// これにより、"build_configuration:debug" タグが追加されます
logger.addTag(withKey: "build_configuration", value: "debug")
[logger addTagWithKey:@"build_configuration" value:@"debug"];

<TAG_VALUE>String である必要があります。

タグを削除

removeTag(withKey:) メソッドを使い、指定されたロガーから送信されるすべてのログからタグを削除します。

// これにより "build_configuration" で始まるすべてのタグが削除されます
logger.removeTag(withKey: "build_configuration")
[logger removeTagWithKey:@"build_configuration"];

詳しくは、タグ入門をご覧ください。

グローバル属性

属性を追加

デフォルトで、ロガーにより送信されるすべてのログに次の属性が追加されます。

  • http.useragent と抽出された deviceOS プロパティ
  • network.client.ip と抽出された地理的プロパティ (country, city)
  • logger.version、Datadog SDK バージョン
  • logger.thread_name, (main, background)
  • versionInfo.plist から抽出されたクライアントのアプリバージョン
  • environment、SDK の初期化に使われる環境名

addAttribute(forKey:value:) メソッドを使い、指定されたロガーから送信されるすべてのログにカスタム属性を追加します。

// これにより、文字列値を持つ "device-model" 属性が追加されます
logger.addAttribute(forKey: "device-model", value: UIDevice.current.model)
[logger addAttributeForKey:@"device-model" value:UIDevice.currentDevice.model];

<ATTRIBUTE_VALUE> には、StringDate、カスタム Codable データモデルなど、Encodable に準拠したものを指定することができます。

属性を削除

removeAttribute(forKey:) メソッドを使い、指定されたロガーから送信されるすべてのログからカスタム属性を削除します。

// これにより、"device-model" 属性は今後送信されるすべてのログから削除されます。
logger.removeAttribute(forKey: "device-model")
[logger removeAttributeForKey:@"device-model"];

その他の参考資料

お役に立つドキュメント、リンクや記事: