Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

• You are not using Datadog supported library instrumentation.
• You want to extend the ddtrace library’s functionality.
• You need finer control over instrumenting your applications.

The ddtrace library provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with Datadog.

要件と制限

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

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

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

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

DatadogCore
DatadogTrace

pod 'DatadogCore'
pod 'DatadogTrace'

github "DataDog/dd-sdk-ios"

OpenTelemetryApi.xcframework
DatadogInternal.xcframework
DatadogCore.xcframework
DatadogTrace.xcframework

2. アプリケーション コンテキストと 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

3. 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)

4. OpenTelemetry API でコードをインスツルメントします:

let span = tracer.spanBuilder(spanName: "<span_name>").startSpan()
// 測定したいことをします ...
// ... そして、操作が終了したら:
span.end()

5. (任意) スパン間の子親関係を設定します:

let responseDecodingSpan = tracer.spanBuilder(spanName: "response decoding")
    .setParent(networkRequestSpan) // `networkRequestSpan` の子にします
    .startSpan()

// ... HTTP レスポンスデータのデコード ...
responseDecodingSpan.end()

6. (任意) スパンに追加属性を付与します:

span.setAttribute(key: "http.url", value: url)

7. (任意) スパンにエラーを添付します:

span.status = .error(description: "Failed to decode response")

8. (任意) スパンに 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()