Node.js クライアント ライブラリでテレメトリー シグナルを有効にする

Cloud de Confiance by S3NS は、Node.js アプリケーションに対して強力なモニタリング、ロギング、診断機能を提供します。

Node.js クライアント ライブラリは、トレースデータを出力するように計測されています。計測はオプトインです。明示的に有効にする必要があります。このドキュメントでは、使用可能なシグナルと、それらを有効にする方法について説明します。

利用可能なシグナル

Node.js クライアント ライブラリは、次のシグナルを生成するように計測されます。

  1. INFO スパンは、論理クライアント リクエストごとに作成されます。通常、クライアント構造体の単一のメソッド呼び出しがこのようなスパンを取得します（たとえば、SecretManagerServiceClient で accessSecretVersion を呼び出す）。
  2. 低レベルの RPC 試行ごとに INFO スパン。通常、クライアント構造体の単一のメソッドは、このようなスパンを 1 つ取得しますが、ライブラリが RPC を再試行する必要がある場合は、さらに多くのスパンを取得することがあります。

これらのスパンとログは、追加のCloud de Confiance by S3NS 属性を使用して OpenTelemetry セマンティック規約に準拠しています。スパンとログの両方が本番環境のモニタリングに適している必要があります。シグナルには、標準の OpenTelemetry 属性（http.response.status_code や rpc.system.name など）が含まれます。

標準属性の一覧については、OpenTelemetry HTTP と gRPC のセマンティック規則をご覧ください。

テレメトリー シグナルを有効にする

機密データを保護するため、テレメトリー シグナルはデフォルトで無効になっています。

Node.js では、トレースを出力するようにクライアントを構成し、これらのシグナルを外部サービスに送信するようにサブスクライバーとエクスポータを構成する必要があります。

クライアントを構成するには、次の環境変数を設定します。

export GOOGLE_SDK_NODE_ENABLE_TRACING=true

トレースが有効になっていて、クライアント ライブラリ メソッドを呼び出すときにアプリケーションの現在のコンテキストにアクティブな OpenTelemetry スパンがある場合、クライアント ライブラリは自動的にそのスパンをアクティブなスパンの子としてリンクします。

トレースをエクスポートする

クライアント ライブラリでテレメトリーを有効にしたら、このデータを収集してオブザーバビリティ サービスにエクスポートするようにアプリケーションを構成する必要があります。

OpenTelemetry トレース相関データの構成の詳細については、Node.js リポジトリ内のオブザーバビリティのサンプルをご覧ください。

Cloud de Confiance by S3NS クライアント ライブラリによって生成された tracing スパンを OpenTelemetry にエクスポートするには、トレーサー プロバイダとエクスポータを設定する必要があります。

const cloudTraceExporter = new TraceExporter();
const spanProcessor = new BatchSpanProcessor(cloudTraceExporter);

const provider = new NodeTracerProvider({
  spanProcessors: [spanProcessor],
});
provider.register();