chore: deprecate constants (DataDog#3261)

Deprecate constants that are intended for internal usage only.

Co-authored-by: Brett Langdon <[email protected]>

ddtrace/constants.py

@@ -1,4 +1,7 @@
-FILTERS_KEY = "FILTERS"
+from ddtrace.internal.compat import ensure_pep562
+from ddtrace.vendor import debtcollector
+
+
 SAMPLE_RATE_METRIC_KEY = "_sample_rate"
 SAMPLING_PRIORITY_KEY = "_sampling_priority_v1"
 ANALYTICS_SAMPLE_RATE_KEY = "_dd1.sr.eausr"
@@ -15,12 +18,10 @@
 SPAN_MEASURED_KEY = "_dd.measured"
 KEEP_SPANS_RATE_KEY = "_dd.tracer_kr"
 
-NUMERIC_TAGS = (ANALYTICS_SAMPLE_RATE_KEY,)
 
 MANUAL_DROP_KEY = "manual.drop"
 MANUAL_KEEP_KEY = "manual.keep"
 
-LOG_SPAN_KEY = "__datadog_log_span"
 
 ERROR_MSG = "error.msg"  # a string representing the error message
 ERROR_TYPE = "error.type"  # a string representing the type of the error
@@ -36,3 +37,33 @@
 AUTO_KEEP = 1
 # Use this to explicitly inform the backend that a trace should be kept and stored.
 USER_KEEP = 2
+
+
+_DEPRECATED = {
+    # TODO: Removal of this attribute does not require the addition of a
+    # constant as it has only a single use for passing trace filters in the
+    # settings to the tracer.
+    "FILTERS_KEY": "FILTERS",
+    # TODO: Moved to other modules but cannot reference here due to circular imports
+    # ddtrace.contrib.logging.patch._LOG_SPAN_KEY
+    # ddtrace.span._NUMERIC_TAGS
+    "NUMERIC_TAGS": (ANALYTICS_SAMPLE_RATE_KEY,),
+    "LOG_SPAN_KEY": "__datadog_log_span",
+}
+
+
+def __getattr__(name):
+    if name in _DEPRECATED:
+        debtcollector.deprecate(
+            ("%s.%s is deprecated" % (__name__, name)),
+            removal_version="1.0.0",
+        )
+        return _DEPRECATED[name]
+
+    if name in globals():
+        return globals()[name]
+
+    raise AttributeError("%s has no attribute %s", __name__, name)
+
+
+ensure_pep562(__name__)

ddtrace/contrib/logging/patch.py

@@ -16,6 +16,7 @@
 RECORD_ATTR_SERVICE = "dd.service"
 RECORD_ATTR_VALUE_ZERO = "0"
 RECORD_ATTR_VALUE_EMPTY = ""
+_LOG_SPAN_KEY = "__datadog_log_span"
 
 ddtrace.config._add(
     "logging",
@@ -57,7 +58,7 @@ def _w_makeRecord(func, instance, args, kwargs):
 
     # logs from internal logger may explicitly pass the current span to
     # avoid deadlocks in getting the current span while already in locked code.
-    span_from_log = getattr(record, ddtrace.constants.LOG_SPAN_KEY, None)
+    span_from_log = getattr(record, _LOG_SPAN_KEY, None)
     if isinstance(span_from_log, ddtrace.Span):
         span = span_from_log
     else:

ddtrace/opentracer/tracer.py

@@ -13,7 +13,6 @@
 import ddtrace
 from ddtrace import Span as DatadogSpan
 from ddtrace import Tracer as DatadogTracer
-from ddtrace.constants import FILTERS_KEY
 from ddtrace.context import Context as DatadogContext
 from ddtrace.internal.utils.config import get_application_name
 from ddtrace.settings import ConfigException
@@ -40,7 +39,7 @@
     keys.PRIORITY_SAMPLING: None,
     keys.UDS_PATH: None,
     keys.SETTINGS: {
-        FILTERS_KEY: [],
+        "FILTERS": [],
     },
 }  # type: Dict[str, Any]
 

ddtrace/span.py

@@ -14,12 +14,12 @@
 import six
 
 from . import config
+from .constants import ANALYTICS_SAMPLE_RATE_KEY
 from .constants import ERROR_MSG
 from .constants import ERROR_STACK
 from .constants import ERROR_TYPE
 from .constants import MANUAL_DROP_KEY
 from .constants import MANUAL_KEEP_KEY
-from .constants import NUMERIC_TAGS
 from .constants import SERVICE_KEY
 from .constants import SERVICE_VERSION_KEY
 from .constants import SPAN_MEASURED_KEY
@@ -48,6 +48,7 @@
 if TYPE_CHECKING:
     from .tracer import Tracer
 
+_NUMERIC_TAGS = (ANALYTICS_SAMPLE_RATE_KEY,)
 
 _TagNameType = Union[Text, bytes]
 _MetaDictType = Dict[_TagNameType, Text]
@@ -306,7 +307,7 @@ def set_tag(self, key, value=None):
             return
 
         # Key should explicitly be converted to a float if needed
-        elif key in NUMERIC_TAGS:
+        elif key in _NUMERIC_TAGS:
             if value is None:
                 log.debug("ignoring not number metric %s:%s", key, value)
                 return

ddtrace/tracer.py

@@ -25,7 +25,6 @@
 from .constants import AUTO_KEEP
 from .constants import AUTO_REJECT
 from .constants import ENV_KEY
-from .constants import FILTERS_KEY
 from .constants import HOSTNAME_KEY
 from .constants import PID
 from .constants import SAMPLE_RATE_METRIC_KEY
@@ -327,9 +326,7 @@ def configure(
             self.enabled = enabled
 
         if settings is not None:
-            filters = settings.get(FILTERS_KEY)
-            if filters is not None:
-                self._filters = filters
+            self._filters = settings.get("FILTERS") or self._filters
 
         if partial_flush_enabled is not None:
             self._partial_flush_enabled = partial_flush_enabled

releasenotes/notes/deprecate-constants-e6ea6706d38b186f.yaml

@@ -0,0 +1,8 @@
+---
+deprecations:
+  - |
+    ``ddtrace.constants.FILTERS_KEY`` is deprecated. Use ``settings={"FILTERS": ...}`` instead when calling ``tracer.configure``.
+  - |
+    ``ddtrace.constants.NUMERIC_TAGS`` is deprecated.
+  - |
+    ``ddtrace.constants.LOG_SPAN_KEY`` is deprecated.

tests/tracer/test_constants.py

@@ -0,0 +1,49 @@
+import warnings
+
+import pytest
+
+
+def test_deprecated():
+    import ddtrace
+
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+
+        assert ddtrace.constants.FILTERS_KEY
+
+        (w,) = ws
+        assert issubclass(w.category, DeprecationWarning)
+        assert "ddtrace.constants.FILTERS_KEY is deprecated and will be removed in version '1.0.0'" == str(w.message)
+
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+
+        assert ddtrace.constants.NUMERIC_TAGS
+
+        (w,) = ws
+        assert issubclass(w.category, DeprecationWarning)
+        assert "ddtrace.constants.NUMERIC_TAGS is deprecated and will be removed in version '1.0.0'" == str(w.message)
+
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+
+        assert ddtrace.constants.LOG_SPAN_KEY
+
+        (w,) = ws
+        assert issubclass(w.category, DeprecationWarning)
+        assert "ddtrace.constants.LOG_SPAN_KEY is deprecated and will be removed in version '1.0.0'" == str(w.message)
+
+
+def test_not_deprecated():
+    import ddtrace
+
+    with warnings.catch_warnings(record=True) as ws:
+        warnings.simplefilter("always")
+
+        assert ddtrace.constants.ENV_KEY
+        assert len(ws) == 0
+
+
+def test_invalid():
+    with pytest.raises(ImportError):
+        from ddtrace.constants import INVALID_CONSTANT  # noqa