OpenTelemetry API を使用した iOS と tvOS のカスタム インスツルメンテーション

Datadog で OpenTelemetry を使用するタイミングがわからない場合は、OpenTelemetry API を使用したカスタムインスツルメンテーションから始めて、詳細を学びましょう。

概要

OpenTelemetry API を使用してアプリケーションを手動でインスツルメントする理由はいくつかあります。

ddtrace ライブラリは、これらの目標を達成するためのさまざまなテクニックを提供しています。次のセクションでは、Datadog で使用するために OpenTelemetry API を使用してカスタムインスツルメンテーションを行う方法を説明します。

要件と制限

  • iOS / tvOS 向け DatadogTrace バージョン 2.12.0 以上が必要です。

OpenTelemetry による iOS アプリのトレーシング

  1. ご利用のパッケージ マネージャーに応じてライブラリを依存関係として宣言してください。推奨は Swift Package Manager (SPM) です。

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

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

    プロジェクトで、以下のライブラリをリンクします。

    DatadogCore
DatadogTrace

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

    pod 'DatadogCore'
pod 'DatadogTrace'

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

    github "DataDog/dd-sdk-ios"

    Xcode で、以下のフレームワークをリンクします。

    OpenTelemetryApi.xcframework
DatadogInternal.xcframework
DatadogCore.xcframework
DatadogTrace.xcframework
    1. アプリケーション コンテキストと Datadog クライアント トークンを使用してライブラリを初期化します。セキュリティ上の理由から、必ずクライアント トークンを使用してください。dd-sdk-ios ライブラリを Datadog API キーで設定すると、iOS アプリ IPA のバイト コードにクライアント サイドで露出してしまいます。

    クライアント トークンの設定方法については、クライアント トークンのドキュメントを参照してください。

      import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)


        import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .eu1,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)


          import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .us3,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)


            import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .us5,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)


              import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .us1_fed,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)


                import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .ap1,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)

                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
                  1. Datadog トレーサーは Open Telemetry 標準を実装しています。Datadog トレーサーを有効化し、トレーサー プロバイダを登録して、トレーサー インスタンスを取得します:
                    import DatadogTrace
import OpenTelemetryApi

Trace.enable(
    with: Trace.Configuration(
        networkInfoEnabled: true
    )
)

OpenTelemetry.registerTracerProvider(
    tracerProvider: OTelTracerProvider()
)

let tracer = OpenTelemetry
    .instance
    .tracerProvider
    .get(instrumentationName: "", instrumentationVersion: nil)
                    1. OpenTelemetry API でコードをインスツルメントします:
                      let span = tracer.spanBuilder(spanName: "<span_name>").startSpan()
// 測定したいことをします ...
// ... そして、操作が終了したら:
span.end()
                      1. (任意) スパン間の子親関係を設定します:
                        let responseDecodingSpan = tracer.spanBuilder(spanName: "response decoding")
    .setParent(networkRequestSpan) // `networkRequestSpan` の子にします
    .startSpan()

// ... HTTP レスポンスデータのデコード ...
responseDecodingSpan.end()
                        1. (任意) スパンに追加属性を付与します:
                          span.setAttribute(key: "http.url", value: url)
                          1. (任意) スパンにエラーを添付します:
                            span.status = .error(description: "Failed to decode response")
                            1. (任意) スパンに Span リンクを追加します:
                              let linkedSpan = tracer.spanBuilder(spanName: "linked span").startSpan()
linkedSpan.end()

let spanWithLinks = tracer.spanBuilder(spanName: "span with links")
    .addLink(spanContext: linkedSpan.context)
    .startSpan()
spanWithLinks.end()
                              PREVIEWING: sdk/versions