fix(trtllm): log deprecation notices so operators see them (cherry-pick #11694 to release/1.3.0)

components/src/dynamo/trtllm/args.py

@@ -16,7 +16,11 @@
     DynamoRuntimeConfig,
 )
 from dynamo.common.utils.runtime import parse_endpoint
-from dynamo.trtllm.backend_args import DynamoTrtllmArgGroup, DynamoTrtllmConfig
+from dynamo.trtllm.backend_args import (
+    DynamoTrtllmArgGroup,
+    DynamoTrtllmConfig,
+    _warn_deprecated,
+)
 from dynamo.trtllm.constants import DisaggregationMode, Modality
 from dynamo.trtllm.dynamic_flags import parse_dynamic_flags
 
@@ -88,26 +92,18 @@ def parse_args(argv: Optional[Sequence[str]] = None) -> Config:
         in ("--publish-events-and-metrics", "--no-publish-events-and-metrics")
         for a in cli_args
     ):
-        import warnings
-
-        warnings.warn(
+        _warn_deprecated(
             "--publish-events-and-metrics is deprecated; use --publish-kv-events. "
-            "The old flag stays as an alias for one release.",
-            DeprecationWarning,
-            stacklevel=2,
+            "The old flag stays as an alias for one release."
         )
     if (
         "DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS" in os.environ
         and "DYN_TRTLLM_PUBLISH_KV_EVENTS" not in os.environ
     ):
-        import warnings
-
-        warnings.warn(
+        _warn_deprecated(
             "DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS is deprecated; use "
             "DYN_TRTLLM_PUBLISH_KV_EVENTS. The old env var stays as an "
-            "alias for one release.",
-            DeprecationWarning,
-            stacklevel=2,
+            "alias for one release."
         )
         os.environ["DYN_TRTLLM_PUBLISH_KV_EVENTS"] = os.environ[
             "DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS"

components/src/dynamo/trtllm/tests/test_trtllm_unit.py

@@ -4,6 +4,7 @@
 """Unit tests for TRTLLM backend components."""
 
 import asyncio
+import os
 import re
 import warnings
 from pathlib import Path
@@ -116,6 +117,48 @@ def test_config_use_kv_events_derived_from_publish_events(monkeypatch):
     assert config_off.use_kv_events is False
 
 
+def test_deprecated_publish_events_flag_alias_maps_and_logs(monkeypatch, caplog):
+    """The deprecated --publish-events-and-metrics alias must still map to
+    publish_events_and_metrics AND surface its deprecation notice on the log
+    stream, which is visible under CPython's default warning filters (a bare
+    warnings.warn(DeprecationWarning) from library code is not)."""
+    monkeypatch.delenv("DYN_TRTLLM_PUBLISH_KV_EVENTS", raising=False)
+    monkeypatch.delenv("DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS", raising=False)
+    with caplog.at_level("WARNING"), pytest.warns(
+        DeprecationWarning, match="--publish-events-and-metrics is deprecated"
+    ):
+        config = parse_args(["--publish-events-and-metrics"])
+    assert config.publish_events_and_metrics is True
+    assert config.use_kv_events is True
+    assert any(
+        "--publish-events-and-metrics is deprecated" in r.message
+        for r in caplog.records
+    )
+
+
+def test_deprecated_publish_events_env_alias_maps_and_logs(monkeypatch, caplog):
+    """The deprecated DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS env var must still
+    map to the new env var AND surface its deprecation notice on the log
+    stream."""
+    # parse_args copies the deprecated env var into the new one via a direct
+    # os.environ write. Swap in a throwaway copy so monkeypatch restores the real
+    # environment on teardown and that write does not leak into later tests.
+    monkeypatch.setattr(os, "environ", os.environ.copy())
+    monkeypatch.delenv("DYN_TRTLLM_PUBLISH_KV_EVENTS", raising=False)
+    monkeypatch.setenv("DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS", "true")
+    with caplog.at_level("WARNING"), pytest.warns(
+        DeprecationWarning, match="DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS is deprecated"
+    ):
+        config = parse_args([])
+    assert config.publish_events_and_metrics is True
+    assert config.use_kv_events is True
+    assert os.environ["DYN_TRTLLM_PUBLISH_KV_EVENTS"] == "true"
+    assert any(
+        "DYN_TRTLLM_PUBLISH_EVENTS_AND_METRICS is deprecated" in r.message
+        for r in caplog.records
+    )
+
+
 @pytest.mark.asyncio
 async def test_init_llm_worker_rejects_invalid_kv_cache_config_override(monkeypatch):
     monkeypatch.delenv("DYN_TRTLLM_OVERRIDE_ENGINE_ARGS", raising=False)