Add start_time and end_time parameters to OpenTelemetry scope classes

This change implements support for custom start and end times on OpenTelemetry spans,
mirroring the Node.js PR #205. Changes include:

- Add TimeInput type alias supporting int (nanoseconds), float (seconds), tuple (HrTime), and datetime
- Update OpenTelemetryScope base class with start_time and end_time constructor parameters
- Add set_end_time() method for setting end time after construction
- Update InferenceScope, InvokeAgentScope, ExecuteToolScope, and OutputScope to forward parameters
- Add comprehensive unit tests for custom start/end time functionality

Co-authored-by: nikhilNava <211831449+nikhilNava@users.noreply.github.com>

Author: Copilot

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/__init__.py

@@ -24,7 +24,7 @@
 from .invoke_agent_details import InvokeAgentDetails
 from .invoke_agent_scope import InvokeAgentScope
 from .middleware.baggage_builder import BaggageBuilder
-from .opentelemetry_scope import OpenTelemetryScope
+from .opentelemetry_scope import OpenTelemetryScope, TimeInput
 from .request import Request
 from .source_metadata import SourceMetadata
 from .tenant_details import TenantDetails
@@ -47,6 +47,8 @@
     "SpanProcessor",
     # Base scope class
     "OpenTelemetryScope",
+    # Type aliases
+    "TimeInput",
     # Specific scope classes
     "ExecuteToolScope",
     "InvokeAgentScope",

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/execute_tool_scope.py

@@ -15,7 +15,7 @@
     SERVER_ADDRESS_KEY,
     SERVER_PORT_KEY,
 )
-from .opentelemetry_scope import OpenTelemetryScope
+from .opentelemetry_scope import OpenTelemetryScope, TimeInput
 from .request import Request
 from .tenant_details import TenantDetails
 from .tool_call_details import ToolCallDetails
@@ -31,6 +31,8 @@ def start(
         tenant_details: TenantDetails,
         request: Request | None = None,
         parent_id: str | None = None,
+        start_time: TimeInput = None,
+        end_time: TimeInput = None,
     ) -> "ExecuteToolScope":
         """Creates and starts a new scope for tool execution tracing.
 
@@ -41,11 +43,18 @@ def start(
             request: Optional request details for additional context
             parent_id: Optional parent Activity ID used to link this span to an upstream
                 operation
+            start_time: Optional explicit start time (ms epoch, Date, or HrTime). Useful when
+                recording a tool call after execution has already completed.
+            end_time: Optional explicit end time (ms epoch, Date, or HrTime). When provided,
+                the span will use this timestamp when disposed instead of the current
+                wall-clock time.
 
         Returns:
             A new ExecuteToolScope instance
         """
-        return ExecuteToolScope(details, agent_details, tenant_details, request, parent_id)
+        return ExecuteToolScope(
+            details, agent_details, tenant_details, request, parent_id, start_time, end_time
+        )
 
     def __init__(
         self,
@@ -54,6 +63,8 @@ def __init__(
         tenant_details: TenantDetails,
         request: Request | None = None,
         parent_id: str | None = None,
+        start_time: TimeInput = None,
+        end_time: TimeInput = None,
     ):
         """Initialize the tool execution scope.
 
@@ -64,6 +75,11 @@ def __init__(
             request: Optional request details for additional context
             parent_id: Optional parent Activity ID used to link this span to an upstream
                 operation
+            start_time: Optional explicit start time (ms epoch, Date, or HrTime). Useful when
+                recording a tool call after execution has already completed.
+            end_time: Optional explicit end time (ms epoch, Date, or HrTime). When provided,
+                the span will use this timestamp when disposed instead of the current
+                wall-clock time.
         """
         super().__init__(
             kind="Internal",
@@ -72,6 +88,8 @@ def __init__(
             agent_details=agent_details,
             tenant_details=tenant_details,
             parent_id=parent_id,
+            start_time=start_time,
+            end_time=end_time,
         )
 
         # Extract details using deconstruction-like approach

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/inference_scope.py

@@ -19,7 +19,7 @@
     GEN_AI_USAGE_OUTPUT_TOKENS_KEY,
 )
 from .inference_call_details import InferenceCallDetails
-from .opentelemetry_scope import OpenTelemetryScope
+from .opentelemetry_scope import OpenTelemetryScope, TimeInput
 from .request import Request
 from .tenant_details import TenantDetails
 from .utils import safe_json_dumps
@@ -35,6 +35,8 @@ def start(
         tenant_details: TenantDetails,
         request: Request | None = None,
         parent_id: str | None = None,
+        start_time: TimeInput = None,
+        end_time: TimeInput = None,
     ) -> "InferenceScope":
         """Creates and starts a new scope for inference tracing.
 
@@ -45,11 +47,15 @@ def start(
             request: Optional request details for additional context
             parent_id: Optional parent Activity ID used to link this span to an upstream
                 operation
+            start_time: Optional explicit start time (ms epoch, Date, or HrTime)
+            end_time: Optional explicit end time (ms epoch, Date, or HrTime)
 
         Returns:
             A new InferenceScope instance
         """
-        return InferenceScope(details, agent_details, tenant_details, request, parent_id)
+        return InferenceScope(
+            details, agent_details, tenant_details, request, parent_id, start_time, end_time
+        )
 
     def __init__(
         self,
@@ -58,6 +64,8 @@ def __init__(
         tenant_details: TenantDetails,
         request: Request | None = None,
         parent_id: str | None = None,
+        start_time: TimeInput = None,
+        end_time: TimeInput = None,
     ):
         """Initialize the inference scope.
 
@@ -68,6 +76,8 @@ def __init__(
             request: Optional request details for additional context
             parent_id: Optional parent Activity ID used to link this span to an upstream
                 operation
+            start_time: Optional explicit start time (ms epoch, Date, or HrTime)
+            end_time: Optional explicit end time (ms epoch, Date, or HrTime)
         """
 
         super().__init__(
@@ -77,6 +87,8 @@ def __init__(
             agent_details=agent_details,
             tenant_details=tenant_details,
             parent_id=parent_id,
+            start_time=start_time,
+            end_time=end_time,
         )
 
         if request:

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/invoke_agent_scope.py

@@ -32,7 +32,7 @@
 )
 from .invoke_agent_details import InvokeAgentDetails
 from .models.caller_details import CallerDetails
-from .opentelemetry_scope import OpenTelemetryScope
+from .opentelemetry_scope import OpenTelemetryScope, TimeInput
 from .request import Request
 from .tenant_details import TenantDetails
 from .utils import safe_json_dumps, validate_and_normalize_ip
@@ -50,6 +50,8 @@ def start(
         request: Request | None = None,
         caller_agent_details: AgentDetails | None = None,
         caller_details: CallerDetails | None = None,
+        start_time: TimeInput = None,
+        end_time: TimeInput = None,
     ) -> "InvokeAgentScope":
         """Create and start a new scope for agent invocation tracing.
 
@@ -60,12 +62,20 @@ def start(
             request: Optional request details for additional context
             caller_agent_details: Optional details of the caller agent
             caller_details: Optional details of the non-agentic caller
+            start_time: Optional explicit start time (ms epoch, Date, or HrTime)
+            end_time: Optional explicit end time (ms epoch, Date, or HrTime)
 
         Returns:
             A new InvokeAgentScope instance
         """
         return InvokeAgentScope(
-            invoke_agent_details, tenant_details, request, caller_agent_details, caller_details
+            invoke_agent_details,
+            tenant_details,
+            request,
+            caller_agent_details,
+            caller_details,
+            start_time,
+            end_time,
         )
 
     def __init__(
@@ -75,6 +85,8 @@ def __init__(
         request: Request | None = None,
         caller_agent_details: AgentDetails | None = None,
         caller_details: CallerDetails | None = None,
+        start_time: TimeInput = None,
+        end_time: TimeInput = None,
     ):
         """Initialize the agent invocation scope.
 
@@ -84,6 +96,8 @@ def __init__(
             request: Optional request details for additional context
             caller_agent_details: Optional details of the caller agent
             caller_details: Optional details of the non-agentic caller
+            start_time: Optional explicit start time (ms epoch, Date, or HrTime)
+            end_time: Optional explicit end time (ms epoch, Date, or HrTime)
         """
         activity_name = INVOKE_AGENT_OPERATION_NAME
         if invoke_agent_details.details.agent_name:
@@ -97,6 +111,8 @@ def __init__(
             activity_name=activity_name,
             agent_details=invoke_agent_details.details,
             tenant_details=tenant_details,
+            start_time=start_time,
+            end_time=end_time,
         )
 
         endpoint, _, session_id = (

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/opentelemetry_scope.py

@@ -6,6 +6,7 @@
 import logging
 import os
 import time
+from datetime import datetime
 from threading import Lock
 from typing import TYPE_CHECKING, Any
 
@@ -48,6 +49,12 @@
 # Create logger for this module - inherits from 'microsoft_agents_a365.observability.core'
 logger = logging.getLogger(__name__)
 
+# TimeInput is a type alias for types that can be used as span timestamps.
+# OpenTelemetry Python SDK accepts int (nanoseconds since epoch), float (seconds since epoch),
+# or a tuple of (seconds, nanoseconds) as HrTime.
+# We extend this to also accept datetime objects for convenience.
+TimeInput = int | float | tuple[int, int] | datetime | None
+
 
 class OpenTelemetryScope:
     """Base class for OpenTelemetry tracing scopes in the SDK."""
@@ -80,6 +87,8 @@ def __init__(
         agent_details: "AgentDetails | None" = None,
         tenant_details: "TenantDetails | None" = None,
         parent_id: str | None = None,
+        start_time: TimeInput = None,
+        end_time: TimeInput = None,
     ):
         """Initialize the OpenTelemetry scope.
 
@@ -91,9 +100,20 @@ def __init__(
             tenant_details: Optional tenant details
             parent_id: Optional parent Activity ID used to link this span to an upstream
                 operation
+            start_time: Optional explicit start time. Can be:
+                - int: nanoseconds since epoch
+                - float: seconds since epoch
+                - tuple[int, int]: HrTime as (seconds, nanoseconds)
+                - datetime: Python datetime object
+                Useful when recording an operation after it has already completed.
+            end_time: Optional explicit end time in the same format as start_time.
+                When provided, the span will use this timestamp when disposed
+                instead of the current wall-clock time.
         """
         self._span: Span | None = None
-        self._start_time = time.time()
+        self._wall_clock_start_ms = time.time() * 1000  # milliseconds
+        self._custom_start_time: TimeInput = start_time
+        self._custom_end_time: TimeInput = end_time
         self._has_ended = False
         self._error_type: str | None = None
         self._exception: Exception | None = None
@@ -119,7 +139,15 @@ def __init__(
             parent_context = parse_parent_id_to_context(parent_id)
             span_context = parent_context if parent_context else context.get_current()
 
-            self._span = tracer.start_span(activity_name, kind=activity_kind, context=span_context)
+            # Convert custom start time to OTel-compatible format (nanoseconds since epoch)
+            otel_start_time = self._time_input_to_ns(start_time) if start_time else None
+
+            self._span = tracer.start_span(
+                activity_name,
+                kind=activity_kind,
+                context=span_context,
+                start_time=otel_start_time,
+            )
 
             # Log span creation
             if self._span:
@@ -230,14 +258,84 @@ def record_attributes(self, attributes: dict[str, Any] | list[tuple[str, Any]])
             if key and key.strip():
                 self._span.set_attribute(key, value)
 
+    @staticmethod
+    def _time_input_to_ns(t: TimeInput) -> int | None:
+        """Convert a TimeInput value to nanoseconds since epoch.
+
+        OpenTelemetry Python SDK accepts int (nanoseconds since epoch) for span
+        start_time and end_time parameters.
+
+        Args:
+            t: TimeInput value which can be:
+                - int: nanoseconds since epoch (returned as-is)
+                - float: seconds since epoch
+                - tuple[int, int]: HrTime as (seconds, nanoseconds)
+                - datetime: Python datetime object
+
+        Returns:
+            Nanoseconds since epoch, or None if input is None
+        """
+        if t is None:
+            return None
+        if isinstance(t, int):
+            # Assume nanoseconds if it's an integer
+            return t
+        if isinstance(t, float):
+            # Convert seconds to nanoseconds
+            return int(t * 1_000_000_000)
+        if isinstance(t, tuple) and len(t) == 2:
+            # HrTime: (seconds, nanoseconds)
+            seconds, nanos = t
+            return seconds * 1_000_000_000 + nanos
+        if isinstance(t, datetime):
+            return int(t.timestamp() * 1_000_000_000)
+        logger.warning(
+            f"_time_input_to_ns received unexpected TimeInput "
+            f"(type={type(t).__name__}); returning None"
+        )
+        return None
+
+    @staticmethod
+    def _time_input_to_ms(t: TimeInput) -> float | None:
+        """Convert a TimeInput value to milliseconds since epoch.
+
+        Used for duration calculations.
+
+        Args:
+            t: TimeInput value (see _time_input_to_ns for accepted types)
+
+        Returns:
+            Milliseconds since epoch, or None if input is None
+        """
+        ns = OpenTelemetryScope._time_input_to_ns(t)
+        return ns / 1_000_000 if ns is not None else None
+
+    def set_end_time(self, end_time: TimeInput) -> None:
+        """Set a custom end time for the scope.
+
+        When set, dispose() will pass this value to span.end() instead of using
+        the current wall-clock time. This is useful when the actual end time of
+        the operation is known before the scope is disposed.
+
+        Args:
+            end_time: The end time as nanoseconds since epoch, seconds since epoch,
+                     HrTime tuple (seconds, nanoseconds), or datetime object.
+        """
+        self._custom_end_time = end_time
+
     def _end(self) -> None:
         """End the span and record metrics."""
         if self._span and self._is_telemetry_enabled() and not self._has_ended:
             self._has_ended = True
             span_id = f"{self._span.context.span_id:016x}" if self._span.context else "unknown"
             logger.info(f"Span ended: '{self._span.name}' ({span_id})")
 
-            self._span.end()
+            # Convert custom end time to OTel-compatible format (nanoseconds since epoch)
+            otel_end_time = self._time_input_to_ns(self._custom_end_time)
+            if otel_end_time is not None:
+                self._span.end(end_time=otel_end_time)
+            else:
+                self._span.end()
 
     def __enter__(self):
         """Enter the context manager and make span active."""