AWS Node.js 用 X-Ray SDK - AWS X-Ray

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS Node.js 用 X-Ray SDK

X-Ray SDK for Node.js は、Express ウェブアプリケーションと Node.js Lambda 関数用のライブラリです。トレースデータを作成して X-Ray デーモンに送信するためのクラスとメソッドを提供します。トレースデータには、アプリケーションが処理した受信 HTTP リクエストや、アプリケーションが AWS SDK または HTTP クライアントを使用してダウンストリームサービスに対して行う呼び出しに関する情報が含まれます。

Express を使用する場合は、アプリケーションサーバーで SDK をミドルウェアとして追加し、受信リクエストをトレースします。ミドルウェアでは、トレース対象リクエストごとに「セグメント」を作成し、レスポンスが送信されるとセグメントを完了します。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。

インストルメント済みアプリケーションまたはサービスによって呼び出される Lambda 関数の場合、Lambda は トレースヘッダー を読み取り、サンプリングされたリクエストを自動的にトレースします。その他の関数については、Lambda の設定 から受信リクエストのサンプリングとトレースを行うことができます。いずれの場合も、Lambda はセグメントを作成し、X-Ray SDK に提供します。

注記

Lambda では、X-Ray SDK はオプションです。関数でこれを使用しない場合、サービスマップには Lambda サービスのノードと Lambda 関数ごとに 1 つのノードが含まれます。SDK を追加することで、関数コードをインストルメントして、Lambda で記録された関数セグメントにサブセグメントを追加することができます。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

次に、Node.js 用 X-Ray SDK を使用して Node.js クライアント用の AWS JavaScript SDK をインストルメントします。 AWS のサービス インストゥルメントされたクライアントを使用してダウンストリームまたはリソースを呼び出すたびに、SDK はその呼び出しに関する情報をサブセグメントに記録します。 AWS のサービス また、サービス内でアクセスするリソースはトレースマップにダウンストリームノードとして表示されるため、個々の接続のエラーやスロットリングの問題を特定するのに役立ちます。

また、X-Ray SDK for Node.js では、HTTP ウェブ API と SQL クエリに対するダウンストリーム呼び出しの計測もできます。HTTP クライアントを SDK のキャプチャメソッドでラップして、送信 HTTP 呼び出しについての情報を記録します。SQL クライアントでは、データベースタイプのキャプチャメソッドを使用します。

ミドルウェアでは、受信リクエストにサンプリングルールを適用して、トレースするリクエストを決定します。X-Ray SDK for Node.js を設定して、サンプリング動作を調整したり、 AWS アプリケーションが実行されているコンピュートリソースに関する情報を記録したりできます。

アプリケーションが注釈やメタデータで行うリクエストや作業に関する追加情報を記録します。注釈は、フィルタ式で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化できるオブジェクトと配列全体を記録できます。

注釈とメタデータ

注釈およびメタデータとは、X-Ray SDK を使用してセグメントに追加する任意のテキストです。注釈は、フィルタ式用にインデックス付けされます。メタデータはインデックス化されませんが、X-Ray コンソールまたは API を使用して raw セグメントで表示できます。X-Ray への読み取りアクセスを許可した人は誰でも、このデータを表示できます。

コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。カスタムサブセグメントで、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションのサブセグメントを作成し、親セグメントにすべてのレコードを記述する代わりにサブセグメントにメタデータと注釈を記録できます。

SDK のクラスとメソッドに関するリファレンスドキュメントについては、AWS X-Ray SDK for Node.js API リファレンスを参照してください。

要件

X-Ray SDK for Node.js には Node.js および次のライブラリが必要です。

  • atomic-batcher – 1.0.2

  • cls-hooked – 4.2.2

  • pkginfo – 0.4.0

  • semver – 5.3.0

NPM を使用して SDK をインストールするときに、SDK ではこれらのライブラリを引き出します。

AWS SDK クライアントをトレースするには、Node.js 用 X-Ray SDK には Node.js の AWS SDK の最小バージョンが必要です。 JavaScript

  • aws-sdk - 2.7.15

依存関係管理

The X-Ray SDK for Node.js は NPM から入手できます。

ローカル開発の場合は、npm を使用してプロジェクトディレクトリに SDK をインストールします。

~/nodejs-xray$ npm install aws-xray-sdk aws-xray-sdk@3.3.3 ├─┬ aws-xray-sdk-core@3.3.3 │ ├── @aws-sdk/service-error-classification@3.15.0 │ ├── @aws-sdk/types@3.15.0 │ ├─┬ @types/cls-hooked@4.3.3 │ │ └── @types/node@15.3.0 │ ├── atomic-batcher@1.0.2 │ ├─┬ cls-hooked@4.2.2 │ │ ├─┬ async-hook-jl@1.7.6 │ │ │ └── stack-chain@1.3.7 │ │ └─┬ emitter-listener@1.1.2 │ │ └── shimmer@1.2.1 │ └── semver@5.7.1 ├── aws-xray-sdk-express@3.3.3 ├── aws-xray-sdk-mysql@3.3.3 └── aws-xray-sdk-postgres@3.3.3

--save オプションを使用して、SDK を依存関係としてアプリケーションの package.json に保存します。

~/nodejs-xray$ npm install aws-xray-sdk --save aws-xray-sdk@3.3.3

アプリケーションに X-Ray SDK の依存関係と競合するバージョンの依存関係がある場合、互換性を確保するために両方のバージョンがインストールされます。詳細については、依存関係の解決に関する公式 NPM ドキュメンテーションを参照してください。

Node.js サンプル

AWS X-Ray SDK for Node.js と連携させて、 end-to-end Node.js アプリケーションを通過するリクエストの様子を把握してください。

X-Ray SDK for Node.js の設定

X-Ray SDK for Node.js にプラグインを設定して、アプリケーションが実行されているサービスに関する情報が含めたり、デフォルトのサンプリング動作を変更したり、特定のパスに対するリクエストに適用されるサンプリングルールを追加したりできます。

サービスプラグイン

pluginsを使用して、アプリケーションをホストしているサービスに関する情報を記録します。

プラグイン
  • Amazon EC2 — インスタンス ID、アベイラビリティーゾーン、EC2Plugin CloudWatch およびロググループを追加します。

  • ElasticBeanstalk– ElasticBeanstalkPluginは、環境名、バージョンラベル、およびデプロイ ID を追加します。

  • Amazon ECS —ECSPluginは、コンテナ ID を追加します。

プラグインを使用するには、config メソッドを使用して X-Ray SDK for Node.js クライアントを設定します。

例 app.js - プラグイン
var AWSXRay = require('aws-xray-sdk'); AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

SDK はプラグイン設定を使用して、セグメントのoriginフィールドを設定します。 AWS これはアプリケーションを実行するリソースのタイプを示します。複数のプラグインを使用する場合、SDK は > EKS > ECS ElasticBeanstalk > EC2 の解決順序を使用してオリジンを判断します。

サンプリングルール

SDK は X-Ray コンソールで定義したサンプリングルールを使用し、記録するリクエストを決定します。デフォルトルールでは、最初のリクエストを毎秒トレースし、X-Ray にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。X-Ray コンソールに追加のルールを作成するをクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。

SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。

注記

SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。

JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、X-Ray サンプリングが利用できない場合のバックアップとしてローカルルールを使用することも、ローカルルールを排他的に使用することもできます。

例 sampling-rules.json
{ "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } }

この例では、1 つのカスタムルールとデフォルトルールを定義します。カスタムルールでは、5 パーセントのサンプリングレートが適用され、/api/move/以下のパスに対してトレースするリクエストの最小数はありません。デフォルトのルールでは、1秒ごとの最初のリクエストおよび追加リクエストの 10 パーセントをトレースします。

ルールをローカルで定義することの欠点は、固定ターゲットが X-Ray サービスによって管理されるのではなく、レコーダーの各インスタンスによって個別に適用されることです。より多くのホストをデプロイすると、固定レートが乗算され、記録されるデータ量の制御が難しくなります。

オン AWS Lambda、サンプリングレートは変更できません。関数がインストルメント化されたサービスによって呼び出された場合、そのサービスによってサンプリングされたリクエストを生成した呼び出しは Lambda によって記録されます。アクティブなトレースが有効で、トレースヘッダーが存在しない場合、Lambda はサンプリングを決定します。

バックアップルールを設定するには、setSamplingRulesの ファイルからサンプリングルールをロードするようX-Ray SDK for Node.js に指示します。

例 app.js - ファイルのサンプリングルール
var AWSXRay = require('aws-xray-sdk'); AWSXRay.middleware.setSamplingRules('sampling-rules.json');

コードのルールを定義し、オブジェクトとして setSamplingRules に渡すこともできます。

例 app.js - オブジェクトのサンプリングルール
var AWSXRay = require('aws-xray-sdk'); var rules = { "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }, "version": 1 } AWSXRay.middleware.setSamplingRules(rules);

ローカルルールのみを使用するには、disableCentralizedSampling を呼び出します。

AWSXRay.middleware.disableCentralizedSampling()

ログ記録

SDK からログ出力するには、AWSXRay.setLogger(logger) を呼び出します。logger は、標準のログ記録メソッド (warninfo、など) を提供するオブジェクトです。

デフォルトでは、SDK はコンソールオブジェクトの標準メソッドを使用してコンソールにエラーメッセージを記録します。組み込みロガーのログレベルは、AWS_XRAY_DEBUG_MODEまたはAWS_XRAY_LOG_LEVEL環境変数を使って設定できます。有効なログレベル値の一覧については、「環境変数」を参照してください。

ログに別の形式または宛先を指定したい場合は、次に示すように、SDK に独自のロガーインターフェイスの実装を提供できます。このインタフェースを実装するあらゆるオブジェクトを使用できます。つまり、Winston など、多くのロギングライブラリを使用して SDK に直接渡すことができるということです。

例 app.js - ログ記録
var AWSXRay = require('aws-xray-sdk'); // Create your own logger, or instantiate one using a library. var logger = { error: (message, meta) => { /* logging code */ }, warn: (message, meta) => { /* logging code */ }, info: (message, meta) => { /* logging code */ }, debug: (message, meta) => { /* logging code */ } } AWSXRay.setLogger(logger); AWSXRay.config([AWSXRay.plugins.EC2Plugin]);

他の設定方法を実行する前に、setLogger を呼び出して、これらの操作から出力をキャプチャすることを確認します。

X-Ray デーモンのアドレス

X-Ray デーモンが、127.0.0.1:2000 以外のポートまたはホスト上でリッスンする場合は、X-Ray SDK for Node.js を使用して、トレースデータを別のアドレスに送信することができます。

AWSXRay.setDaemonAddress('host:port');

ホストは、名前または IPv4 アドレス で指定できます。

例 app.js - デーモンのアドレス
var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('daemonhost:8082');

TCP および UDP の別のポートでリッスンするようデーモンを設定する場合、両方ともデーモンアドレスの設定で指定できます。

例 app.js - 別々のポートのデーモンのアドレス
var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

または、AWS_XRAY_DAEMON_ADDRESS 環境変数を使用して、デーモンアドレスを設定することもできます。

環境変数

環境変数を使用して、X-Ray SDK for Node.js を設定できます。SDK は次の変数をサポートしています。

  • AWS_XRAY_CONTEXT_MISSING – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、RUNTIME_ERROR に設定します。

    有効な値
    • RUNTIME_ERROR— ランタイム例外をスローします。

    • LOG_ERROR – エラーをログ記録して続行します (デフォルト)。

    • IGNORE_ERROR – エラーを無視して続行します。

    オープン状態のリクエストがない場合、または新しいスレッドを発生させるコードで、スタートアップコードに実装されたクライアントを使用しようとした場合に発生する可能性がある、セグメントまたはサブセグメントの欠落に関連するエラー。

  • AWS_XRAY_DAEMON_ADDRESS – X-Ray デーモンリスナーのホストとポートを設定します。デフォルトでは、SDK はトレースデータ (UDP) とサンプリング (TCP) の両方に127.0.0.1:2000を使用します。この変数は、デーモンを次のように構成している場合に使用します。別のポートでリッスンするまたは、別のホストで実行されている場合。

    [形式]
    • 同じポートaddress:port

    • 異なるポートtcp:address:port udp:address:port

  • AWS_XRAY_DEBUG_MODEdebugレベルでコンソールにログを出力するように SDK を設定するには、TRUEに設定します。

  • AWS_XRAY_LOG_LEVEL – デフォルトロガーのログレベルを設定します。有効な値は、debuginfowarnerrorsilent です。この値は、AWS_XRAY_DEBUG_MODE が TRUE に設定されている場合、無視されます。

  • AWS_XRAY_TRACING_NAME – SDK がセグメントに使用するサービス名を設定します。Express ミドルウェアを設定したセグメント名を上書きします。

X-Ray SDK for Node.js を使用して受信リクエストをトレースします。

X-Ray SDK for Node.js を使用して、Express アプリケーションと Restify アプリケーションが Amazon EC2 または Amazon ECS の EC2 インスタンス上で処理する受信 HTTP リクエストをトレースできます。 AWS Elastic Beanstalk

X-Ray SDK for Node.js は Express フレームワークおよび Restify フレームワークを使用するアプリケーションのミドルウェアを提供します。X-Ray ミドルウェアをアプリケーションに追加すると、X-Ray SDK for Node.js によってサンプリングされた各リクエストのセグメントが作成されます。このセグメントには、時間、メソッド、HTTP リクエストの処理などが含まれます。追加の計測により、このセグメントでサブセグメントが作成されます。

注記

AWS Lambda 関数の場合、Lambda はサンプリングされたリクエストごとにセグメントを作成します。詳細については、「AWS Lambda および AWS X-Ray」を参照してください。

各セグメントには、サービスマップ内のアプリケーションを識別する名前があります。セグメントの名前は静的に指定することも、受信リクエストのホストヘッダーに基づいて動的に名前を付けるように SDK を設定することもできます。動的ネーミングでは、リクエスト内のドメイン名に基づいてトレースをグループ化でき、名前が予想されるパターンと一致しない場合(たとえば、ホストヘッダーが偽造されている場合)、デフォルト名を適用できます。

転送されたリクエスト

ロードバランサーまたは他の仲介者がアプリケーションにリクエストを転送する場合、X-Ray は、クライアントの IP をIP パケットの送信元 IP からではなく、リクエストのX-Forwarded-Forヘッダーから取得します。転送されたリクエストについて記録されたクライアント IP は偽造される可能性があるため、信頼されるべきではありません。

リクエストが転送されると、それを示す追加フィールドが SDK によってセグメントに設定されます。セグメントのフィールド x_forwarded_fortrue に設定されている場合、クライアント IP が HTTP リクエストの X-Forwarded-For ヘッダーから取得されます。

メッセージハンドラーは、次の情報が含まれる http ブロックを使用して、各受信リクエスト用にセグメントを作成します。

  • HTTP メソッド – GET、POST、PUT、DELETE、その他。

  • クライアントアドレス – リクエストを送信するクライアントの IP アドレス。

  • レスポンスコード – 完了したリクエストの HTTP レスポンスコード。

  • タイミング – 開始時間 (リクエストが受信された時間) および終了時間 (レスポンスが送信された時間)。

  • ユーザーエージェント — リクエストからのuser-agent

  • コンテンツの長さ — レスポンスからのcontent-length

Express を使用した受信リクエストのトレース

Express ミドルウェアを使用するには、SDK クライアントを初期化して、ルートを定義する前に express.openSegment 関数によって返されたミドルウェアを使用します。

例 app.js - Express
var app = express(); var AWSXRay = require('aws-xray-sdk'); app.use(AWSXRay.express.openSegment('MyApp')); app.get('/', function (req, res) { res.render('index'); }); app.use(AWSXRay.express.closeSegment());

ルートを定義した後、express.closeSegment の出力を図のように使用して X-Ray SDK for Node.js によって返されたエラーを処理します。

Restify を使用した受信リクエストのトレース

Restify ミドルウェアを使用するには、SDK クライアントを初期化し、enable を実行します。Restify サーバーおよびセグメント名を渡します。

例 app.js - Restify
var AWSXRay = require('aws-xray-sdk'); var AWSXRayRestify = require('aws-xray-sdk-restify'); var restify = require('restify'); var server = restify.createServer(); AWSXRayRestify.enable(server, 'MyApp')); server.get('/', function (req, res) { res.render('index'); });

セグメント命名ルールの設定

AWS X-Ray サービス名を使用してアプリケーションを識別し、アプリケーションが使用する他のアプリケーション、データベース、外部 API、 AWS リソースと区別します。X-Ray SDK が受信リクエストのセグメントを生成すると、アプリケーションのサービス名がセグメントの名前フィールドに記録されます。

X-Ray SDK では、HTTP リクエストヘッダーのホスト名の後にセグメントの名前を指定できます。ただし、このヘッダーは偽造され、サービスマップに予期しないノードが発生する可能性があります。偽造されたホストヘッダーを持つリクエストによって SDK がセグメントの名前を間違えないようにするには、受信リクエストのデフォルト名を指定する必要があります。

アプリケーションが複数のドメインのリクエストを処理する場合、動的ネーミングストラテジーを使用してセグメント名にこれを反映するように SDK を設定できます。動的ネーミングストラテジーにより、SDK は予想されるパターンに一致するリクエストにホスト名を使用し、そうでないリクエストにデフォルト名を適用できます。

たとえば、3 つのサブドメイン(www.example.com,api.example.com,およびstatic.example.com)に対してリクエストを処理する単一のアプリケーションがあるとします。動的ネーミングストラテジーをパターン *.example.com で使用して、異なる名前を持つ各サブドメインのセグメントを識別することができます。結果的にはサービスマップ上に 3 つのサービスノードを作成することになります。アプリケーションがパターンと一致しないホスト名のリクエストを受信すると、指定したフォールバック名を持つ 4 番目のノードがサービスマップに表示されます。

すべてのリクエストセグメントに対して同じ名前を使用するには、前のセクションで示すとおり、ミドルウェアを初期化するときに、アプリケーションの名前を指定します。

注記

コードで定義したデフォルトのサービス名は、AWS_XRAY_TRACING_NAME 環境変数で上書きできます。

動的な命名戦略は、ホスト名と一致するようパターンを定義し、HTTP リクエストのホスト名がパターンと一致しない場合はデフォルトの名前を使用します。動的にセグメントに命名するには、AWSXRay.middleware.enableDynamicNaming を使用します。

例 app.js - 動的セグメントの名前

リクエストのホスト名がパターン *.example.com と一致する場合は、そのホスト名を使用します。それ以外の場合は、MyApp を使用します。

var app = express(); var AWSXRay = require('aws-xray-sdk'); app.use(AWSXRay.express.openSegment('MyApp')); AWSXRay.middleware.enableDynamicNaming('*.example.com'); app.get('/', function (req, res) { res.render('index'); }); app.use(AWSXRay.express.closeSegment());

X-Ray SDK for Node.js を使用してダウンストリーム HTTP ウェブサービスの呼び出しをトレースする

アプリケーションがマイクロサービスまたはパブリック HTTP API に呼び出しを実行する場合に、X-Ray SDK for Node.js クライアントを使用してこれらの呼び出しを計測し、API をダウンストリームサービスとしてサービスグラフに追加できます。

http または https クライアントを X-Ray SDK for Node.js の captureHTTPs メソッドに渡して、送信呼び出しをトレースします。

注記

Axios や Superagent などのサードパーティー製の HTTP リクエストライブラリを使用する呼び出しは captureHTTPsGlobal() API を通じてサポートされ、ネイティブ http モジュールを使用する場合でもトレースされます。

例 app.js - HTTP クライアント
var AWSXRay = require('aws-xray-sdk'); var http = AWSXRay.captureHTTPs(require('http'));

すべての HTTP クライアントのトレースを有効にするには、http をロードする前に captureHTTPsGlobal を呼び出します。

例 app.js - HTTP クライアント (グローバル)
var AWSXRay = require('aws-xray-sdk'); AWSXRay.captureHTTPsGlobal(require('http')); var http = require('http');

ダウンストリームウェブ API に対する呼び出しを計測すると、X-Ray SDK for Node.js は HTTP リクエストおよびレスポンスに関する情報を含むセグメントを記録します。X-Ray はサブセグメントを使用してリモート API の推測セグメントを生成します。

例 ダウンストリーム HTTP 呼び出しのサブセグメント
{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } } }
例 ダウンストリーム HTTP 呼び出しの推定セグメント
{ "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-62be1272-1b71c4274f39f122afa64eab", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true }

X-Ray SDK for Node.js を使用して SQL クエリをトレースします。

SQL クライアントを対応する X-Ray SDK for Node.js クライアントメソッドでラップすることにより、SQL データベースクエリを計測します。

  • PostgreSQLAWSXRay.capturePostgres()

    var AWSXRay = require('aws-xray-sdk'); var pg = AWSXRay.capturePostgres(require('pg')); var client = new pg.Client();
  • MySQLAWSXRay.captureMySQL()

    var AWSXRay = require('aws-xray-sdk'); var mysql = AWSXRay.captureMySQL(require('mysql')); ... var connection = mysql.createConnection(config);

計測済みクライアントを使用して SQL クエリを作成すると、&X-Ray-nodejssdk; は、サブセグメントに接続およびクエリに関する情報を記録します。

SQL サブセグメントに追加データを含める

許可リストに登録された SQL フィールドにマップされている限り、SQL クエリ用に生成されたサブセグメントに情報を追加できます。たとえば、サニタイズされた SQL クエリ文字列をサブセグメントに記録するには、サブセグメントの SQL オブジェクトに直接追加できます。

例 サブセグメントへの SQL の割り当て
const queryString = 'SELECT * FROM MyTable'; connection.query(queryString, ...); // Retrieve the most recently created subsegment const subs = AWSXRay.getSegment().subsegments; if (subs & & subs.length > 0) { var sqlSub = subs[subs.length - 1]; sqlSub.sql.sanitized_query = queryString; }

許可リストに登録されている SQL フィールドの完全な一覧については、AWS X-Ray デベロッパーガイドにある「SQL クエリ」を参照してください。

X-Ray SDK for Node.js を使用したカスタムサブセグメントの生成

サブセグメントはリクエストを処理するために行われた作業の詳細を含んだトレースのセグメントを拡張します。計測済みクライアント内で呼び出しを行うたびに、X-Ray SDK によってサブセグメントに生成された情報が記録されます。追加のサブセグメントを作成して、他のサブセグメントをグループ化したり、コードセクションのパフォーマンスを測定したり、注釈とメタデータを記録したりできます。

カスタム Express サブセグメント

ダウンストリームサービス呼び出しを行う関数用のカスタムセグメントを作成するには、captureAsyncFunc 関数を使用します。

例 app.js - カスタムサブセグメント Express
var AWSXRay = require('aws-xray-sdk'); app.use(AWSXRay.express.openSegment('MyApp')); app.get('/', function (req, res) { var host = 'api.example.com'; AWSXRay.captureAsyncFunc('send', function(subsegment) { sendRequest(host, function() { console.log('rendering!'); res.render('index'); subsegment.close(); }); }); }); app.use(AWSXRay.express.closeSegment()); function sendRequest(host, cb) { var options = { host: host, path: '/', }; var callback = function(response) { var str = ''; response.on('data', function (chunk) { str += chunk; }); response.on('end', function () { cb(); }); } http.request(options, callback).end(); };

この例では、アプリケーションにより、sendRequest 関数への呼び出すために send という名前のカスタムサブセグメントが作成されます。captureAsyncFunc は、非同期呼び出しが完了したときにコールバック関数内で閉じる必要があるサブセグメントを渡します。

同期関数の場合は、captureFunc 関数を使用できます。これにより、関数ブロックの実行が終了するとサブセグメントが自動的に閉じられます。

セグメントまたは別のサブセグメント内にサブセグメントを作成する場合、X-Ray SDK for Node.js によってその ID が生成され、開始時刻と終了時刻が記録されます。

例 サブセグメントとメタデータ
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },

カスタム Lambda サブセグメント

SDK は、Lambda で実行中であることを検出したときに、プレースホルダファサードセグメントを自動的に作成するように設定されています。X-Ray トレースマップに 1 AWS::Lambda::Function つのノードを作成する基本的なサブセグメントを作成するには、ファサードセグメントを呼び出して再利用します。新しい ID を使用して新しいセグメントを手動で作成すると (トレース ID、親 ID、サンプリングデシジョンを共有しているときに)、新しいセグメントを送信できるようになります。

例 app.js - 手動カスタムサブセグメント
const segment = AWSXRay.getSegment(); //returns the facade segment const subsegment = segment.addNewSubsegment('subseg'); ... subsegment.close(); //the segment is closed by the SDK automatically

X-Ray SDK for Node.js を使用してセグメントに注釈とメタデータを追加する

注釈とメタデータを使用して、リクエスト、環境、またはアプリケーションに関する追加情報を記録できます。X-Ray SDK が作成するセグメントまたは作成するカスタムサブセグメントに、注釈およびメタデータを追加できます。

注釈は文字列、数値、またはブール値を使用したキーと値のペアです。注釈は、フィルタ式用にインデックス付けされます。注釈を使用して、コンソールでトレースをグループ化するため、またはGetTraceSummaries API を呼び出すときに使用するデータを記録します。

メタデータは、オブジェクトとリストを含む、任意のタイプの値を持つことができるキーバリューのペアですが、フィルタ式に使用するためにインデックスは作成されません。メタデータを使用してトレースに保存する追加のデータを記録しますが、検索で使用する必要はありません。

注釈とメタデータに加えて、セグメントにユーザー ID 文字列を記録することもできます。ユーザー ID はセグメントの個別のフィールドに記録され、検索用にインデックスが作成されます。

X-Ray SDK for Node.js を使用して注釈を記録

注釈を使用して、検索用にインデックスを作成するセグメントまたはサブセグメントに情報を記録します。

注釈の要件
  • キー — X-Ray アノテーションのキーには、最大 500 文字の英数字を使用できます。アンダースコア記号 (_) 以外のスペースや記号は使用できません。

  • — X-Ray アノテーションの値には、最大 1,000 文字の Unicode 文字を使用できます。

  • 注釈の数 — 1 つのトレース 1 つにつき最大 50 個の注釈を使用できます。

注釈を記録するには
  1. 現在のセグメントまたはサブセグメントの参照を取得します。

    var AWSXRay = require('aws-xray-sdk'); ... var document = AWSXRay.getSegment();
  2. 文字列キー、および、ブール値、数値、文字列値を使用して addAnnotation を呼び出します。

    document.addAnnotation("mykey", "my value");

SDK は、セグメントドキュメントの annotations オブジェクトにキーと値のペアとして、注釈を記録します。同じキーで addAnnotation を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。

特定の値を持つ注釈のあるトレースを見つけるには、annotations.keyフィルタ式 キーワードを使用します。

例 app.js - 注釈
var AWS = require('aws-sdk'); var AWSXRay = require('aws-xray-sdk'); var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB()); ... app.post('/signup', function(req, res) { var item = { 'email': {'S': req.body.email}, 'name': {'S': req.body.name}, 'preview': {'S': req.body.previewAccess}, 'theme': {'S': req.body.theme} }; var seg = AWSXRay.getSegment(); seg.addAnnotation('theme', req.body.theme); ddb.putItem({ 'TableName': ddbTable, 'Item': item, 'Expected': { email: { Exists: false } } }, function(err, data) { ...

X-Ray SDK for Node.js を使用したメタデータの記録

メタデータを使用して、検索用にインデックスを作成する必要のないセグメントまたはサブセグメントに情報を記録します。メタデータ値は、文字列、数値、ブール値、または JSON オブジェクトや JSON 配列にシリアル化できるその他の任意のオブジェクトになります。

メタデータを記録するには
  1. 現在のセグメントまたはサブセグメントの参照を取得します。

    var AWSXRay = require('aws-xray-sdk'); ... var document = AWSXRay.getSegment();
  2. 文字列キー、ブール値、数値、文字列値、オブジェクト値、文字列名前空間を使用して addMetadata を呼び出します。

    document.addMetadata("my key", "my value", "my namespace");

    または

    キーと値だけを使用して addMetadata を呼び出します。

    document.addMetadata("my key", "my value");

名前空間を指定しない場合、SDK は default を使用します。同じキーで addMetadata を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。

X-Ray SDK for Node.js を使用したユーザー ID の記録

リクエストセグメントにユーザー ID を記録して、リクエストを送信したユーザーを識別します。Lambda AWS Lambda 環境のセグメントは不変であるため、この操作は関数と互換性がありません。setUser の呼び出しはセグメントにのみ適用でき、サブセグメントには適用できません。

ユーザー ID を記録するには
  1. 現在のセグメントまたはサブセグメントの参照を取得します。

    var AWSXRay = require('aws-xray-sdk'); ... var document = AWSXRay.getSegment();
  2. リクエストを送信したユーザーの文字列 ID を使用して setUser() を呼び出します。

    var user = 'john123'; AWSXRay.getSegment().setUser(user);

setUser を呼び出し、Express アプリケーションがリクエストの処理を開始するとすぐに、ユーザー ID を記録できます。ユーザー ID を設定するためだけにセグメントを使用する場合、呼び出しを 1 行で連鎖させることができます。

例 app.js - ユーザー ID
var AWS = require('aws-sdk'); var AWSXRay = require('aws-xray-sdk'); var uuidv4 = require('uuid/v4'); var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB()); ... app.post('/signup', function(req, res) { var userId = uuidv4(); var item = { 'userId': {'S': userId}, 'email': {'S': req.body.email}, 'name': {'S': req.body.name} }; var seg = AWSXRay.getSegment().setUser(userId); ddb.putItem({ 'TableName': ddbTable, 'Item': item, 'Expected': { email: { Exists: false } } }, function(err, data) { ...

ユーザー ID のトレースを見つけるには、userフィルタ式で、 キーワードを使用します。