概要

このページでは、Cloud Trace 用にアプリケーションをインストルメント化する方法の概要を簡単に説明します。Cloud Trace の設定の詳細な手順については、言語固有の設定ページをご覧ください。

Cloud Trace では、アプリケーションの分散トレースデータを提供します。アプリケーションをインストルメント化すると、Cloud Trace コンソールで、1 つのリクエストのレイテンシ データを分析して、アプリケーション全体の集約したレイテンシを確認できます。

Cloud Trace では、OpenTelemetry の使用をおすすめします。 OpenTelemetry は、OpenCensus と OpenTracing を統合したオープンソース プロダクトです。

アプリケーションをインストゥルメント化するタイミング

アプリケーションで Cloud Trace にトレースを送信するには、インストゥルメント化する必要があります。Google クライアント ライブラリを使用してコードをインストゥルメント化できます。ただし、アプリケーションのインストゥルメント化には OpenTelemetry または OpenCensus を使用することをおすすめします。これらはオープンソースのトレース パッケージです。OpenTelemetry は現在開発中であり、推奨されるパッケージです。

アプリケーションのトレースのインストルメント化

アプリケーションのトレースを実装するには、次の 3 つの方法があります。

  • OpenTelemetry と関連する Cloud Trace クライアント ライブラリを使用します。アプリケーションをインストゥルメント化するには、この方法をおすすめします。

  • お使いの言語で OpenTelemetry クライアント ライブラリを使用できない場合は、OpenCensus を使用します。

  • Cloud Trace APIを使用して、Cloud Trace にトレースデータを送信するカスタム メソッドを作成します。

次の表は、各プログラミング言語におすすめのクライアント ライブラリの一覧です。

言語 推奨されるクライアント ライブラリ
Python OpenCensus
Java OpenCensus
Node.js Cloud Trace API
Go OpenCensus
C# .NET Cloud Trace API
PHP OpenCensus
Ruby Cloud Trace API

スパンを作成するタイミング

Cloud Trace クライアント ライブラリには通常、現在のスパンに関する情報(トレース ID やトレースがサンプリングされるかどうかなど)を保持するグローバル トレース コンテキストが保持されています。これらのライブラリでは通常、RPC の境界にスパンが作成されます。ただし、デフォルトの作成アルゴリズムではニーズを満たせない場合は、ユーザーがスパンを作成する必要があります。

現在アクティブなスパンには、Tracer オブジェクトでラップされることもあるグローバル トレース コンテキストからアクセスできます。アプリケーションに関連する情報をカスタム アノテーションとタグを使用して、既存のスパンに追加できます。また、独自のアノテーションとタグで新しい子スパンを作成して、アプリケーションの動作を詳細にトレースすることもできます。コンテキストはグローバルであるため、コンテキストを更新するマルチスレッドのアプリケーションは適切な隔離を使用する必要があります。

認証情報を提供するタイミング

アプリケーションに認証情報を提供する必要はありません。また、Google Cloud で実行するときにアプリケーションで Google Cloud プロジェクト ID を指定する必要はありません。一部の言語では、Google Cloud で実行されている場合でさえも、Google Cloud プロジェクト ID を指定する必要があります。

Google Cloud の外部で実行している場合は、アプリケーションに認証情報を指定する必要があります。アプリケーションで Google Cloud プロジェクト ID を指定する必要もあります。

詳しくは、言語別の設定ページをご覧ください。

リクエストを強制的にトレースする方法

Cloud Trace はすべてのリクエストをサンプリングしません。たとえば、Java と OpenCensus を使用する場合、10,000 個あたり 1 個のリクエストのみがトレースされます。App Engine を使用している場合、リクエストは App Engine インスタンスごとに毎秒 0.1 リクエストの割合でサンプリングされます。Cloud Trace API を使用する場合は、顧客のレートを構成できます。Java OpenCensus パッケージなどの一部のパッケージは、サンプリング レートの構成をサポートしています。

特定のリクエストを強制的にトレースするには、リクエストに X-Cloud-Trace-Context ヘッダーを追加します。ヘッダーの仕様は次のとおりです。

"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"

ここで

  • TRACE_ID は、128 ビットの番号を表す 32 文字の 16 進数値です。 リクエストを束ねるつもりがないのであれば、リクエスト間で一意の値にする必要があります。これには UUID を使用できます。

  • SPAN_ID は、(符号なしの)スパン ID の 10 進表現です。ランダムに生成され、トレース内で一意でなければなりません。後続のリクエストでは、SPAN_ID を親リクエストのスパン ID に設定します。ネストされたトレースの詳細については、TraceSpanRESTRPC)の説明をご覧ください。

  • このリクエストをトレースするには、TRACE_TRUE1 に設定する必要があります。リクエストをトレースしない場合は 0 を指定します。

たとえば、curl でトレースを強制するには、次のようにします。

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b12000100000/1;o=1"

Cloud Trace の実行ツールを作成する方法

OpenCensus は、gRPC サービス用の時系列データを書き込むと、Cloud Trace の実行ツールを作成します。これらの実行ツールを表示するには、グラフを作成し、グラフのツールバーを使用して表示を有効にします。詳細については、グラフのツールバーの使用をご覧ください。

独自のカスタム指標を記述する場合は、次のリソースをご覧ください。

カスタム指標を記述すると、実行ツールを作成できます。次の Go コード スニペットは、時系列に単一の Point を作成することを示しています。最初の要素は Interval でラベル付けされた時間間隔であり、2 番目の要素は値です。値は TypedValue オブジェクトのインスタンスであり、distributionValue に解決される必要があります。

import (
	"time"

	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
)

func createDataPointWithExemplar() *monitoringpb.Point {
	end := time.Now().Unix()
	dataPoint := &monitoringpb.Point{
		Interval: &monitoringpb.TimeInterval{
			StartTime: &googlepb.Timestamp{Seconds: end - 60},
			EndTime:   &googlepb.Timestamp{Seconds: end},
		},
		Value: &monitoringpb.TypedValue{Value: &monitoringpb.TypedValue_DistributionValue{
			DistributionValue: &distributionpb.Distribution{
				Count: 14,
				BucketOptions: &distributionpb.Distribution_BucketOptions{Options: &distributionpb.Distribution_BucketOptions_LinearBuckets{
					LinearBuckets: &distributionpb.Distribution_BucketOptions_Linear{NumFiniteBuckets: 2, Width: 3, Offset: 0},
				}},
				BucketCounts: []int64{5, 6, 3},
				Exemplars: []*distributionpb.Distribution_Exemplar{
					&distributionpb.Distribution_Exemplar{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
					&distributionpb.Distribution_Exemplar{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint
}

Google Cloud プロジェクトの構成

Cloud Trace を使用するには、Google Cloud プロジェクトで Cloud Trace API を有効にする必要があります。この設定により、Google Cloud プロジェクトが認証されたソースからトレースデータを受信できるようになります。

Google Cloud プロジェクトでは、デフォルトで Cloud Trace API が有効になっているため、何もする必要はありません。Google Cloud プロジェクトのアクセス スコープを変更し、設定を確認する場合は、次の操作を行います。

  1. Google Cloud Console から [API とサービス] に移動します。

    [API とサービス] に移動

  2. [API とサービスを有効化] をクリックします。

  3. 検索バーで、「Trace API」と入力します。

  4. [API が有効です] と表示されている場合、この API はすでに有効になっており、何もする必要はありません。それ以外の場合は、[有効にする] をクリックします。

次のステップ

GitHub やその他のオープンソース リポジトリへの詳細な構成情報、サンプル、リンクについては、ご使用の言語の設定ページをご覧ください。