Remove tags (deprecated) + Update docs for 6.x (#1034)

* Update docs for 6.x

* Remove tags (deprecated) + review suggestions

Author: basepi

CHANGELOG.asciidoc

@@ -30,28 +30,27 @@ endif::[]
 //===== Bug fixes
 //
 
-[float]
-=== Unreleased
+[[release-notes-6.x]]
+=== Python Agent version 6.x
+
+
+[[release-notes-6.0.0]]
+==== v6.0.0
 
-// Unreleased changes go here
-// When the next release happens, nest these changes under the "Python Agent version 5.x" heading
 [float]
 ===== Breaking changes
 
 * Python 2.7 and 3.5 support has been deprecated. The Python agent now requires Python 3.6+ {pull}1021[#1021]
 * No longer collecting body for `elasticsearch-py` `update` and `delete_by_query` {pull}1013[#1013]
 * Align `sanitize_field_names` config with the
   https://github.com/elastic/apm/blob/3fa78e2a1eeea81c73c2e16e96dbf6b2e79f3c64/specs/agents/sanitization.md[cross-agent spec].
-  If you are using a non-default `sanitize_field_names`, surrounding each of your entries with stars (i.e.
-  `\*secret\*`) will retain the old behavior. {pull}982[#982]
+  If you are using a non-default `sanitize_field_names`, surrounding each of your entries with stars (e.g.
+  `*secret*`) will retain the old behavior. {pull}982[#982]
 * Remove credit card sanitization for field values. This improves performance, and the security value of this check was
   dubious anyway. {pull}982[#982]
 * Remove HTTP querystring sanitization. This improves performance, and is meant to standardize behavior across the
   agents, as defined in https://github.com/elastic/apm/pull/334. {pull}982[#982]
-
-[float]
-===== Features
-
+* Remove `elasticapm.tag()` (deprecated since 5.0.0) {pull}1034[#1034]
 
 [float]
 ===== Bug fixes

docs/upgrading.asciidoc

@@ -25,8 +25,27 @@ The table below is a simplified description of this policy.
 |3.x |2020-01-20 |4.0
 |4.x |2020-05-14 |5.0
 |5.x |2021-02-05 |6.0
+|6.x |2022-08-01 |7.0
 |====
 
+[[upgrading-6.x]]
+=== Upgrading to version 6 of the agent
+
+==== Python 2 no longer supported
+
+Please upgrade to Python 3.6+ to continue to receive regular updates.
+
+==== `SANITIZE_FIELD_NAMES` changes
+
+If you are using a non-default `sanitize_field_names` config, please note
+that your entries must be surrounded with stars (e.g. `*secret*`) in order to
+maintain previous behavior.
+
+==== Tags removed (in favor of labels)
+
+Tags were deprecated in the 5.x release (in favor of labels). They have now been
+removed.
+
 [[upgrading-5.x]]
 === Upgrading to version 5 of the agent
 
@@ -42,7 +61,7 @@ we renamed "tags" to "labels", and introduced limited support for typed labels.
 While tag values were only allowed to be strings, label values can be strings, booleans, or numerical.
 
 To benefit from this change, ensure that you run at least *APM Server 6.7*, and use `elasticapm.label()` instead of `elasticapm.tag()`.
-The `tag()` API will continue to work as before, but emit a `DeprecationWarning`. It will be removed in 6.0 of the agent. 
+The `tag()` API will continue to work as before, but emit a `DeprecationWarning`. It will be removed in 6.0 of the agent.
 
 [[upgrading-4.x]]
 === Upgrading to version 4 of the agent

elasticapm/__init__.py

@@ -45,7 +45,6 @@
     set_transaction_outcome,
     set_transaction_result,
     set_user_context,
-    tag,
 )
 from elasticapm.utils.disttracing import trace_parent_from_headers, trace_parent_from_string  # noqa: F401
 

elasticapm/traces.py

@@ -34,19 +34,17 @@
 import threading
 import time
 import timeit
-import warnings
 from collections import defaultdict
 
 from elasticapm.conf import constants
 from elasticapm.conf.constants import LABEL_RE, 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
 from elasticapm.utils.logging import get_logger
 
-__all__ = ("capture_span", "tag", "label", "set_transaction_name", "set_custom_context", "set_user_context")
+__all__ = ("capture_span", "label", "set_transaction_name", "set_custom_context", "set_user_context")
 
 error_logger = get_logger("elasticapm.errors")
 logger = get_logger("elasticapm.traces")
@@ -116,23 +114,6 @@ def label(self, **labels):
         labels = encoding.enforce_label_format(labels)
         self.labels.update(labels)
 
-    @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.labels[LABEL_RE.sub("_", compat.text_type(key))] = encoding.keyword_field(compat.text_type(tags[key]))
-
     def set_success(self):
         self.outcome = "success"
 
@@ -666,7 +647,6 @@ def __init__(
         extra=None,
         skip_frames=0,
         leaf=False,
-        tags=None,
         labels=None,
         span_subtype=None,
         span_action=None,
@@ -681,14 +661,6 @@ def __init__(
         self.extra = extra
         self.skip_frames = skip_frames
         self.leaf = leaf
-        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
         self.start = start
         self.duration = duration
@@ -750,18 +722,6 @@ def label(**labels):
         transaction.label(**labels)
 
 
-@deprecated("elasticapm.label")
-def tag(**tags):
-    """
-    Tags current transaction. Both key and value of the label should be strings.
-    """
-    transaction = execution_context.get_transaction()
-    if not transaction:
-        error_logger.warning("Ignored tags %s. No transaction currently active.", ", ".join(tags.keys()))
-    else:
-        transaction.tag(**tags)
-
-
 def set_transaction_name(name, override=True):
     """
     Sets the name of the transaction

tests/client/client_tests.py

@@ -699,7 +699,7 @@ def test_transaction_keyword_truncation(elasticapm_client):
     assert len(expected) == KEYWORD_MAX_LENGTH
     assert expected[-1] != "x"
     elasticapm_client.begin_transaction(too_long)
-    elasticapm.tag(val=too_long)
+    elasticapm.label(val=too_long)
     elasticapm.set_user_context(username=too_long, email=too_long, user_id=too_long)
     with elasticapm.capture_span(name=too_long, span_type=too_long):
         pass

tests/client/exception_tests.py

@@ -304,7 +304,7 @@ def test_transaction_data_is_attached_to_errors_exc_handled_outside_span(elastic
 
 def test_transaction_context_is_used_in_errors(elasticapm_client):
     elasticapm_client.begin_transaction("test")
-    elasticapm.tag(foo="baz")
+    elasticapm.label(foo="baz")
     elasticapm.set_custom_context({"a": "b"})
     elasticapm.set_user_context(username="foo", email="foo@example.com", user_id=42)
     elasticapm_client.capture_message("x", custom={"foo": "bar"})

tests/instrumentation/transactions_store_tests.py

@@ -336,73 +336,6 @@ def test_labels_dedot(elasticapm_client):
     assert transactions[0]["context"]["tags"] == {"d_o_t": "dot", "s_t_a_r": "star", "q_u_o_t_e": "quote"}
 
 
-### TESTING DEPRECATED TAGGING START ###
-
-
-def test_tagging_is_deprecated(elasticapm_client):
-    elasticapm_client.begin_transaction("test")
-    with pytest.warns(DeprecationWarning, match="Call to deprecated function tag. Use elasticapm.label instead"):
-        elasticapm.tag(foo="bar")
-    elasticapm_client.end_transaction("test", "OK")
-    transactions = elasticapm_client.events[TRANSACTION]
-
-    assert transactions[0]["context"]["tags"] == {"foo": "bar"}
-
-
-def test_tag_transaction():
-    requests_store = Tracer(lambda: [], lambda: [], lambda *args: None, Config(), None)
-    transaction = requests_store.begin_transaction("test")
-    elasticapm.tag(foo="bar")
-    transaction.tag(baz="bazzinga")
-    requests_store.end_transaction(200, "test")
-
-    assert transaction.labels == {"foo": "bar", "baz": "bazzinga"}
-    transaction_dict = transaction.to_dict()
-    assert transaction_dict["context"]["tags"] == {"foo": "bar", "baz": "bazzinga"}
-
-
-def test_tag_while_no_transaction(caplog):
-    with caplog.at_level(logging.WARNING, "elasticapm.errors"):
-        elasticapm.tag(foo="bar")
-    record = caplog.records[0]
-    assert record.levelno == logging.WARNING
-    assert "foo" in record.args
-
-
-def test_tag_with_non_string_value():
-    requests_store = Tracer(lambda: [], lambda: [], lambda *args: None, config=Config(), agent=None)
-    t = requests_store.begin_transaction("test")
-    elasticapm.tag(foo=1)
-    requests_store.end_transaction(200, "test")
-    assert t.labels == {"foo": "1"}
-
-
-def test_tags_merge(elasticapm_client):
-    elasticapm_client.begin_transaction("test")
-    elasticapm.tag(foo=1, bar="baz")
-    elasticapm.tag(bar=3, boo="biz")
-    elasticapm_client.end_transaction("test", "OK")
-    transactions = elasticapm_client.events[TRANSACTION]
-
-    assert transactions[0]["context"]["tags"] == {"foo": "1", "bar": "3", "boo": "biz"}
-
-
-def test_tags_dedot(elasticapm_client):
-    elasticapm_client.begin_transaction("test")
-    elasticapm.tag(**{"d.o.t": "dot"})
-    elasticapm.tag(**{"s*t*a*r": "star"})
-    elasticapm.tag(**{'q"u"o"t"e': "quote"})
-
-    elasticapm_client.end_transaction("test_name", 200)
-
-    transactions = elasticapm_client.events[TRANSACTION]
-
-    assert transactions[0]["context"]["tags"] == {"d_o_t": "dot", "s_t_a_r": "star", "q_u_o_t_e": "quote"}
-
-
-### TESTING DEPRECATED TAGGING END ###
-
-
 def test_dedot_is_not_run_when_unsampled(elasticapm_client):
     for sampled in (True, False):
         t = elasticapm_client.begin_transaction("test")
@@ -542,20 +475,12 @@ def test_dotted_span_type_conversion(elasticapm_client):
 def test_span_labelling(elasticapm_client):
     elasticapm_client.begin_transaction("test")
     with elasticapm.capture_span("test", labels={"foo": "bar", "ba.z": "baz.zinga"}) as span:
-        span.tag(lorem="ipsum")
+        span.label(lorem="ipsum")
     elasticapm_client.end_transaction("test", "OK")
     span = elasticapm_client.events[SPAN][0]
     assert span["context"]["tags"] == {"foo": "bar", "ba_z": "baz.zinga", "lorem": "ipsum"}
 
 
-def test_span_tagging_raises_deprecation_warning(elasticapm_client):
-    elasticapm_client.begin_transaction("test")
-    with pytest.warns(DeprecationWarning, match="The tags argument to capture_span is deprecated"):
-        with elasticapm.capture_span("test", tags={"foo": "bar", "ba.z": "baz.zinga"}) as span:
-            span.tag(lorem="ipsum")
-    elasticapm_client.end_transaction("test", "OK")
-
-
 def test_span_sync(elasticapm_client):
     elasticapm_client.begin_transaction("test")
     with capture_span("foo", "type", sync=True):