api.asciidoc in elastic-apm-2.12.0

- old
+ new

@@ -258,11 +258,11 @@
 [[api-agent-set-tag]]
 ==== `ElasticAPM.set_tag`
 
 Add a tag to the current transaction.
 Tags are basic key-value pairs that are indexed in your Elasticsearch database
-and therefore searchable.
+and therefore searchable. The value will always be converted to a String.
 
 TIP: Before using custom tags, ensure you understand the different types of
 {apm-overview-ref-v}/metadata.html[metadata] that are available.
 
 [source,ruby]
@@ -278,9 +278,38 @@
   * `value`: A string value.
 
 Returns the set `value`.
 
 WARNING: Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in *https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]*.
+
+NOTE: This method has been deprecated in favor of `set_label`, which does not convert values to Strings.
+
+[float]
+[[api-agent-set-label]]
+==== `ElasticAPM.set_label`
+
+Add a label to the current transaction.
+Labels are basic key-value pairs that are indexed in your Elasticsearch database and therefore searchable.
+The value can be a string, nil, numeric or boolean.
+
+TIP: Before using custom labels, ensure you understand the different types of
+{apm-overview-ref-v}/metadata.html[metadata] that are available.
+
+[source,ruby]
+----
+before_action do
+  ElasticAPM.set_label(:company_id, current_user.company.id)
+end
+----
+
+Arguments:
+
+  * `key`: A string key. Note that `.`, `*` or `"` will be converted to `_`.
+  * `value`: A value.
+
+Returns the set `value`.
+
+WARNING: Be aware that labels are indexed in Elasticsearch. Using too many unique keys will result in *https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]*.
 
 [float]
 [[api-agent-set-custom-context]]
 ==== `ElasticAPM.set_custom_context`
 