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:
Type | Description |
---|---|
Identifiers | Help us to pinpoint an event based on our application unique identifiers. For example |
Flow control | Help us understand what happened in the code. For example, |
Business metrics | Help us to understand some unique business KPIs. For example, the quantity of |
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.
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 byaws.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 exampleusers
is an array of structured user info as dictionary items, and each contains auser_id
field, then indexing byaws.sns.message.users.user_id
will index all theuser_id
values under all theusers
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 fielderrorType
under the objectresponse
in the objecthttp
. - 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
andhttp.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.
Updated 2 months ago