Menu
AWS X-Ray
Developer Guide

Add Annotations and Metadata to Segments with the X-Ray SDK for Node.js

You can record additional information about requests or your application to the segments that the X-Ray SDK creates, or to custom subsegments that you create.

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.

Recording Annotations with the X-Ray SDK for Node.js

Use annotations to record information on segments or subsegments that you want indexed for search.

Annotation Requirements

  • Keys – Up to 500 alphanumeric characters. No spaces or symbols except underscores.

  • Values – Up to 1,000 Unicode characters.

  • Entries – Up to 50 annotations per trace.

To record annotations

  1. Get a reference to the current segment or subsegment.

    var AWSXRay = require('aws-xray-sdk');
    ...
    var document = AWSXRay.getSegment();
  2. Call addAnnotation with a String key, and a Boolean, Number, or String value.

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

The SDK records annotations as key-value pairs in an annotations object in the segment document. Calling addAnnotation twice with the same key overwrites previously recorded values on the same segment or subsegment.

To find traces that have annotations with specific values, use the annotations.key keyword in a filter expression.

Example app.js - Annotations

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) {
...

Recording Metadata with the X-Ray SDK for Node.js

Use metadata to record information on segments or subsegments that you don't need indexed for search. Metadata values can be strings, numbers, Booleans, or any other object that can be serialized into a JSON object or array.

To record metadata

  1. Get a reference to the current segment or subsegment.

    var AWSXRay = require('aws-xray-sdk');
    ...
    var document = AWSXRay.getSegment();
  2. Call addMetadata with a string key, a Boolean, number, string, or object value, and a string namespace.

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

    or

    Call addMetadata with just a key and value.

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

If you don't specify a namespace, the SDK uses default. Calling addMetadata twice with the same key overwrites previously recorded values on the same segment or subsegment.