perf: only force flush tracer provider when ending agent spans

Reduce overhead by limiting force_flush calls to agent span completion
instead of every span end. Add flush parameter to _end_span() with
default False, passing True only from end_agent_span().

Author: Di-Is

src/strands/telemetry/tracer.py

@@ -186,6 +186,7 @@ def _end_span(
         attributes: dict[str, AttributeValue] | None = None,
         error: BaseException | None = None,
         error_message: str | None = None,
+        flush: bool = False,
     ) -> None:
         """Generic helper method to end a span.
 
@@ -194,6 +195,7 @@ def _end_span(
             attributes: Optional attributes to set before ending the span
             error: Optional exception if an error occurred
             error_message: Optional error message to set in the span status
+            flush: Force the tracer provider to flush after ending the span
         """
         if not span or not span.is_recording():
             return
@@ -217,8 +219,7 @@ def _end_span(
             logger.warning("error=<%s> | error while ending span", e, exc_info=True)
         finally:
             span.end()
-            # Force flush to ensure spans are exported
-            if self.tracer_provider and hasattr(self.tracer_provider, "force_flush"):
+            if flush and self.tracer_provider and hasattr(self.tracer_provider, "force_flush"):
                 try:
                     self.tracer_provider.force_flush()
                 except Exception as e:
@@ -699,7 +700,7 @@ def end_agent_span(
                     }
                 )
 
-        self._end_span(span, attributes, error)
+        self._end_span(span, attributes, error, flush=True)
 
     def _construct_tool_definitions(self, tools_config: dict) -> list[dict[str, Any]]:
         """Constructs a list of tool definitions from the provided tools_config."""

tests/strands/telemetry/test_tracer.py

@@ -1089,21 +1089,40 @@ def test_end_span_with_exception_handling(mock_span):
         pytest.fail("_end_span should not raise exceptions")
 
 
+def test_end_span_does_not_force_flush_by_default(mock_span, mock_get_tracer_provider):
+    """Test that ending a regular span does not force flush by default."""
+    tracer = Tracer()
+    mock_tracer_provider = mock_get_tracer_provider.return_value
+
+    tracer._end_span(mock_span)
+
+    mock_tracer_provider.force_flush.assert_not_called()
+
+
 def test_force_flush_with_error(mock_span, mock_get_tracer_provider):
     """Test force flush with error handling."""
-    # Setup the tracer with a provider that raises an exception on force_flush
     tracer = Tracer()
 
     mock_tracer_provider = mock_get_tracer_provider.return_value
     mock_tracer_provider.force_flush.side_effect = Exception("Force flush error")
 
     # Should not raise an exception
-    tracer._end_span(mock_span)
+    tracer._end_span(mock_span, flush=True)
 
     # Verify force_flush was called
     mock_tracer_provider.force_flush.assert_called_once()
 
 
+def test_end_agent_span_force_flushes(mock_span, mock_get_tracer_provider):
+    """Test that ending an agent span forces a flush."""
+    tracer = Tracer()
+    mock_tracer_provider = mock_get_tracer_provider.return_value
+
+    tracer.end_agent_span(mock_span)
+
+    mock_tracer_provider.force_flush.assert_called_once()
+
+
 def test_end_agent_span_with_empty_error_message_uses_exception_name(mock_span):
     """Test that agent spans fall back to the exception type name for empty errors."""
     tracer = Tracer()