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, exception messages and more. 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, like so:

Adding a custom indexed tag over aws.sns.message.user, will allow you to search traces and create alerts based on the user field sent in the JSON-encoded SNS payload.

To index custom tags from the trace view, click Index Tags, and select the tag you want to be indexed. To manage custom indexed tags, go to Custom Indexed Tags.

You can also index JSON attributes that are displayed as strings but can JSONified.

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
}

Custom Tags Data Types

• 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.
• Custom tags can be used to index object types (key-value mappings). These values are encoded and indexed as jsons. To index particular nested object values, use the "." syntax for object expansion, e.g. http.response.errorType will index the field errorType under the object response in the object http.
• Each custom tag is assumed to have a single value type across all traces in which it exists. If different traces provide different value types over the same custom indexed tag, then the indexed type of that tag is chosen arbitrarily, and traces with conflicting types will not be indexed by that tag. Custom tags expanded over arrays or objects are assumed to have the same value type over all items resulting from that expansion.
• Custom tag paths are restricted to alphanumeric, dots ("."), hyphens ("-") and underscores ("_"). Note that "." have a reserved meaning of object expansion.
• As "." have the special meaning of object expansion, Epsagon does not allow defining any two custom tags where one is a dotted-prefix of another, e.g. http.response.body and http.response.body.errorType. This, however, can be circumvented by providing non-conflicting aliases for the tags - see next.

Custom Tags Aliases

Epsagon allows user-defined aliases for custom tags. These are typically used to provide a shorter, meaningful name for otherwise long, complex tags.

When creating a custom tag, Epsagon suggest an alias which is the same as the tagged path by default. To modify the alias, either change it when creating the tag, or provide recreate the same tag with a different alias (via the span page of the custom tags settings).

Epsagon indexes tags by either the alias or the original path, but not both. Meaning, if you've defined a custom tag over http.response.errorType with the alias http_error_type, all spans will be indexed and searchable by http_error_type (but not by http.response.errorType). This is consistent across span search, dashboard panels, alerts and all other components referencing indexed tags.

As a side effect, aliases can be used to circumvent the conflicting-tag-names limitation. For example, to have Epsagon index both http.response.body (when available and string-type) and http.response.body.errorType (when available and numeric-type), the user can define two custom indexed tags: one aliased as http_response_body and another as http_response_body_error_type. Both tags will be indexed and will work as the aliases do not conflict one another.