deprecate tags, add labels, and add support for typed labels (#538)

fixes #517
closes #538

Author: beniwohli

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Breaking changes
 
  * implemented type/subtype/action hierachy for spans. Ensure that you run at least APM Server 6.6 (#377)
+ * renamed tags to labels and changed API. The old API remains for backwards compatibility until 6.0 of the agent (#538)
 
 ## Other changes
 

docs/api.asciidoc

@@ -263,7 +263,7 @@ import elasticapm
 def coffee_maker(strength):
     fetch_water()
 
-    with elasticapm.capture_span('near-to-machine', tags={"type": "arabica"}):
+    with elasticapm.capture_span('near-to-machine', labels={"type": "arabica"}):
         insert_filter()
         for i in range(strengh):
             pour_coffee()
@@ -277,17 +277,17 @@ def coffee_maker(strength):
  * `span_type`: The type of the span, usually in a dot-separated hierarchy of `type`, `subtype`, and `action`, e.g. `db.mysql.query`. Alternatively, type, subtype and action can be provided as three separate arguments, see `span_subtype` and `span_action`.
  * `skip_frames`: The number of stack frames to skip when collecting stack traces. Defaults to `0`.
  * `leaf`: if `True`, all spans nested bellow this span will be ignored. Defaults to `False`.
- * `tags`: a dictionary of tags. Both keys and values must be strings. Defaults to `None`.
+ * `labels`: a dictionary of labels. Keys must be strings, values can be strings, booleans, or numerical (`int`, `float`, `decimal.Decimal`). Defaults to `None`.
  * `span_subtype`: subtype of the span, e.g. name of the database. Defaults to `None`.
  * `span_action`: action of the span, e.g. `query`. Defaults to `None`
 
 [float]
-[[api-tag]]
-==== `elasticapm.tag()`
+[[api-label]]
+==== `elasticapm.label()`
 
-Attach tags to the the current transaction and errors.
+Attach labels to the the current transaction and errors.
 
-TIP: Before using custom tags, ensure you understand the different types of
+TIP: Before using custom labels, ensure you understand the different types of
 {apm-overview-ref-v}/metadata.html[metadata] that are available.
 
 Example:
@@ -296,16 +296,16 @@ Example:
 ----
 import elasticapm
 
-elasticapm.tag(ecommerce=True, dollar_value=47.12)
+elasticapm.label(ecommerce=True, dollar_value=47.12)
 ----
 
-Errors that happen after this call will also have the tags attached to them.
-You can call this function multiple times, new tags will be merged with existing tags,
+Errors that happen after this call will also have the labels attached to them.
+You can call this function multiple times, new labels will be merged with existing labels,
 following the `update()` semantics of Python dictionaries.
 
-The value is converted to a string.
-`.`, `*`, and `"` are invalid characters for tag names and will be replaced with `_`.
+Keys must be strings, values can be strings, booleans, or numerical (`int`, `float`, `decimal.Decimal`)
+`.`, `*`, and `"` are invalid characters for label names and will be replaced with `_`.
 
-WARNING: Avoid defining too many user-specified tags.
+WARNING: Avoid defining too many user-specified labels.
 Defining too many unique fields in an index is a condition that can lead to a
 {ref}/mapping.html#mapping-limit-settings[mapping explosion].

docs/configuration.asciidoc

@@ -501,7 +501,7 @@ WARNING: We recommend to always include the default set of validators if you cus
 
 By default, the agent will sample every transaction (e.g. request to your service).
 To reduce overhead and storage requirements, you can set the sample rate to a value between `0.0` and `1.0`.
-We still record overall time and the result for unsampled transactions, but no context information, tags, or spans.
+We still record overall time and the result for unsampled transactions, but no context information, labels, or spans.
 
 [float]
 [[config-include-paths]]

elasticapm/__init__.py

@@ -40,5 +40,5 @@
 from elasticapm.conf import setup_logging  # noqa: F401
 from elasticapm.instrumentation.control import instrument, uninstrument  # noqa: F401
 from elasticapm.traces import capture_span, set_context, set_custom_context  # noqa: F401
-from elasticapm.traces import set_transaction_name, set_user_context, tag  # noqa: F401
+from elasticapm.traces import set_transaction_name, set_user_context, tag, label  # noqa: F401
 from elasticapm.traces import set_transaction_result  # noqa: F401

elasticapm/base.py

@@ -341,8 +341,8 @@ def _build_msg_for_logging(
         else:
             context = transaction_context
         event_data["context"] = context
-        if transaction and transaction.tags:
-            context["tags"] = deepcopy(transaction.tags)
+        if transaction and transaction.labels:
+            context["tags"] = deepcopy(transaction.labels)
 
         # if '.' not in event_type:
         # Assume it's a builtin

elasticapm/conf/constants.py

@@ -28,6 +28,8 @@
 #  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 #  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+import decimal
+
 EVENTS_API_PATH = "intake/v2/events"
 
 TRACE_CONTEXT_VERSION = 0
@@ -45,3 +47,11 @@
 TRANSACTION = "transaction"
 SPAN = "span"
 METRICSET = "metricset"
+
+
+try:
+    # Python 2
+    TAG_TYPES = (bool, int, long, float, decimal.Decimal)
+except NameError:
+    # Python 3
+    TAG_TYPES = (bool, int, float, decimal.Decimal)

elasticapm/contrib/opentracing/span.py

@@ -101,7 +101,7 @@ def set_tag(self, key, value):
             elif key == tags.COMPONENT:
                 traces.set_context({"framework": {"name": value}}, "service")
             else:
-                self.elastic_apm_ref.tag(**{key: value})
+                self.elastic_apm_ref.label(**{key: value})
         else:
             if key.startswith("db."):
                 span_context = self.elastic_apm_ref.context or {}
@@ -115,12 +115,12 @@ def set_tag(self, key, value):
                     span_context["db"]["type"] = value
                     self.elastic_apm_ref.type = "db." + value
                 else:
-                    self.elastic_apm_ref.tag(**{key: value})
+                    self.elastic_apm_ref.label(**{key: value})
                 self.elastic_apm_ref.context = span_context
             elif key == tags.SPAN_KIND:
                 self.elastic_apm_ref.type = value
             else:
-                self.elastic_apm_ref.tag(**{key: value})
+                self.elastic_apm_ref.label(**{key: value})
         return self
 
     def finish(self, finish_time=None):

elasticapm/traces.py

@@ -35,16 +35,18 @@
 import threading
 import time
 import timeit
+import warnings
 from collections import defaultdict
 
 from elasticapm.conf import constants
 from elasticapm.conf.constants import SPAN, TRANSACTION
 from elasticapm.context import init_execution_context
 from elasticapm.metrics.base_metrics import Timer
 from elasticapm.utils import compat, encoding, get_name_from_func
+from elasticapm.utils.deprecation import deprecated
 from elasticapm.utils.disttracing import TraceParent, TracingOptions
 
-__all__ = ("capture_span", "tag", "set_transaction_name", "set_custom_context", "set_user_context")
+__all__ = ("capture_span", "tag", "label", "set_transaction_name", "set_custom_context", "set_user_context")
 
 error_logger = logging.getLogger("elasticapm.errors")
 logger = logging.getLogger("elasticapm.traces")
@@ -86,11 +88,11 @@ def duration(self):
 
 
 class BaseSpan(object):
-    def __init__(self, tags=None):
+    def __init__(self, labels=None):
         self._child_durations = ChildDuration(self)
-        self.tags = {}
-        if tags:
-            self.tag(**tags)
+        self.labels = {}
+        if labels:
+            self.label(**labels)
 
     def child_started(self, timestamp):
         self._child_durations.start(timestamp)
@@ -101,16 +103,39 @@ def child_ended(self, timestamp):
     def end(self, skip_frames=0):
         raise NotImplementedError()
 
+    def label(self, **labels):
+        """
+        Label this span with one or multiple key/value labels. Keys should be strings, values can be strings, booleans,
+        or numerical values (int, float, Decimal)
+
+            span_obj.label(key1="value1", key2=True, key3=42)
+
+        Note that keys will be dedotted, replacing dot (.), star (*) and double quote (") with an underscore (_)
+
+        :param labels: key/value pairs of labels
+        :return: None
+        """
+        for key, value in compat.iteritems(labels):
+            if not isinstance(value, constants.TAG_TYPES):
+                value = encoding.keyword_field(compat.text_type(value))
+            self.labels[TAG_RE.sub("_", compat.text_type(key))] = value
+
+    @deprecated("transaction/span.label()")
     def tag(self, **tags):
         """
+        This method is deprecated, please use "label()" instead.
+
         Tag this span with one or multiple key/value tags. Both the values should be strings
 
             span_obj.tag(key1="value1", key2="value2")
 
         Note that keys will be dedotted, replacing dot (.), star (*) and double quote (") with an underscore (_)
+
+        :param tags: key/value pairs of tags
+        :return: None
         """
         for key in tags.keys():
-            self.tags[TAG_RE.sub("_", compat.text_type(key))] = encoding.keyword_field(compat.text_type(tags[key]))
+            self.labels[TAG_RE.sub("_", compat.text_type(key))] = encoding.keyword_field(compat.text_type(tags[key]))
 
 
 class Transaction(BaseSpan):
@@ -178,7 +203,7 @@ def _begin_span(
         span_type,
         context=None,
         leaf=False,
-        tags=None,
+        labels=None,
         parent_span_id=None,
         span_subtype=None,
         span_action=None,
@@ -198,7 +223,7 @@ def _begin_span(
                 span_type=span_type or "code.custom",
                 context=context,
                 leaf=leaf,
-                tags=tags,
+                labels=labels,
                 parent=parent_span,
                 parent_span_id=parent_span_id,
                 span_subtype=span_subtype,
@@ -209,14 +234,14 @@ def _begin_span(
         execution_context.set_span(span)
         return span
 
-    def begin_span(self, name, span_type, context=None, leaf=False, tags=None, span_subtype=None, span_action=None):
+    def begin_span(self, name, span_type, context=None, leaf=False, labels=None, span_subtype=None, span_action=None):
         """
         Begin a new span
         :param name: name of the span
         :param span_type: type of the span
         :param context: a context dict
         :param leaf: True if this is a leaf span
-        :param tags: a flat string/string dict of tags
+        :param labels: a flat string/string dict of labels
         :param span_subtype: sub type of the span, e.g. "postgresql"
         :param span_action: action of the span , e.g. "query"
         :return: the Span object
@@ -226,7 +251,7 @@ def begin_span(self, name, span_type, context=None, leaf=False, tags=None, span_
             span_type,
             context=context,
             leaf=leaf,
-            tags=tags,
+            labels=labels,
             parent_span_id=None,
             span_subtype=span_subtype,
             span_action=span_action,
@@ -257,7 +282,7 @@ def ensure_parent_id(self):
         return self.trace_parent.span_id
 
     def to_dict(self):
-        self.context["tags"] = self.tags
+        self.context["tags"] = self.labels
         result = {
             "id": self.id,
             "trace_id": self.trace_parent.trace_id,
@@ -301,7 +326,7 @@ class Span(BaseSpan):
         "parent",
         "parent_span_id",
         "frames",
-        "tags",
+        "labels",
         "_child_durations",
     )
 
@@ -312,7 +337,7 @@ def __init__(
         span_type,
         context=None,
         leaf=False,
-        tags=None,
+        labels=None,
         parent=None,
         parent_span_id=None,
         span_subtype=None,
@@ -326,7 +351,7 @@ def __init__(
         :param span_type: type of the span, e.g. db
         :param context: context dictionary
         :param leaf: is this span a leaf span?
-        :param tags: a dict of tags
+        :param labels: a dict of labels
         :param parent_span_id: override of the span ID
         :param span_subtype: sub type of the span, e.g. mysql
         :param span_action: sub type of the span, e.g. query
@@ -359,7 +384,7 @@ def __init__(
         if self.transaction._breakdown:
             p = self.parent if self.parent else self.transaction
             p.child_started(self.start_time)
-        super(Span, self).__init__(tags=tags)
+        super(Span, self).__init__(labels=labels)
 
     def to_dict(self):
         result = {
@@ -375,10 +400,10 @@ def to_dict(self):
             "timestamp": int(self.timestamp * 1000000),  # microseconds
             "duration": self.duration * 1000,  # milliseconds
         }
-        if self.tags:
+        if self.labels:
             if self.context is None:
                 self.context = {}
-            self.context["tags"] = self.tags
+            self.context["tags"] = self.labels
         if self.context:
             result["context"] = self.context
         if self.frames:
@@ -491,7 +516,7 @@ def end_transaction(self, result=None, transaction_name=None):
 
 
 class capture_span(object):
-    __slots__ = ("name", "type", "subtype", "action", "extra", "skip_frames", "leaf", "tags")
+    __slots__ = ("name", "type", "subtype", "action", "extra", "skip_frames", "leaf", "labels")
 
     def __init__(
         self,
@@ -501,6 +526,7 @@ def __init__(
         skip_frames=0,
         leaf=False,
         tags=None,
+        labels=None,
         span_subtype=None,
         span_action=None,
     ):
@@ -511,7 +537,15 @@ def __init__(
         self.extra = extra
         self.skip_frames = skip_frames
         self.leaf = leaf
-        self.tags = tags
+        if tags and not labels:
+            warnings.warn(
+                'The tags argument to capture_span is deprecated, use "labels" instead',
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            labels = tags
+
+        self.labels = labels
 
     def __call__(self, func):
         self.name = self.name or get_name_from_func(func)
@@ -531,7 +565,7 @@ def __enter__(self):
                 self.type,
                 context=self.extra,
                 leaf=self.leaf,
-                tags=self.tags,
+                labels=self.labels,
                 span_subtype=self.subtype,
                 span_action=self.action,
             )
@@ -545,9 +579,24 @@ def __exit__(self, exc_type, exc_val, exc_tb):
                 logger.info("ended non-existing span %s of type %s", self.name, self.type)
 
 
+def label(**labels):
+    """
+    Labels current transaction. Keys should be strings, values can be strings, booleans,
+    or numerical values (int, float, Decimal)
+
+    :param labels: key/value map of labels
+    """
+    transaction = execution_context.get_transaction()
+    if not transaction:
+        error_logger.warning("Ignored labels %s. No transaction currently active.", ", ".join(labels.keys()))
+    else:
+        transaction.label(**labels)
+
+
+@deprecated("elasticapm.label")
 def tag(**tags):
     """
-    Tags current transaction. Both key and value of the tag should be strings.
+    Tags current transaction. Both key and value of the label should be strings.
     """
     transaction = execution_context.get_transaction()
     if not transaction:

elasticapm/utils/json_encoder.py

@@ -30,6 +30,7 @@
 
 
 import datetime
+import decimal
 import uuid
 
 try:
@@ -45,6 +46,7 @@ class BetterJSONEncoder(json.JSONEncoder):
         datetime.datetime: lambda obj: obj.strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
         uuid.UUID: lambda obj: obj.hex,
         bytes: lambda obj: obj.decode("utf-8", errors="replace"),
+        decimal.Decimal: lambda obj: float(obj),
     }
 
     def default(self, obj):