Add support for customizing config for A365 (#98)

* Add support for customizing config for A365

* Fix lint

Author: rads-1996

MIGRATION_A365.md

@@ -257,6 +257,10 @@ use_microsoft_opentelemetry(
     a365_suppress_invoke_agent_input=True,
     a365_enable_observability_exporter=True,
     a365_observability_scope_override="api://<app-id>/.default",
+    a365_max_queue_size=4096,
+    a365_scheduled_delay_ms=2000,
+    a365_exporter_timeout_ms=15000,
+    a365_max_export_batch_size=256,
 )
 ```
 
@@ -275,6 +279,10 @@ use_microsoft_opentelemetry(
 | `cluster_category` | `a365_cluster_category` kwarg or `A365_CLUSTER_CATEGORY` env var |
 | `exporter_options` | Individual kwargs or env vars (see below) |
 | `suppress_invoke_agent_input` | `a365_suppress_invoke_agent_input` kwarg or `A365_SUPPRESS_INVOKE_AGENT_INPUT` env var |
+| `exporter_options.max_queue_size` | `a365_max_queue_size` kwarg |
+| `exporter_options.scheduled_delay_ms` | `a365_scheduled_delay_ms` kwarg |
+| `exporter_options.exporter_timeout_ms` | `a365_exporter_timeout_ms` kwarg |
+| `exporter_options.max_export_batch_size` | `a365_max_export_batch_size` kwarg |
 | _(env var only previously)_ `ENABLE_A365_OBSERVABILITY_EXPORTER` | `a365_enable_observability_exporter` kwarg or `ENABLE_A365_OBSERVABILITY_EXPORTER` env var |
 | _(env var only previously)_ `A365_OBSERVABILITY_SCOPE_OVERRIDE` | `a365_observability_scope_override` kwarg or `A365_OBSERVABILITY_SCOPE_OVERRIDE` env var |
 

README.md

@@ -110,6 +110,10 @@ See the [A365 guide](docs/A365_DOCUMENTATION.md) for A365-specific configuration
 | `a365_suppress_invoke_agent_input` | `bool` | `False` | Strip input messages from InvokeAgent spans. |
 | `a365_enable_observability_exporter` | `bool` | `None` | Enable the A365 HTTP exporter. Also read from `ENABLE_A365_OBSERVABILITY_EXPORTER` env var. Defaults to `false` when neither is set. |
 | `a365_observability_scope_override` | `str` | `False` | Override the default Entra scope used by the built-in token resolvers. Also read from `A365_OBSERVABILITY_SCOPE_OVERRIDE`. |
+| `a365_max_queue_size` | `int` | `2048` | Maximum queue size for the A365 batch span processor. |
+| `a365_scheduled_delay_ms` | `int` | `5000` | Delay between A365 export batches (ms). |
+| `a365_exporter_timeout_ms` | `int` | `30000` | Timeout for a single A365 export operation (ms). |
+| `a365_max_export_batch_size` | `int` | `512` | Maximum batch size for a single A365 export operation. |
 
 > For A365 token resolver patterns, baggage, and scope classes, see the [A365 guide](docs/A365_DOCUMENTATION.md).
 

src/microsoft/opentelemetry/_constants.py

@@ -104,3 +104,7 @@
 A365_SUPPRESS_INVOKE_AGENT_INPUT_ARG = "a365_suppress_invoke_agent_input"
 A365_ENABLE_OBSERVABILITY_EXPORTER_ARG = "a365_enable_observability_exporter"
 A365_OBSERVABILITY_SCOPE_OVERRIDE_ARG = "a365_observability_scope_override"
+A365_MAX_QUEUE_SIZE_ARG = "a365_max_queue_size"
+A365_SCHEDULED_DELAY_MS_ARG = "a365_scheduled_delay_ms"
+A365_EXPORTER_TIMEOUT_MS_ARG = "a365_exporter_timeout_ms"
+A365_MAX_EXPORT_BATCH_SIZE_ARG = "a365_max_export_batch_size"

src/microsoft/opentelemetry/_distro.py

@@ -39,6 +39,10 @@
     A365_SUPPRESS_INVOKE_AGENT_INPUT_ARG,
     A365_ENABLE_OBSERVABILITY_EXPORTER_ARG,
     A365_OBSERVABILITY_SCOPE_OVERRIDE_ARG,
+    A365_MAX_QUEUE_SIZE_ARG,
+    A365_SCHEDULED_DELAY_MS_ARG,
+    A365_EXPORTER_TIMEOUT_MS_ARG,
+    A365_MAX_EXPORT_BATCH_SIZE_ARG,
     ENABLE_AZURE_MONITOR_ARG,
     ENABLE_CONSOLE_ARG,
     INSTRUMENTATION_OPTIONS_ARG,
@@ -136,6 +140,18 @@ def use_microsoft_opentelemetry(**kwargs: object) -> None:  # pylint: disable=to
         A365 observability service. Equivalent to setting the
         ``A365_OBSERVABILITY_SCOPE_OVERRIDE`` environment variable. When provided,
         this kwarg overrides the env var.
+    :keyword int a365_max_queue_size:
+        Maximum queue size for the A365 batch span processor. Defaults to 2048
+        when omitted (BatchSpanProcessor default).
+    :keyword int a365_scheduled_delay_ms:
+        Delay between A365 export batches in milliseconds. Defaults to 5000
+        when omitted (BatchSpanProcessor default).
+    :keyword int a365_exporter_timeout_ms:
+        Timeout for a single A365 export operation in milliseconds. Defaults to
+        30000 when omitted (BatchSpanProcessor default).
+    :keyword int a365_max_export_batch_size:
+        Maximum batch size for a single A365 export operation. Defaults to 512
+        when omitted (BatchSpanProcessor default).
     :keyword bool enable_console:
         Enable console exporter for traces, metrics, and logs (development
         only).  Mirrors ``ExportTarget.Console`` from the .NET distro.
@@ -167,6 +183,10 @@ def use_microsoft_opentelemetry(**kwargs: object) -> None:  # pylint: disable=to
     a365_suppress_invoke_agent_input = kwargs.pop(A365_SUPPRESS_INVOKE_AGENT_INPUT_ARG, None)
     a365_enable_observability_exporter = kwargs.pop(A365_ENABLE_OBSERVABILITY_EXPORTER_ARG, None)
     a365_observability_scope_override = kwargs.pop(A365_OBSERVABILITY_SCOPE_OVERRIDE_ARG, None)
+    a365_max_queue_size = kwargs.pop(A365_MAX_QUEUE_SIZE_ARG, None)
+    a365_scheduled_delay_ms = kwargs.pop(A365_SCHEDULED_DELAY_MS_ARG, None)
+    a365_exporter_timeout_ms = kwargs.pop(A365_EXPORTER_TIMEOUT_MS_ARG, None)
+    a365_max_export_batch_size = kwargs.pop(A365_MAX_EXPORT_BATCH_SIZE_ARG, None)
 
     enable_spectra: bool = bool(kwargs.pop(ENABLE_SPECTRA_ARG, False))
     spectra_endpoint = kwargs.pop(SPECTRA_ENDPOINT_ARG, None)
@@ -218,6 +238,10 @@ def use_microsoft_opentelemetry(**kwargs: object) -> None:  # pylint: disable=to
         suppress_invoke_agent_input=a365_suppress_invoke_agent_input,
         enable_observability_exporter=a365_enable_observability_exporter,
         observability_scope_override=a365_observability_scope_override,
+        max_queue_size=a365_max_queue_size,
+        scheduled_delay_ms=a365_scheduled_delay_ms,
+        exporter_timeout_ms=a365_exporter_timeout_ms,
+        max_export_batch_size=a365_max_export_batch_size,
     )
 
     # ---- Console exporters (dev-only, mirrors ExportTarget.Console) ----
@@ -287,6 +311,10 @@ def _append_a365_components(
     suppress_invoke_agent_input: Any = None,
     enable_observability_exporter: Any = None,
     observability_scope_override: Any = None,
+    max_queue_size: Any = None,
+    scheduled_delay_ms: Any = None,
+    exporter_timeout_ms: Any = None,
+    max_export_batch_size: Any = None,
 ) -> None:
     """Build and append Agent365 span processors to ``otel_kwargs``.
 
@@ -370,10 +398,23 @@ def _append_a365_components(
             use_s2s_endpoint=resolved_use_s2s,
         )
 
-        # Enriching batch processor wrapping the exporter
+        # Enriching batch processor wrapping the exporter.
+        # Only forward batch parameters when the user explicitly supplied
+        # them so that BatchSpanProcessor uses its own defaults otherwise.
+        batch_kwargs: Dict[str, Any] = {}
+        if max_queue_size is not None:
+            batch_kwargs["max_queue_size"] = max_queue_size
+        if scheduled_delay_ms is not None:
+            batch_kwargs["schedule_delay_millis"] = scheduled_delay_ms
+        if exporter_timeout_ms is not None:
+            batch_kwargs["export_timeout_millis"] = exporter_timeout_ms
+        if max_export_batch_size is not None:
+            batch_kwargs["max_export_batch_size"] = max_export_batch_size
+
         batch_processor = _EnrichingBatchSpanProcessor(
             exporter,
             suppress_invoke_agent_input=resolved_suppress_input,
+            **batch_kwargs,
         )
 
         otel_kwargs[SPAN_PROCESSORS_ARG].append(batch_processor)

tests/test_distro.py

@@ -387,6 +387,10 @@ def token_fn(aid, tid):
             a365_suppress_invoke_agent_input=True,
             a365_enable_observability_exporter=False,
             a365_observability_scope_override="api://custom-scope/.default",
+            a365_max_queue_size=5000,
+            a365_scheduled_delay_ms=2000,
+            a365_exporter_timeout_ms=13000,
+            a365_max_export_batch_size=534,
         )
         a365_mock.assert_called_once()
         _, kwargs = a365_mock.call_args
@@ -396,6 +400,10 @@ def token_fn(aid, tid):
         self.assertEqual(kwargs["suppress_invoke_agent_input"], True)
         self.assertEqual(kwargs["enable_observability_exporter"], False)
         self.assertEqual(kwargs["observability_scope_override"], "api://custom-scope/.default")
+        self.assertEqual(kwargs["max_queue_size"], 5000)
+        self.assertEqual(kwargs["scheduled_delay_ms"], 2000)
+        self.assertEqual(kwargs["exporter_timeout_ms"], 13000)
+        self.assertEqual(kwargs["max_export_batch_size"], 534)
 
     @patch("microsoft.opentelemetry._distro._append_a365_components")
     def test_a365_not_called_when_disabled(self, a365_mock):
@@ -682,6 +690,87 @@ def test_observability_scope_override_defaults_to_none(self, default_resolver_mo
         default_resolver_mock.assert_called_once_with(scope_override=None)
 
 
+class TestA365BatchProcessorKwargs(unittest.TestCase):
+    """Tests for a365_max_queue_size / scheduled_delay_ms / exporter_timeout_ms /
+    max_export_batch_size kwargs forwarding to _EnrichingBatchSpanProcessor."""
+
+    def _build(self, **kwargs):
+        """Run _append_a365_components with the exporter enabled and return the
+        captured kwargs that were passed to _EnrichingBatchSpanProcessor."""
+        with (
+            patch(
+                "microsoft.opentelemetry.a365.core.exporters.utils._create_default_token_resolver",
+                return_value=lambda aid, tid: "token",
+            ),
+            patch("microsoft.opentelemetry.a365.core.exporters.agent365_exporter._Agent365Exporter"),
+            patch(
+                "microsoft.opentelemetry.a365.core.exporters.enriching_span_processor._EnrichingBatchSpanProcessor"
+            ) as proc_mock,
+        ):
+            otel_kwargs = {"span_processors": []}
+            _append_a365_components(
+                True,
+                otel_kwargs,
+                enable_observability_exporter=True,
+                **kwargs,
+            )
+        proc_mock.assert_called_once()
+        return proc_mock.call_args.kwargs
+
+    def test_batch_kwargs_omitted_when_user_does_not_pass_them(self):
+        """When the user passes none of the batch kwargs, the processor is
+        constructed without any of them so BatchSpanProcessor uses its own
+        defaults."""
+        proc_kwargs = self._build()
+        self.assertNotIn("max_queue_size", proc_kwargs)
+        self.assertNotIn("schedule_delay_millis", proc_kwargs)
+        self.assertNotIn("export_timeout_millis", proc_kwargs)
+        self.assertNotIn("max_export_batch_size", proc_kwargs)
+
+    def test_max_queue_size_forwarded(self):
+        proc_kwargs = self._build(max_queue_size=4096)
+        self.assertEqual(proc_kwargs["max_queue_size"], 4096)
+        self.assertNotIn("schedule_delay_millis", proc_kwargs)
+        self.assertNotIn("export_timeout_millis", proc_kwargs)
+        self.assertNotIn("max_export_batch_size", proc_kwargs)
+
+    def test_scheduled_delay_ms_forwarded_with_renamed_key(self):
+        """a365_scheduled_delay_ms maps to BatchSpanProcessor's schedule_delay_millis."""
+        proc_kwargs = self._build(scheduled_delay_ms=2000)
+        self.assertEqual(proc_kwargs["schedule_delay_millis"], 2000)
+        self.assertNotIn("scheduled_delay_ms", proc_kwargs)
+
+    def test_exporter_timeout_ms_forwarded_with_renamed_key(self):
+        """a365_exporter_timeout_ms maps to BatchSpanProcessor's export_timeout_millis."""
+        proc_kwargs = self._build(exporter_timeout_ms=15000)
+        self.assertEqual(proc_kwargs["export_timeout_millis"], 15000)
+        self.assertNotIn("exporter_timeout_ms", proc_kwargs)
+
+    def test_max_export_batch_size_forwarded(self):
+        proc_kwargs = self._build(max_export_batch_size=256)
+        self.assertEqual(proc_kwargs["max_export_batch_size"], 256)
+
+    def test_all_batch_kwargs_forwarded_together(self):
+        proc_kwargs = self._build(
+            max_queue_size=4096,
+            scheduled_delay_ms=2000,
+            exporter_timeout_ms=15000,
+            max_export_batch_size=256,
+        )
+        self.assertEqual(proc_kwargs["max_queue_size"], 4096)
+        self.assertEqual(proc_kwargs["schedule_delay_millis"], 2000)
+        self.assertEqual(proc_kwargs["export_timeout_millis"], 15000)
+        self.assertEqual(proc_kwargs["max_export_batch_size"], 256)
+        # Always-forwarded enriching kwarg is preserved.
+        self.assertIn("suppress_invoke_agent_input", proc_kwargs)
+
+    def test_zero_value_is_forwarded(self):
+        """Falsy-but-not-None integer values must still be forwarded (not dropped)."""
+        proc_kwargs = self._build(max_queue_size=0, max_export_batch_size=0)
+        self.assertEqual(proc_kwargs["max_queue_size"], 0)
+        self.assertEqual(proc_kwargs["max_export_batch_size"], 0)
+
+
 class TestA365Components(unittest.TestCase):
     """Tests for A365 enable_a365 flag and _append_a365_components."""