Node.js での OpenTelemetry の使用

OpenTelemetric を使用することにより、Node.js アプリケーションで Cloud Trace を有効にできます。OpenTelemetry は、複数のバックエンドで機能するトレースと指標データを収集するための、一連の計測ライブラリです。Node.js の OpenTelemetry に関する最新情報、他のドキュメントやサンプルについては、https://opentelemetry.io/ をご覧ください。

インストールと構成

トレースを収集するには、次のことを行う必要があります。

  • OpenTelemetric クライアント ライブラリのインストール。
  • OpenTeleometry トレース パッケージのインポート。
  • スパンを Cloud Trace にエクスポートするように OpenTelemetric を構成。
  • Cloud Trace API アクセス スコープの有効化。

クライアントのインストール、初期化、使用

OpenTelemetry では、アプリケーションの計測化を行う次の 3 つの方法が用意されています。

  • Node.js アプリケーションの自動計測
  • 手動トレース
  • ウェブ アプリケーションの自動計測

以下のセクションでは、各計測のユースケースを示します。

自動計測

@opentelemetric/nodeモジュールは、Node.js アプリケーションの自動計測を提供します。

自動計測により、アプリケーション内で次の項目が自動的に識別されます。

  • Express などのフレームワーク
  • HTTP、HTTPS、gRPC などの一般的なプロトコル
  • MySQL、MongoDB、Redis、PostgreSQL などのデータベース
  • アプリケーション内の他のライブラリ

自動計測を使用すると、すぐに使用できるトレースが提供され、使用しているどのライブラリに対してもコードを変更する必要がありません。自動計測コードにより、次のアクションが自動的に実行されます。

  • 受信リクエストからトレースコンテキスト ID を抽出し、必要に応じて分散トレースを許可する。
  • トランザクションがアプリケーションを走査する間、現在のトレースコンテキストが伝播することを保証する。詳細については、@opentelemetry/context-base をご覧ください。
  • トレースコンテキスト ID を送信リクエストに追加し、必要に応じて分散トレースをネクストホップに継続できるようにします。
  • スパンの作成とスパンの終了。

このモジュールでは、プラグインを使用してアプリケーションを自動的に計測化し、数行のコードでエンドツーエンドのトレースを提供します。

手動計測

手動トレース モジュール @opentelemetry/tracing により、計測とスパン作成を完全に管理する手段が提供されます。async_hooks は読み込みません。デフォルトでは、継続ローカル ストレージや計測のプラグインは使用されません。手動トレースでは、自動計測モジュールと比較してパフォーマンス オーバーヘッドへの影響が少なくなります。

ウェブ アプリケーションの自動計測

@opentelemetry/web モジュールは、ウェブアプリケーション用の自動計測とトレースを提供します。これにより、レイテンシや分散トレースなどのユーザー側のパフォーマンス データが収集され、フロントエンドの問題を診断してアプリケーションの全体的な状態がモニタリングされます。

Compute Engine 用と Google Kubernetes Engine 用の自動計測モジュールの使用方法を次に示します。

Compute Engine

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

npm install --save @opentelemetry/api
npm install --save @opentelemetry/node
npm install --save @opentelemetry/tracing
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

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

const opentelemetry = require('@opentelemetry/api');
const {NodeTracerProvider} = require('@opentelemetry/node');
const {SimpleSpanProcessor} = require('@opentelemetry/tracing');
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.
// Expects ADCs to be provided through the environment as ${GOOGLE_APPLICATION_CREDENTIALS}
const projectId = process.env.GOOGLE_PROJECT_ID;

// GOOGLE_APPLICATION_CREDENTIALS are expected by a dependency of this code
// and not this code itself. Checking for existence here but not retaining (as not needed)
if (!projectId || !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
  throw Error('Unable to proceed without a Project ID');
}

const provider = new NodeTracerProvider();

// Initialize the exporter
const exporter = new TraceExporter({projectId: projectId});

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

GKE

次の内容を Dockerfile に追加します。

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/node
RUN npm install --save @opentelemetry/tracing
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

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

const opentelemetry = require('@opentelemetry/api');
const {NodeTracerProvider} = require('@opentelemetry/node');
const {SimpleSpanProcessor} = require('@opentelemetry/tracing');
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.
// Expects ADCs to be provided through the environment as ${GOOGLE_APPLICATION_CREDENTIALS}
const projectId = process.env.GOOGLE_PROJECT_ID;

// GOOGLE_APPLICATION_CREDENTIALS are expected by a dependency of this code
// and not this code itself. Checking for existence here but not retaining (as not needed)
if (!projectId || !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
  throw Error('Unable to proceed without a Project ID');
}

const provider = new NodeTracerProvider();

// Initialize the exporter
const exporter = new TraceExporter({projectId: projectId});

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

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

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

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

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

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

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

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

カスタムスパンの作成

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

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


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
opentelemetry.trace.setGlobalTracerProvider(provider);
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 の使用方法を示しています。

カスタムスパンを作成する基本的な例については、OpenTeleometry の例をご覧ください。

プラットフォームの構成

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

Google Cloud での実行

アプリケーションが Google Cloud で実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、Google Cloud Platform で Cloud Trace API のアクセス スコープが有効になっている必要があります。

次の構成では、デフォルトのアクセス スコープ設定により Cloud Trace API が有効化されます。

  • App Engine フレキシブル環境
  • App Engine スタンダード環境

  • Google Kubernetes Engine(GKE)

  • Compute Engine

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。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)を使用してアプリケーションの認証情報を検索します。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"

トレースの表示

デプロイ後は、Cloud Console Trace Viewer でトレースを表示できます。

Trace Viewer のページに移動

トラブルシューティング

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