Stackdriver Trace API を使用すると、Google Stackdriver Trace にレイテンシ データを送信したり、反対にそれらを取得したりできます。この API では、機能を直接操作できる低レベルのインターフェースが提供されます。以下の SDK で提供される追加のラッパー機能を使用すると、お使いのアプリケーションから Stackdriver Trace にレイテンシ データを簡単に書き込むことができます。
- Java 用 Stackdriver Trace SDK
- Node.js 用 Stackdriver Trace SDK
- Go 用 Stackdriver Trace SDK
- Ruby 用 Stackdriver Trace SDK
トレースは Stackdriver Trace Zipkin Collector 経由で Zipkin トレーサーから受信することもできます。
デフォルトでは、データは Stackdriver Trace が有効になっている Google App Engine アプリケーションから収集されます。Stackdriver Trace API を使用すると、他のアプリケーションからもレイテンシ データを Stackdriver Trace に送信できるようになります。これには、ローカルまたは Google Compute Engine 上で実行しているアプリケーション、Google Cloud Platform から完全に切り離されたホスティング環境で実行しているアプリケーションも含まれます。さらに、デフォルトで App Engine から送信されるデータをカスタマイズしたり、強化したりするために Stackdriver Trace API を使用することもできます。この API を使用して Stackdriver Trace に送信されたデータは、Google API Console で表示、レポート、および分析できます。
インターフェース
Stackdriver Trace API では以下の 2 種類のインターフェースを利用できます。
- REST インターフェース。JSON 形式のレイテンシ データを HTTP で送受信できます。
- RPC インターフェース。gRPC を使用してレイテンシ データを送受信できます。現時点では、gRPC クライアント ライブラリは提供されていません。このインターフェースを使用する場合は、gRPC のドキュメントに記載されている手順でサービス定義（近日中に提供予定）から gRPC クライアント コードを生成できます。
データモデル
Stackdriver Trace API では、トレースとスパンの 2 種類のエンティティが定義されます。
トレース
トレースは、アプリケーションが 1 つの操作を完了するまでにかかる時間を表します。たとえば、アプリケーションがユーザーからリクエストを受信してから、それを処理し、レスポンスを返すまでにどれくらいの時間がかかるかを表します。各トレースは 1 つ以上のスパンによって構成されます。それぞれのスパンはサブオペレーションが完了するまでにかかる時間を表します。
トレースは、REST インターフェースでは Trace リソースによって、RPC インターフェースでは Trace メッセージによって表現されます。トレース エンティティには、関連する Cloud プロジェクトとそのサブスパンを指定するフィールドが含まれます。
スパン
スパンは、アプリケーションがトレース内のサブ操作を完了するまでにかかる時間を表します。たとえば、アプリケーションがリクエストの処理時に他のシステムへの往復 RPC コールを実行するのにかかる時間を表したり、より大きなオペレーションの一部となる別のタスクを実行するのにかかる時間を表したりすることができます。
スパンは、REST インターフェースでは TraceSpan リソースによって、RPC インターフェースでは TraceSpan メッセージによって表現されます。スパン エンティティには、自身のタイプ、開始時間、終了時間を指定するフィールドと、自身を説明するラベルが含まれます。スパンはトレース内でネストできます。ネストしたスパンには親スパンが指定されます。
操作
Stackdriver Trace API では以下の操作を実行できます。
- Stackdriver Trace にトレースを送信
- 既存のトレースを更新
- トレースのリストを取得
- 1 つのトレースの詳細情報を取得
トレースの送信
新規のトレースを Stackdriver Trace に送信するには、お使いのクライアント アプリケーション内でトレース エンティティを作成してから、それらを REST patchTraces メソッドや RPC PatchTracesRequest メソッドに渡します。
既存のトレースを更新
Stackdriver Trace 内の新規のトレースを更新するには、既存のトレース エンティティを更新してから、それらを REST patchTraces メソッドや RPC PatchTracesRequest メソッドに渡します。これは、新規のトレースを送信した場合と同じように動作します。ただし、送信したトレースの ID が既存のトレースの ID と一致すると、既存のトレースとそれに含まれるスパンのすべてのフィールドが送信したトレースの値で上書きされ、既存のトレースにないフィールドは既存のトレースデータと統合されます。
トレースのリストの取得
Stackdriver Trace からトレースのリストを取得するには、REST list メソッドや RPC ListTracesRequest メソッドにリクエストを送信します。これらのリクエストには、特定の開始時間から終了時間までの間に送信されたトレースのみを取得するフィルタ条件を渡すことができます。list メソッドと ListTracesRequest メソッドからは、トレース エンティティのセットが返されます。
トレースの詳細情報の取得
トレースのリストを取得した後、特定のトレースの詳細情報を取得するには、リクエストを REST get メソッドや RPC GetTraceRequest メソッドに送信します。このリクエストにはトレースを ID で指定します。これらのメソッドからは 1 つのトレース エンティティが返されます。
承認
Stackdriver Trace API では、ユーザー承認に OAuth 2.0 が使用されます。つまり、API を使用するには、Google API Console でプロジェクト用のウェブ アプリケーションの認証情報を設定し、クライアント アプリケーションに OAuth 2.0 承認フローを実装する必要があります。詳細については、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。また、gRPC 固有の情報については、gRPC サイトの認証ページをご覧ください。
API の確認
REST インターフェース ドキュメントでは、ページ内の [使ってみる] 機能を使用して、API の機能を確認できます。[使ってみる] は、API に渡すデータの作成方法や、API から返されるデータの構造とコンテンツの理解に役立ちます。例については list メソッドのドキュメントをご覧ください。