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

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

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

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

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

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

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

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

注釈の要件

  • キー – 最大 500 の英数字。アンダースコアを除くスペースまたは記号はありません。

  • – 最大 1,000 のユニコード文字。

  • エントリ – トレースごとに最大 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 キーワードを使用します。