chore(tracing): deprecate tracer.configure params

ddtrace/_trace/processor/__init__.py

@@ -302,7 +302,6 @@ def __init__(
         partial_flush_enabled: bool,
         partial_flush_min_spans: int,
         dd_processors: Optional[List[TraceProcessor]] = None,
-        user_processors: Optional[List[TraceProcessor]] = None,
     ):
         # Set partial flushing
         self.partial_flush_enabled = partial_flush_enabled
@@ -313,7 +312,7 @@ def __init__(
         )
         self.tags_processor = TraceTagsProcessor()
         self.dd_processors = dd_processors or []
-        self.user_processors = user_processors or []
+        self.user_processors: List[TraceProcessor] = []
         self.service_name_processor = ServiceNameProcessor()
         self.writer = create_trace_writer(response_callback=self._agent_response_callback)
         # Initialize the trace buffer and lock

ddtrace/_trace/tracer.py

@@ -60,6 +60,7 @@
 from ddtrace.settings._config import config
 from ddtrace.settings.asm import config as asm_config
 from ddtrace.settings.peer_service import _ps_config
+from ddtrace.vendor.debtcollector import deprecate
 from ddtrace.vendor.debtcollector.removals import remove
 from ddtrace.version import get_version
 
@@ -230,6 +231,14 @@ def deregister_on_start_span(self, func: Callable[[Span], None]) -> Callable[[Sp
         core.reset_listeners("trace.span_start", callback=func)
         return func
 
+    @property
+    def processors(self) -> List[TraceProcessor]:
+        return self._span_aggregator.user_processors
+
+    @processors.setter
+    def processors(self, value: List[TraceProcessor]):
+        self._span_aggregator.user_processors = value
+
     def sample(self, span):
         self._sampler.sample(span)
 
@@ -306,6 +315,7 @@ def configure(
         iast_enabled: Optional[bool] = None,
         apm_tracing_disabled: Optional[bool] = None,
         trace_processors: Optional[List[TraceProcessor]] = None,
+        apm_tracing_enabled: Optional[bool] = None,
     ) -> None:
         """Configure a Tracer.
 
@@ -314,9 +324,9 @@ def configure(
             doesn't need to be changed from the default value.
         :param bool appsec_enabled: Enables Application Security Monitoring (ASM) for the tracer.
         :param bool iast_enabled: Enables IAST support for the tracer
-        :param bool apm_tracing_disabled: When APM tracing is disabled ensures ASM support is still enabled.
-        :param List[TraceProcessor] trace_processors: This parameter sets TraceProcessor (ex: TraceFilters).
-           Trace processors are used to modify and filter traces based on certain criteria.
+        :param bool apm_tracing_disabled: Deprecated. Use `apm_tracing_enabled` instead.
+        :param bool apm_tracing_enabled: Enables/Disables the submission of traces to the Datadog Agent.
+        :param List[TraceProcessor] trace_processors: Deprecated. Use `tracer.processors` property instead.
         """
 
         if appsec_enabled is not None:
@@ -328,7 +338,15 @@ def configure(
             asm_config._iast_enabled = iast_enabled
 
         if apm_tracing_disabled is not None:
+            deprecate(
+                prefix="tracer.configure(apm_tracing_disabled=...) is deprecated",
+                message="Use tracer.configure(apm_tracing_enabled=...) instead.",
+                category=DDTraceDeprecationWarning,
+                removal_version="4.0.0",
+            )
             asm_config._apm_tracing_enabled = not apm_tracing_disabled
+        if apm_tracing_enabled is not None:
+            asm_config._apm_tracing_enabled = apm_tracing_enabled
 
         if asm_config._apm_opt_out:
             config._tracing_enabled = self.enabled = False
@@ -341,21 +359,33 @@ def configure(
         if compute_stats_enabled is not None:
             config._trace_compute_stats = compute_stats_enabled
 
+        if trace_processors is not None:
+            deprecate(
+                prefix="tracer.configure(trace_processors=...) is deprecated",
+                message="Use tracer.processors property instead.",
+                category=DDTraceDeprecationWarning,
+                removal_version="4.0.0",
+            )
+            self.processors = trace_processors
+
+        if context_provider is not None:
+            deprecate(
+                prefix="tracer.configure(context_provider=...) is deprecated",
+                message="Use tracer.context_provider property instead.",
+                category=DDTraceDeprecationWarning,
+                removal_version="4.0.0",
+            )
+            self.context_provider = context_provider
+
         if any(
             x is not None
             for x in [
-                trace_processors,
                 compute_stats_enabled,
                 appsec_enabled,
                 iast_enabled,
             ]
         ):
-            self._recreate(
-                trace_processors, compute_stats_enabled, asm_config._apm_opt_out, appsec_enabled, reset_buffer=False
-            )
-
-        if context_provider is not None:
-            self.context_provider = context_provider
+            self._recreate(compute_stats_enabled, asm_config._apm_opt_out, appsec_enabled, reset_buffer=False)
 
     def _generate_diagnostic_logs(self):
         if config._debug_mode or config._startup_logs_enabled:
@@ -383,7 +413,6 @@ def _child_after_fork(self):
 
     def _recreate(
         self,
-        trace_processors: Optional[List[TraceProcessor]] = None,
         compute_stats_enabled: Optional[bool] = None,
         apm_opt_out: Optional[bool] = None,
         appsec_enabled: Optional[bool] = None,
@@ -393,7 +422,6 @@ def _recreate(
         # Stop the writer.
         # This will stop the periodic thread in HTTPWriters, preventing memory leaks and unnecessary I/O.
         self._span_aggregator.reset(
-            user_processors=trace_processors,
             compute_stats=compute_stats_enabled,
             apm_opt_out=apm_opt_out,
             appsec_enabled=appsec_enabled,

ddtrace/contrib/internal/tornado/application.py

@@ -39,10 +39,8 @@ def tracer_config(__init__, app, args, kwargs):
     # TODO: Remove `FILTERS` from supported settings
     trace_processors = settings.get("settings", {}).get("FILTERS")
 
-    tracer.configure(
-        context_provider=context_provider,
-        trace_processors=trace_processors,
-    )
+    tracer.processors = trace_processors
+    tracer.context_provider = context_provider
     tracer._wrap_executor = decorators.wrap_executor
     # TODO: Remove `enabled`, `hostname` and `port` settings in v4.0
     # Tracer should be configured via environment variables

ddtrace/internal/ci_visibility/recorder.py

@@ -656,7 +656,7 @@ def _start_service(self) -> None:
         tracer_filters = self.tracer._span_aggregator.user_processors
         if not any(isinstance(tracer_filter, TraceCiVisibilityFilter) for tracer_filter in tracer_filters):
             tracer_filters += [TraceCiVisibilityFilter(self._tags, self._service)]  # type: ignore[arg-type]
-            self.tracer.configure(trace_processors=tracer_filters)
+            self.tracer.processors = tracer_filters
 
         if asbool(os.getenv("DD_CIVISIBILITY_USE_BETA_WRITER")):
             self._set_global_span_forwarder(CIVisibilitySpanForwarder(self.tracer))
@@ -734,7 +734,7 @@ def _set_global_span_forwarder(self, span_forwarder: Optional[TraceFilter]) -> N
         tracer_filters = [tf for tf in tracer_filters if not isinstance(tf, CIVisibilitySpanForwarder)]
         if span_forwarder:
             tracer_filters.append(span_forwarder)
-        ddtrace.tracer.configure(trace_processors=tracer_filters)
+        ddtrace.tracer.processors = tracer_filters
 
     @classmethod
     def set_codeowners_of(cls, location, span=None):

releasenotes/notes/update-tracer-configure-190952ff70420bda.yaml

@@ -0,0 +1,9 @@
+---
+deprecations:
+  - |
+    tracing: The following tracer.configure() parameters have been deprecated:
+    - `trace_processors` - use `tracer.processors` property instead
+    - `apm_tracing_disabled` - use `tracer.configure(apm_tracing_enabled=...)` instead  
+    - `context_provider` - use `tracer.context_provider` property instead
+
+    These will be removed in ddtrace 4.0.0. Other configure() parameters remain supported.

tests/appsec/appsec/test_asm_standalone.py

@@ -11,7 +11,7 @@
 
 @pytest.fixture(
     params=[
-        {"DD_APPSEC_SCA_ENABLED": sca, "iast_enabled": iast, "appsec_enabled": appsec, "apm_tracing_disabled": apm}
+        {"DD_APPSEC_SCA_ENABLED": sca, "iast_enabled": iast, "appsec_enabled": appsec, "apm_tracing_enabled": apm}
         for sca in ["1", "0"]
         for iast in [True, False]
         for appsec in [True, False]
@@ -37,7 +37,7 @@ def tracer_appsec_standalone(request, tracer):
 
     # Reset tracer configuration
     ddtrace.config._reset()
-    tracer.configure(appsec_enabled=False, apm_tracing_disabled=False, iast_enabled=False)
+    tracer.configure(appsec_enabled=False, apm_tracing_enabled=True, iast_enabled=False)
 
 
 def test_appsec_standalone_apm_enabled_metric(tracer_appsec_standalone):
@@ -46,7 +46,7 @@ def test_appsec_standalone_apm_enabled_metric(tracer_appsec_standalone):
     with tracer.trace("test", span_type=SpanTypes.WEB) as span:
         set_http_meta(span, {}, raw_uri="http://example.com/.git", status_code="404")
 
-    if args.get("apm_tracing_disabled", None) and (
+    if args.get("apm_tracing_enabled", None) and (
         args.get("appsec_enabled", None)
         or args.get("iast_enabled", None)
         or args.get("DD_APPSEC_SCA_ENABLED", "0") == "1"

tests/appsec/contrib_appsec/django_app/settings.py

@@ -6,7 +6,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 
 
 ALLOWED_HOSTS = [

tests/appsec/contrib_appsec/flask_app/app.py

@@ -15,7 +15,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 cur_dir = os.path.dirname(os.path.realpath(__file__))
 tmpl_path = os.path.join(cur_dir, "test_templates")
 app = Flask(__name__, template_folder=tmpl_path)

tests/appsec/integrations/django_tests/django_app/settings.py

@@ -6,7 +6,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 
 ALLOWED_HOSTS = [
     "testserver",

tests/contrib/django/django_app/settings.py

@@ -6,7 +6,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 
 
 ALLOWED_HOSTS = [

tests/contrib/flask/app.py

@@ -12,7 +12,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 cur_dir = os.path.dirname(os.path.realpath(__file__))
 tmpl_path = os.path.join(cur_dir, "test_templates")
 app = Flask(__name__, template_folder=tmpl_path)

tests/contrib/gunicorn/wsgi_mw_app.py

@@ -18,7 +18,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 
 
 def aggressive_shutdown():

tests/contrib/kafka/test_kafka.py

@@ -110,7 +110,7 @@ def should_filter_empty_polls():
 def tracer(should_filter_empty_polls):
     patch()
     if should_filter_empty_polls:
-        ddtracer.configure(trace_processors=[KafkaConsumerPollFilter()])
+        ddtracer.processors = [KafkaConsumerPollFilter()]
     # disable backoff because it makes these tests less reliable
     if not config._trace_writer_native:
         previous_backoff = ddtracer._span_aggregator.writer._send_payload_with_backoff
@@ -554,7 +554,7 @@ def _generate_in_subprocess(random_topic):
 
     PAYLOAD = bytes("hueh hueh hueh", encoding="utf-8")
 
-    ddtrace.tracer.configure(trace_processors=[KafkaConsumerPollFilter()])
+    ddtrace.tracer.processors = [KafkaConsumerPollFilter()]
     # disable backoff because it makes these tests less reliable
     if not config._trace_writer_native:
         ddtrace.tracer._span_aggregator.writer._send_payload_with_backoff = (

tests/contrib/openai/conftest.py

@@ -137,7 +137,7 @@ def patch_openai(ddtrace_global_config, ddtrace_config_openai, openai_api_key, o
 @pytest.fixture
 def snapshot_tracer(openai, patch_openai):
     pin = Pin.get_from(openai)
-    pin.tracer.configure(trace_processors=[FilterOrg()])
+    pin.tracer.processors = [FilterOrg()]
 
     yield pin.tracer
 
@@ -147,7 +147,7 @@ def mock_tracer(ddtrace_global_config, openai, patch_openai):
     pin = Pin.get_from(openai)
     mock_tracer = DummyTracer(writer=DummyWriter(trace_flush_enabled=False))
     pin._override(openai, tracer=mock_tracer)
-    pin.tracer.configure(trace_processors=[FilterOrg()])
+    pin.tracer.processors = [FilterOrg()]
 
     if ddtrace_global_config.get("_llmobs_enabled", False):
         # Have to disable and re-enable LLMObs to use to mock tracer.

tests/contrib/openai/test_openai_v1.py

@@ -855,7 +855,7 @@ def test_integration_sync(openai_api_key, ddtrace_run_python_code_in_subprocess)
 from tests.contrib.openai.conftest import FilterOrg
 from tests.contrib.openai.test_openai_v1 import get_openai_vcr
 pin = ddtrace.trace.Pin.get_from(openai)
-pin.tracer.configure(trace_processors=[FilterOrg()])
+pin.tracer.processors = [FilterOrg()]
 with get_openai_vcr(subdirectory_name="v1").use_cassette("completion.yaml"):
     client = openai.OpenAI()
     resp = client.completions.create(
@@ -896,7 +896,7 @@ def test_integration_async(openai_api_key, ddtrace_run_python_code_in_subprocess
 from tests.contrib.openai.conftest import FilterOrg
 from tests.contrib.openai.test_openai_v1 import get_openai_vcr
 pin = ddtrace.trace.Pin.get_from(openai)
-pin.tracer.configure(trace_processors=[FilterOrg()])
+pin.tracer.processors = [FilterOrg()]
 async def task():
     with get_openai_vcr(subdirectory_name="v1").use_cassette("completion.yaml"):
         client = openai.AsyncOpenAI()
@@ -1099,7 +1099,7 @@ def test_integration_service_name(openai_api_key, ddtrace_run_python_code_in_sub
 from tests.contrib.openai.conftest import FilterOrg
 from tests.contrib.openai.test_openai_v1 import get_openai_vcr
 pin = ddtrace.trace.Pin.get_from(openai)
-pin.tracer.configure(trace_processors=[FilterOrg()])
+pin.tracer.processors = [FilterOrg()]
 with get_openai_vcr(subdirectory_name="v1").use_cassette("completion.yaml"):
     client = openai.OpenAI()
     resp = client.completions.create(model="ada", prompt="hello world")

tests/contrib/pyramid/app/app.py

@@ -7,7 +7,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 
 
 def hello_world(request):

tests/contrib/pyramid/pserve_app/app/__init__.py

@@ -13,7 +13,7 @@ def process_trace(self, trace):
         return None if trace and trace[0].trace_id == 1 else trace
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 
 
 def tracer_shutdown(request):

tests/contrib/sanic/run_server.py

@@ -9,7 +9,7 @@
 from tests.webclient import PingFilter
 
 
-tracer.configure(trace_processors=[PingFilter()])
+tracer.processors = [PingFilter()]
 
 
 app = Sanic("test_sanic_server")

tests/contrib/urllib3/test_urllib3.py

@@ -536,7 +536,7 @@ def test_distributed_tracing_apm_opt_out_true(self):
         config.urllib3["distributed_tracing"] = True
         self.tracer.enabled = False
         # Ensure the ASM SpanProcessor is set
-        self.tracer.configure(apm_tracing_disabled=True, appsec_enabled=True)
+        self.tracer.configure(apm_tracing_enabled=False, appsec_enabled=True)
         assert asm_config._apm_opt_out
         with mock.patch(
             "urllib3.connectionpool.HTTPConnectionPool._make_request", side_effect=ValueError
@@ -585,7 +585,7 @@ def test_distributed_tracing_apm_opt_out_false(self):
         """Test with distributed tracing disabled does not propagate the headers"""
         config.urllib3["distributed_tracing"] = True
         # Ensure the ASM SpanProcessor is set.
-        self.tracer.configure(apm_tracing_disabled=False, appsec_enabled=True)
+        self.tracer.configure(apm_tracing_enabled=True, appsec_enabled=True)
         self.tracer.enabled = False
         assert not asm_config._apm_opt_out
         with mock.patch(

tests/integration/test_integration_snapshots.py

@@ -91,7 +91,7 @@ def process_trace(self, trace):
                 s.set_tag(self.key, self.value)
             return trace
 
-    tracer.configure(trace_processors=[FilterMutate("boop", "beep")])
+    tracer.processors = [FilterMutate("boop", "beep")]
 
     with tracer.trace("root"):
         with tracer.trace("child"):

tests/integration/test_priority_sampling.py

@@ -173,7 +173,7 @@ def process_trace(self, trace):
                     return None
             return trace
 
-    t.configure(trace_processors=[CustomFilter()])  # Triggers AgentWriter recreate
+    t.processors = [CustomFilter()]  # Triggers AgentWriter recreate
     assert (
         t._span_aggregator.sampling_processor.sampler._agent_based_samplers == agent_based_samplers
     ), f"Expected agent sampling rules to be set to {agent_based_samplers}, "

tests/opentelemetry/flask_app.py

@@ -10,7 +10,7 @@
 
 opentelemetry.trace.set_tracer_provider(TracerProvider())
 
-ddtrace.tracer.configure(trace_processors=[PingFilter()])
+ddtrace.tracer.processors = [PingFilter()]
 app = flask.Flask(__name__)