AWS X-Ray
開発者ガイド

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

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

Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for use with filter expressions. Use annotations to record data that you want to use to group traces in the console, or when calling the GetTraceSummaries API.

Metadata are key-value pairs that can have values of any type, including objects and lists, but are not indexed for use with filter expressions. Use metadata to record additional data that you want stored in the trace but don't need to use with search.

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 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。