計装ライブラリ

アプリを開発する際、作業を加速するためにサードパーティのライブラリやフレームワークを使用することがあるでしょう。 OpenTelemetryを使用してアプリを計装する場合、使用するサードパーティのライブラリやフレームワークにトレース、ログ、メトリクスを手動で追加するために時間を費やすことを避けたいことがあります。

多くのライブラリやフレームワークはすでにOpenTelemetryをサポートしているか、OpenTelemetryの計装を介してサポートされているため、テレメトリーを生成してオブザーバビリティバックエンドにエクスポートできます。

サードパーティのライブラリやフレームワークを使用しているアプリやサービスを計装する場合は、このページの手順に従って、ネイティブに計装されたライブラリと依存関係の計装ライブラリの使用方法を学んでください。

ネイティブに計装されたライブラリを使用する

デフォルトでOpenTelemetryサポートが付属しているライブラリの場合、アプリにOpenTelemetry SDKを追加して設定することで、そのライブラリから発行されるトレース、メトリクス、ログを取得できます。

ライブラリによっては、計装のために追加の構成が必要な場合があります。 詳細はライブラリごとのドキュメントをご覧ください。

計装ライブラリの使用

OpenTelemetry-Swift は、インストールして初期化すると計装を自動的に生成する計装ライブラリをいくつか提供しています。

たとえば、NSURLSession の計装は、NSURLSession で行われるすべてのネットワークリクエストに対して自動的にスパンを作成します。

セットアップ

すべての計装ライブラリは OpenTelemetry Swift で利用可能です。 計装を有効にするには、各計装の手順に従ってください。

SDKResourceExtension

SDKResourceExtension はデバイスの詳細をリソースとして提供します。

使い方

DefaultResource.get() を使用して、オールインワンのリソースオブジェクトを生成します。 このリソースは TracerProvider または MetricProvider に追加できます。

OpenTelemetry.registerTracerProvider(tracerProvider: TracerProviderBuilder()
            .with(resource: DefaultResource.get())
            .build())

詳細

SDKResourceExtension は、iOS デバイス、OS の詳細、アプリケーションの詳細を含むリソースオブジェクトの属性を提供します。 これらの値は適切なセマンティック属性に適用されます。

アプリケーション情報

デバイス情報

オペレーティングシステム情報

NSURLSession の計装

この計装は、NSURLSession で行われるすべてのネットワークリクエストに対してスパンを作成します。 また、計装されたネットワークリクエストに分散トレーシングヘッダーを注入します。 NetworkStatus はこのパッケージの依存関係であり、ネットワークスパンにネットワーク状態の属性を提供します。

注意: NSURLSession の計装は、OpenTelemetry オブジェクトのグローバルトレーサープロバイダーに依存しています。 カスタムトレーサープロバイダーは、この計装の前に設定し、グローバルプロバイダーとして設定する必要があります。

使い方

URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration()) でクラスを初期化すると、すべてのネットワーク呼び出しが自動的にキャプチャされます。

この動作は、URLSessionInstrumentationConfiguration で定義されているオプションのコールバックを使用して変更または拡張できます。

• shouldInstrument: ((URLRequest) -> (Bool)?)?

  計装するリクエストをフィルタリングします。 デフォルトではすべてのリクエストが対象です。

• shouldRecordPayload: ((URLSession) -> (Bool)?)?

  セッションにペイロードデータを記録させたい場合に実装します。 デフォルトは false です。

• shouldInjectTracingHeaders: ((URLRequest) -> (Bool)?)?

  トレースを追跡するためにヘッダーを注入するリクエストをフィルタリングできます。 デフォルトは true です。 カスタムヘッダーを注入したい場合も true を返す必要があります。

• injectCustomHeaders: ((inout URLRequest, Span?) -> Void)?

  カスタムヘッダーを注入したり、リクエストを他の方法で変更するためにこのコールバックを実装します。

• nameSpan: ((URLRequest) -> (String)?)?

  標準の OpenTelemetry 名のかわりに、指定されたリクエストの名前を変更します。

• createdRequest: ((URLRequest, Span) -> Void)?

  リクエストが作成された後に呼び出され、スパンに追加情報を付与できます。

• receivedResponse: ((URLResponse, DataOrFile?, Span) -> Void)?

  レスポンスが受信された後に呼び出され、スパンに追加情報を付与できます。

• receivedError: ((Error, DataOrFile?, HTTPStatus, Span) -> Void)?

  エラーが受信された後に呼び出され、スパンに追加情報を付与できます。

以下は初期化の例です。 URLSessionInstrumentationConfiguration のコンストラクタには、アプリケーションのニーズに合わせて上で定義したパラメーターを渡すことができます。

let sessionInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())

詳細

NSURLSession の計装は、ネットワークリクエスト時のデバイスのネットワーク状態に関する詳細を提供する追加の属性も提供します。

SignpostIntegration

このパッケージは、スパンが開始または終了されたときに os_signpost の begin および end 呼び出しを作成します。 OpenTelemetry で計装されたアプリケーションが Instruments のようなプロファイリングアプリでスパンを表示できるよう、自動的に統合します。 また、ユーザーが追加のシグナルポストイベントを追加できるように、投稿に使用する OSLog もエクスポートします。 この機能は Simple Exporter の例で示されています。

バージョンに関する注意

• iOS 15以上、macOS 12以上、tvOS 15以上、watchOS 8以上: 効率性と互換性が向上したモダンな OSSignposter API を利用する OSSignposterIntegration を使用してください。
• 古いシステム: 従来の os_signpost API に依存する SignPostIntegration を使用してください。

使い方

デプロイメントターゲットに基づいて適切なスパンプロセッサーを追加してください（プロバイダーの設定の詳細については手動計装のドキュメントを参照してください）。

iOS 15以上、macOS 12以上、tvOS 15以上、watchOS 8以上の場合:

OpenTelemetry.instance.tracerProvider.addSpanProcessor(OSSignposterIntegration())

古いシステムの場合

OpenTelemetry.instance.tracerProvider.addSpanProcessor(SignPostIntegration())

実行時に自動的に選択する場合:

if #available(iOS 15, macOS 12, tvOS 15, watchOS 8, *) {
    OpenTelemetry.instance.tracerProvider.addSpanProcessor(OSSignposterIntegration())
} else {
    OpenTelemetry.instance.tracerProvider.addSpanProcessor(SignPostIntegration())
}

利用可能な計装ライブラリ

OpenTelemetry が提供する計装ライブラリの完全なリストは、opentelemetry-swift リポジトリから入手できます。

レジストリでもさらに多くの計装を見つけることができます。

次のステップ

計装ライブラリをセットアップした後は、カスタムテレメトリーデータを収集するために、コードに独自の計装を追加することを検討してください。