Tagging traces can help you enrich the data collected as part of the trace for two main reasons:

• To pinpoint a specific event in our application.
• To detect trends based on a unique-business dimension.

Tagging adds more context to an existing trace. Tags are comprised of a key-value pair, such that key=value.

Examples of popular tags used:

Use Cases

Tags help us in the following scenarios:

• Correlate incidents and customers – Looking for a problem that happened to a specific user/customer in our application.
• Insights into the customer experience – Understanding the performance metrics of a specific event in our system.
• Business trends – Looking at trends for business KPIs.

Tagging in Epsagon

Tagging is simple. Use the label function to create new tags.

epsagon.label('key', 'value')

For example with an Express.js application, you can tag your user ID:

router.get('/test', (req, res, next) => {
    req.epsagon.label('userID', req.query.userId);
    res.send('success');
});

Once your application generates traces with the new tag, you'll be able to see it in the Trace View, under Labels:

Indexing custom tags

You can configure Epsagon to index additional tags from your traces, even ones that are inside nested JSON payloads. This will allow you to search traces and create alerts based on your own custom tags.

For example, you may have a trace of an SNS message where the message itself is a JSON object, and you are interested in indexing the user field, like so:

• To index custom tags, click Index Tags, and select the tag you want to be indexed.
• To manage custom indexed tags, go to Custom Indexed Tags.
• Custom tags support simple values of type numeric, string or boolean.
• Custom tags additionally support array values. For example, for a trace with an SNS payload containing a field named users containing a list of user IDs, indexing by aws.sns.message.users will index the trace by all the user IDs in that list. Moreover, array values are expanded recursively - if in the same example users is an array of structured user info as dictionary items, and each contains a user_id field, then indexing by aws.sns.message.users.user_id will index all the user_id values under all the users items, etc. Note that resulting array items should all be of the same type, which is one of the named basic types.

After adding an indexed tag, Epsagon will search your payloads for those tags, and index them in addition to other tags within a few minutes. Once a trace with the new tag is sent, you will be able to filter it via the trace search page:

Equivalent JSON payload in SNS:

{
    'user': 'John Adams',
    'ID': 1234
}