このページは、OpenTelemetry を使用して Node.js アプリケーション用の Cloud Trace データを収集するアプリケーション開発者を対象としています。OpenTelemetry は、トレースデータと指標データを収集するために使用できる、ベンダーに依存しないインストルメンテーション フレームワークです。コードのインストルメンテーションの詳細については、インストルメンテーションとオブザーバビリティをご覧ください。
- OpenTelemetry パッケージをインストールする。
- Cloud Trace にスパンをエクスポートするようにアプリケーションを構成する。
- プラットフォームを構成する。
リリース情報については、以下をご覧ください。
OpenTelemetry リファレンス コンテンツについては、以下をご覧ください。
追加のドキュメントとサンプルを含め、Node.js の OpenTelemetry に関する最新情報については、OpenTelemetry をご覧ください。
準備
-
Google Cloud コンソールのナビゲーション パネルで [API とサービス] を選択し、[API とサービスを有効化] をクリックして、Cloud Trace API を有効にします。
[API が有効です] が表示されている場合、API はすでに有効になっています。そうでない場合は、[有効にする] ボタンをクリックします。
クライアントのインストール、初期化、使用
OpenTelemetry では、アプリケーションの計測化を行う次の方法が用意されています。
Node.js アプリケーションの自動計測
このアプローチを使用する場合は、
@opentelemetry/sdk-trace-node
SDK を含めるようにアプリケーションを構成します。ただし、使用しているどのライブラリに対してもコードを変更する必要はありません。手動トレース
この方法を使用する場合、トレース情報を収集するために使用しているライブラリを変更します。
以下のセクションでは、各計測のユースケースを示します。
自動計測
@opentelemetry/sdk-trace-node モジュールは、Node.js アプリケーションの自動計測を提供します。
自動計測により、アプリケーション内で次の項目が自動的に識別されます。
- Express などのフレームワーク
- 一般的なプロトコル(HTTP、HTTPS、gRPC など)
- MySQL、MongoDB、Redis、PostgreSQL などのデータベース
- アプリケーション内の他のライブラリ
自動計測を使用すると、すぐに使用できるトレースが提供され、使用しているどのライブラリに対してもコードを変更する必要がありません。自動計測コードにより、次のアクションが自動的に実行されます。
- 受信リクエストからトレースコンテキスト ID を抽出し、必要に応じて分散トレースを許可する。
- トランザクションがアプリケーションを走査する間、現在のトレースコンテキストが伝播することを保証する。
- トレースコンテキスト ID を送信リクエストに追加し、必要に応じて分散トレースをネクストホップに継続できるようにします。
- スパンの作成とスパンの終了。
このモジュールでは、プラグインを使用してアプリケーションを自動的に計測化し、数行のコードでエンドツーエンドのトレースを提供します。
手動計測
手動トレース モジュール @opentelemetry/sdk-trace-base により、計測とスパン作成を完全に管理する手段が提供されます。async_hooks
は読み込みません。デフォルトでは、継続ローカル ストレージや計測のプラグインは使用されません。手動トレースでは、自動計測モジュールと比較してパフォーマンス オーバーヘッドへの影響が少なくなります。
例
Compute Engine 用と Google Kubernetes Engine 用の自動計測モジュールの使用方法を次に示します。
Compute Engine
以下のパッケージをインストールします。
npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter
次のコードをアプリに追加して、エクスポータの初期化と登録を行います。
GKE
次の内容を Dockerfile
に追加します。
RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter
次のコードをアプリに追加して、エクスポータの初期化と登録を行います。
Express フレームワークを使用したサンプル アプリケーション
OpenTelemetry Express Instrumentation を使用すると、トレースデータを自動的に収集して、指定のバックエンドにエクスポートできるようになり、分散システムにオブザーバビリティが追加されます。
Express フレームワークを使用するアプリケーションで OpenTelemetric を使用するには、次の手順を実行します。
以下のパッケージをインストールします。
npm install --save @opentelemetry/instrumentation-http npm install --save @opentelemetry/instrumentation-express
次のコードをアプリに追加します。これにより、サポートされているプラグインがすべて読み込まれます。
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node'); const provider = new NodeTracerProvider();
基本的な例については、OpenTelemetry Express の例をご覧ください。
カスタムスパンの作成
カスタムスパンを作成することで、システムが作成したトレースに別の情報を追加できます。
カスタムスパンを作成するには、ソースコードに次の内容を追加します。
getTracer
は、トレーサーのインスタンスを返します。ここで、basic
は、トレーサーまたは計測ライブラリの名前です。これにより、OpenTelemetric にスパンの作成元が通知されます。foo
は、カスタムスパンの名前です。invoking work
は、サンプル イベントの名前です。これは、addEvent
API の使用方法を示しています。
カスタムスパンの作成の基本的な例については、OpenTelemetry の例をご覧ください。
プラットフォームの構成
Cloud Trace は Google Cloud と他のプラットフォームで使用できます。
Google Cloud での実行
アプリケーションが Google Cloud で実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、Google Cloud Platform で Cloud Trace API のアクセス スコープが有効になっている必要があります。
サポートされている Google Cloud 環境の一覧については、環境サポートをご覧ください。
次の構成では、デフォルトのアクセス スコープ設定により Cloud Trace API が有効化されます。
- App Engine フレキシブル環境
App Engine スタンダード環境
Google Kubernetes Engine(GKE)
Compute Engine
Cloud Run
カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。
Google Cloud Console を使用して環境のアクセス スコープを構成する方法については、Google Cloud プロジェクトの構成をご覧ください。
gcloud
ユーザーの場合は、--scopes
フラグを使用してアクセス スコープを指定し、trace.append
Cloud Trace API アクセス スコープを含めます。たとえば、Cloud Trace API のみを有効にして GKE クラスタを作成するには、次のようにします。gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
ローカルやその他の場所での実行
アプリケーションが Google Cloud の外部で実行されている場合は、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要があります。サービス アカウントには Cloud Trace エージェント ロールが含まれている必要があります。手順については、サービス アカウントの作成をご覧ください。
Google Cloud クライアント ライブラリは、アプリケーションのデフォルト認証情報(ADC)を使用してアプリケーションの認証情報を検索します。
これらの認証情報を指定するには、次の 3 つの方法があります。
実行
gcloud auth application-default login
オペレーティング システムのデフォルトパスにサービス アカウントを配置します。以下に、Windows と Linux のデフォルトのパスを一覧表示します。
Windows:
%APPDATA%/gcloud/application_default_credentials.json
Linux:
$HOME/.config/gcloud/application_default_credentials.json
GOOGLE_APPLICATION_CREDENTIALS
環境変数をサービス アカウントのパスに設定します。
Linux / macOS
export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
Windows
set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"
トレースを表示
Google Cloud コンソールのナビゲーション パネルで [Trace] を選択し、次に [ Trace エクスプローラ] を選択します。
トラブルシューティング
Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。