Metadata can enrich your events and make application performance monitoring even more useful. Let’s explore the different types of metadata that Elastic APM offers.


Labels are used to add indexed information to transactions, spans, and errors. Indexed means the data is searchable and aggregatable in Elasticsearch. Multiple labels can be defined with different key-value pairs.

  • Indexed: Yes
  • Elasticsearch type: object
  • Elasticsearch field: labels (context.tags in APM Server pre-7.0)
  • Applies to Transactions | Spans | Errors

Label values can be a string, boolean, or number in APM Server 6.7+. Using this API in combination with an older APM Server version leads to validation errors. In addition, some agents only support string values at this time. Because labels for a given key, regardless of agent used, are stored in the same place in Elasticsearch, all label values of a given key must have the same data type. Multiple data types per key will throw an exception, e.g. {foo: bar} and {foo: 42}

Avoid defining too many user-specified labels. Defining too many unique fields in an index is a condition that can lead to a mapping explosion.

Labels API links

Go: SetTag Java: addLabel Node.js: setTag | addTags Python: tag Ruby: set_tag Rum: addTags

Custom contextedit

Custom context is used to add non-indexed, custom contextual information to transactions and errors. Non-indexed means the data is not searchable or aggregatable in Elasticsearch, and you cannot build dashboards on top of the data. This also means you do not have to worry about mapping explosions, as these fields are not added to the mapping.

Non-indexed information is useful for providing contextual information to help you quickly debug performance issues or errors.

  • Indexed: No
  • Elasticsearch type: object
  • Elasticsearch fields: transaction.custom | error.custom
  • Applies to Transactions | Errors

Setting a circular object, large object, or a non JSON serializable object can lead to errors.

Custom context API links

Go: coming soon Java: coming soon Node.js: setCustomContext Python: set_custom_context Ruby: set_custom_context Rum: setCustomContext

User contextedit

User context is used to add indexed user information to transactions and errors. Indexed means the data is searchable and aggregatable in Elasticsearch.

  • Indexed: Yes
  • Elasticsearch type: keywords
  • Elasticsearch fields: | |
  • Applies to Transactions | Errors

User context API links

Go: SetUsername | SetUserID | SetUserEmail Java: setUser Node.js: setUserContext Python: set_user_context Ruby: set_user Rum: setUserContext