Node.js インストルメンテーションのサンプル

このドキュメントでは、オープンソースの OpenTelemetry フレームワークを使用してトレースと指標データを収集するように Node.js JavaScript アプリを変更する方法と、構造化 JSON ログを標準出力に出力する方法について説明します。このドキュメントでは、インストールして実行できる Node.js サンプルアプリについても説明します。このアプリは Fastify ウェブフレームワークを使用し、指標、トレース、ログを生成するように構成されています。

計測について詳しくは、次のドキュメントをご覧ください。

手動インストルメンテーションとゼロコードインストルメンテーションについて

この言語について、OpenTelemetry はゼロコードインストルメンテーションを、コードを変更せずにライブラリとフレームワークからテレメトリーを収集する手法と定義しています。ただし、モジュールをインストールし、環境変数を設定する必要があります。

このドキュメントでは、ゼロコードインストルメンテーションについては説明しません。このトピックについては、JavaScript zero-code instrumentation をご覧ください。

一般的な情報については、Node の OpenTelemetry インストルメンテーションをご覧ください。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まずフェデレーション ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まずフェデレーション ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Cloud Shell、 Google Cloudリソース、ローカル開発環境でサンプルを実行する場合は、このセクションに記載されている権限で十分です。本番環境アプリケーションの場合、通常、サービスアカウントはログ、指標、トレースデータを書き込む認証情報を提供します。

サンプルアプリケーションがログ、指標、トレースデータを書き込むために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- ログ書き込み（roles/logging.logWriter）
- モニタリング指標の書き込み（roles/monitoring.metricWriter）
- Cloud トレースエージェント（roles/cloudtrace.agent）
ログ、指標、トレースデータを表示するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
- ログ閲覧者（roles/logging.viewer）
- モニタリング閲覧者（roles/monitoring.viewer）
- Cloud トレースユーザー（roles/cloudtrace.user）
ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

アプリを計測してトレース、指標、ログを収集する

アプリを計測して、トレースと指標データを収集し、構造化 JSON を標準出力に出力するには、このドキュメントの以降のセクションで説明する手順を実施します。
OpenTelemetry を構成する

OpenTelemetry Node.js SDK のデフォルト構成では、OTLP プロトコルを使用してトレースをエクスポートします。また、トレースコンテキストの伝播に W3C トレースコンテキスト形式を使用するように OpenTelemetry を構成します。この構成により、トレース内でスパンが正しい親子関係を持つことが保証されます。

次のコードサンプルでは、OpenTelemetry を設定するための JavaScript モジュールを示します。

サンプル全体を表示するには、（その他）をクリックして、[GitHub で表示] を選択します。
```
diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.diagLogLevelFromString(
    opentelemetry.core.getStringFromEnv('OTEL_LOG_LEVEL')
  )
);

const sdk = new opentelemetry.NodeSDK({
  instrumentations: getNodeAutoInstrumentations({
    // Disable noisy instrumentations
    '@opentelemetry/instrumentation-fs': {enabled: false},
  }),
  resourceDetectors: getResourceDetectorsFromEnv(),
  metricReader: getMetricReader(),
});

try {
  sdk.start();
  diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
  diag.error(
    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
    error
  );
}

// Gracefully shut down the SDK to flush telemetry when the program exits
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => diag.debug('OpenTelemetry SDK terminated'))
    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});
```
上記のコードサンプルでは、OTLP プロトコルを使用して指標をエクスポートするように OpenTelemetry を構成し、@opentelemetry/auto-instrumentations-node パッケージを使用して、使用可能なすべての Node.js のインストルメンテーションを構成しています。

アプリがシャットダウンする前に、保留中のすべてのテレメトリーがフラッシュされ、接続が正常に終了するように、SIGTERM ハンドラは shutdown を呼び出します。

詳細と構成オプションについては、Zero-Code Instrumentation Configuration をご覧ください。

OpenTelemetry 構成をプリロードするようにアプリを構成する

構造化ログを書き込み、OpenTelemetry を使用して指標とトレースデータを収集するようにアプリを構成するには、Node.js --require フラグを使用して計測モジュールをプリロードするようにアプリの呼び出しを更新します。--require フラグを使用すると、アプリの起動前に OpenTelemetry が初期化されます。詳細については、OpenTelemetry Node.js スタートガイドをご覧ください。

次のコードサンプルは、--require フラグを渡す Dockerfile を示しています。
```
CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log
```
構造化ロギングを構成する

標準出力に書き込まれる JSON 形式のログにトレース情報を含めるには、構造化ログを JSON 形式で出力するようにアプリを構成します。Fastify は Pino ログフレームワークを使用し、各リクエストハンドラにロガーを提供します。次のコードサンプルは、JSON 構造化ログを出力するようにアプリを構成する Pino LoggerOptions オブジェクトを示しています。
```
// Expected attributes that OpenTelemetry adds to correlate logs with spans
interface LogRecord {
  trace_id?: string;
  span_id?: string;
  trace_flags?: string;
  [key: string]: unknown;
}

// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
const PinoLevelToSeverityLookup: Record<string, string | undefined> = {
  trace: 'DEBUG',
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARNING',
  error: 'ERROR',
  fatal: 'CRITICAL',
};

export const loggerConfig = {
  messageKey: 'message',
  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
  timestamp(): string {
    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
  },
  formatters: {
    log(object: LogRecord): Record<string, unknown> {
      // Add trace context attributes following Cloud Logging structured log format described
      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
      const {trace_id, span_id, trace_flags, ...rest} = object;

      return {
        'logging.googleapis.com/trace': trace_id,
        'logging.googleapis.com/spanId': span_id,
        'logging.googleapis.com/trace_sampled': trace_flags
          ? trace_flags === '01'
          : undefined,
        ...rest,
      };
    },
    // See
    // https://getpino.io/#/docs/help?id=mapping-pino-log-levels-to-google-cloud-logging-stackdriver-severity-levels
    level(label: string) {
      return {
        severity:
          PinoLevelToSeverityLookup[label] ?? PinoLevelToSeverityLookup['info'],
      };
    },
  },
} satisfies LoggerOptions;
```
前の構成では、アクティブなスパンに関する情報がログメッセージから抽出され、抽出された情報が JSON 構造化ログに属性として追加されます。これらの属性を使用して、ログをトレースに関連付けることができます。
- logging.googleapis.com/trace: ログエントリに関連付けられているトレースのリソース名。
- logging.googleapis.com/spanId: ログエントリに関連付けられているトレースのスパン ID。
- logging.googleapis.com/trace_sampled: このフィールドの値は true または false にする必要があります。
これらのフィールドの詳細については、LogEntry 構造体をご覧ください。

Fastify で Pino 構成を使用するには、Fastify アプリの作成時にロガー構成オブジェクトを渡します。
```
// Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});
```
構造化ログを書き込む

トレースにリンクする構造化ログを書き込むには、Fastify が提供する Pino ロガーを使用します。たとえば、次のステートメントは Logger.info() メソッドを呼び出す方法を示しています。
```
request.log.info({subRequests}, 'handle /multi request');
```
OpenTelemetry は、OpenTelemetry Context で現在アクティブなスパンのスパンコンテキストを Pino ログエントリに自動的に入力します。このスパンコンテキストは、構造化ロギングを構成するで説明されているように、JSON ログに含まれます。

テレメトリーを収集するように構成されたサンプルアプリを実行する

サンプルアプリでは、ログに JSON、指標とトレースに OTLP を使用し、さらに Fastify フレームワークを使用するなど、ベンダーに依存しない形式を使用しています。テレメトリーを Google Cloudにルーティングするため、このサンプルでは Google エクスポータで構成された OpenTelemetry Collector を使用します。このアプリには 2 つのエンドポイントがあります。
- /multi エンドポイントは、handleMulti 関数によって処理されます。アプリの負荷生成ツールが /multi エンドポイントにリクエストを発行します。このエンドポイントは、リクエストを受信すると、ローカルサーバーの /single エンドポイントに 3～7 件のリクエストを送信します。
```
/**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the handler body.
 */
fastify.get('/multi', async request => {
  const subRequests = randInt(3, 8);
  request.log.info({subRequests}, 'handle /multi request');

  for (let i = 0; i < subRequests; i++) {
    await axios.get(`http://localhost:${port}/single`);
  }
  return 'ok';
});
```
- /single エンドポイントは、handleSingle 関数によって処理されます。このエンドポイントは、リクエストを受信すると、少しの間スリープしてから、文字列で応答します。
```
/**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 */
fastify.get('/single', async request => {
  // Sleep between 100-200 milliseconds
  const sleepMillis = randInt(100, 200);
  request.log.info({sleepMillis}, 'Going to sleep');
  await sleep(sleepMillis);
  return `slept ${sleepMillis}\n`;
});
```
アプリをダウンロードしてデプロイする

注: Cloud Shell を使用してサンプルアプリを実行することをおすすめします。ただし、Linux または Mac でサンプルアプリをローカルで実行する場合は、次のステップの最初の手順は省略してください。
サンプルを実行するには、次の操作を行います。
1. In the Google Cloud console, activate Cloud Shell.
  
  Activate Cloud Shell
  
  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
2. リポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js
```
3. サンプルディレクトリに移動します。
```
cd opentelemetry-operations-js/samples/instrumentation-quickstart
```
4. サンプルをビルドして実行します。
```
docker compose up --abort-on-container-exit
```
  Cloud Shell で実行していない場合は、認証情報ファイルを指す GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用してアプリケーションを実行します。アプリケーションのデフォルト認証情報は、$HOME/.config/gcloud/application_default_credentials.json にある認証情報ファイルを提供します。
```
# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
```

Node.js インストルメンテーションのサンプル

手動インストルメンテーションとゼロコードインストルメンテーションについて

始める前に

アプリを計測してトレース、指標、ログを収集する

OpenTelemetry を構成する

OpenTelemetry 構成をプリロードするようにアプリを構成する

構造化ロギングを構成する

構造化ログを書き込む

テレメトリーを収集するように構成されたサンプルアプリを実行する

アプリをダウンロードしてデプロイする

指標を表示する

トレースを表示する

ログを表示する

次のステップ

Node.js インストルメンテーションのサンプル コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

手動インストルメンテーションとゼロコード インストルメンテーションについて

始める前に

アプリを計測してトレース、指標、ログを収集する

OpenTelemetry を構成する

OpenTelemetry 構成をプリロードするようにアプリを構成する

構造化ロギングを構成する

構造化ログを書き込む

テレメトリーを収集するように構成されたサンプルアプリを実行する

アプリをダウンロードしてデプロイする

指標を表示する

トレースを表示する

ログを表示する

次のステップ

Node.js インストルメンテーションのサンプル

手動インストルメンテーションとゼロコードインストルメンテーションについて