fix(curl): enforce DD_TRACE_SPANS_LIMIT for curl_multi_exec parent spans (APMS-19944) (#4030)

* fix(curl): enforce DD_TRACE_SPANS_LIMIT for curl_multi_exec parent spans (APMS-19944)

The curl_multi_exec integration opens its parent span via the user-facing
DDTrace\start_span(), which intentionally bypasses DD_TRACE_SPANS_LIMIT
(see #3691). Distributed-header injection then flags that span NOT_DROPPABLE,
so the post-hook's try_drop_span() can never reclaim it. In long-running CLI
workloads that repeatedly call curl_multi_exec (e.g. AWS SDK SQS batches),
one un-droppable span accumulates per call, growing memory 1:1 with calls
until OOM.

Skip creating the parent span when the tracer is already limited. Distributed
tracing headers are still injected by the C handler against the active span,
so propagation is preserved, and the child request spans are already limited.

Fixes: APMS-19944

* test(curl): drop flaky is_limited assertion from span-limit test

dd_trace_tracer_is_limited() reflects the open+closed span counters at the
moment of the call, which depends on end-of-run flush/cleanup timing and
varies across CI environments and PHP versions (7.3/7.4/8.2-ASAN all reported
bool(false) at script end). The span-count assertion (BOUNDED) is the real
regression guard: with the fix the retained curl_multi_exec spans stay capped
near DD_TRACE_SPANS_LIMIT, without it they scale 1:1 with iterations. Bump to
100 iterations for a clearer margin and drop the fragile check.

* test(curl): remove comments from span-limit test

* fix(curl): check span limit at top of curl_multi_exec hook

Address review: move the ddtrace_tracer_is_limited() guard to the start of
the begin hook so the limited path returns immediately, skipping the args
lookup and ObjectKVStore reuse check. Spans for a multi-op are only created
on the first curl_multi_exec call, so a new handle has nothing to reuse when
limited; the boundary case (parent created just before the limit) is still
finalized by CurlSpanInfo::__destruct().

Author: Leiyks

src/DDTrace/Integrations/Curl/CurlIntegration.php

@@ -100,7 +100,7 @@ public static function init(): int
         ]);
 
         \DDTrace\install_hook('curl_multi_exec', static function (HookData $hook) {
-            if (\count($hook->args) < 2) {
+            if (\count($hook->args) < 2 || \dd_trace_tracer_is_limited()) {
                 return;
             }
             $data = null;

tests/ext/integrations/curl/curl_multi_exec_span_limit.phpt

@@ -0,0 +1,42 @@
+--TEST--
+curl_multi_exec parent spans honor DD_TRACE_SPANS_LIMIT (APMS-19944)
+--SKIPIF--
+<?php if (!extension_loaded('curl')) die('skip: curl extension required'); ?>
+<?php if (!getenv('HTTPBIN_HOSTNAME')) die('skip: HTTPBIN_HOSTNAME env var required'); ?>
+--ENV--
+DD_TRACE_AUTO_FLUSH_ENABLED=0
+DD_TRACE_GENERATE_ROOT_SPAN=1
+DD_TRACE_SPANS_LIMIT=20
+DD_TRACE_LOG_LEVEL=error
+--FILE--
+<?php
+$port = getenv('HTTPBIN_PORT') ?: '80';
+$url = 'http://' . getenv('HTTPBIN_HOSTNAME') . ':' . $port . '/';
+
+$iterations = 100;
+for ($i = 0; $i < $iterations; $i++) {
+    $ch = curl_init($url);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+
+    $mh = curl_multi_init();
+    curl_multi_add_handle($mh, $ch);
+    do {
+        $status = curl_multi_exec($mh, $active);
+        curl_multi_select($mh);
+    } while ($active > 0 && $status === CURLM_OK);
+    curl_multi_remove_handle($mh, $ch);
+    curl_multi_close($mh);
+}
+
+$spans = dd_trace_serialize_closed_spans();
+$multiCount = 0;
+foreach ($spans as $span) {
+    if (($span['name'] ?? '') === 'curl_multi_exec') {
+        $multiCount++;
+    }
+}
+
+echo ($multiCount <= $iterations / 2 ? 'BOUNDED' : 'LEAK') . "\n";
+?>
+--EXPECT--
+BOUNDED