Node.js と OpenTelemetry

このページは、OpenTelemetry を使用して Node.js アプリケーション用の Cloud Trace データを収集するアプリケーション開発者を対象としています。OpenTelemetry は、トレースデータと指標データを収集するために使用できる、ベンダーに依存しないインストルメンテーション フレームワークです。コードのインストルメンテーションの詳細については、インストルメンテーションとオブザーバビリティをご覧ください。

  • OpenTelemetry パッケージをインストールする。
  • Cloud Trace にスパンをエクスポートするようにアプリケーションを構成する。
  • プラットフォームを構成する。

リリース情報については、以下をご覧ください。

OpenTelemetry リファレンス コンテンツについては、以下をご覧ください。

追加のドキュメントとサンプルを含め、Node.js の OpenTelemetry に関する最新情報については、OpenTelemetry をご覧ください。

準備

  1. Google Cloud コンソールのナビゲーション パネルで [API とサービス] を選択し、[API とサービスを有効化] をクリックして、Cloud Trace API を有効にします。

    [Cloud Trace API の設定] に移動

  2. [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

次のコードをアプリに追加して、エクスポータの初期化と登録を行います。

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(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

次のコードをアプリに追加して、エクスポータの初期化と登録を行います。

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Express フレームワークを使用したサンプル アプリケーション

OpenTelemetry Express Instrumentation を使用すると、トレースデータを自動的に収集して、指定のバックエンドにエクスポートできるようになり、分散システムにオブザーバビリティが追加されます。

Express フレームワークを使用するアプリケーションで OpenTelemetric を使用するには、次の手順を実行します。

  1. 以下のパッケージをインストールします。

    npm install --save @opentelemetry/instrumentation-http
    npm install --save @opentelemetry/instrumentation-express
    
  2. 次のコードをアプリに追加します。これにより、サポートされているプラグインがすべて読み込まれます。

    const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
    const provider = new NodeTracerProvider();
    

基本的な例については、OpenTelemetry Express の例をご覧ください。

カスタムスパンの作成

カスタムスパンを作成することで、システムが作成したトレースに別の情報を追加できます。

カスタムスパンを作成するには、ソースコードに次の内容を追加します。


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
provider.register();
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();
  • 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 が有効化されます。

カスタム アクセス スコープを使用する場合は、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 エクスプローラ] を選択します。

[Trace エクスプローラ] に移動

トラブルシューティング

Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。