microsoft-agents-a365-observability-core 0.2.1.dev7__py3-none-any.whl → 0.2.1.dev10__py3-none-any.whl

microsoft_agents_a365/observability/core/__init__.py

@@ -12,6 +12,12 @@ from .config import (
 )
 from .execute_tool_scope import ExecuteToolScope
 from .execution_type import ExecutionType
+from .exporters.enriched_span import EnrichedReadableSpan
+from .exporters.enriching_span_processor import (
+    get_span_enricher,
+    register_span_enricher,
+    unregister_span_enricher,
+)
 from .inference_call_details import InferenceCallDetails
 from .inference_operation_type import InferenceOperationType
 from .inference_scope import InferenceScope
@@ -32,6 +38,11 @@ __all__ = [
     "is_configured",
     "get_tracer",
     "get_tracer_provider",
+    # Span enrichment
+    "register_span_enricher",
+    "unregister_span_enricher",
+    "get_span_enricher",
+    "EnrichedReadableSpan",
     # Span processor
     "SpanProcessor",
     # Base scope class

microsoft_agents_a365/observability/core/config.py

@@ -9,10 +9,13 @@ from typing import Any, Optional
 from opentelemetry import trace
 from opentelemetry.sdk.resources import SERVICE_NAME, SERVICE_NAMESPACE, Resource
 from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter
 
 from .exporters.agent365_exporter import _Agent365Exporter
 from .exporters.agent365_exporter_options import Agent365ExporterOptions
+from .exporters.enriching_span_processor import (
+    _EnrichingBatchSpanProcessor,
+)
 from .exporters.utils import is_agent365_exporter_enabled
 from .trace_processor.span_processor import SpanProcessor
 
@@ -166,8 +169,9 @@ class TelemetryManager:
 
         # Add span processors
 
-        # Create BatchSpanProcessor with optimized settings
-        batch_processor = BatchSpanProcessor(exporter, **batch_processor_kwargs)
+        # Create _EnrichingBatchSpanProcessor with optimized settings
+        # This allows extensions to enrich spans before export
+        batch_processor = _EnrichingBatchSpanProcessor(exporter, **batch_processor_kwargs)
         agent_processor = SpanProcessor()
 
         tracer_provider.add_span_processor(batch_processor)

microsoft_agents_a365/observability/core/exporters/enriched_span.py

@@ -0,0 +1,160 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Enriched ReadableSpan wrapper for adding attributes to immutable spans."""
+
+import json
+from typing import Any
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.util import types
+
+
+class EnrichedReadableSpan(ReadableSpan):
+    """
+    Wrapper to add attributes to an immutable ReadableSpan.
+
+    Since ReadableSpan is immutable after a span ends, this wrapper allows
+    extensions to add additional attributes before export without modifying
+    the original span.
+    """
+
+    def __init__(self, span: ReadableSpan, extra_attributes: dict):
+        """
+        Initialize the enriched span wrapper.
+
+        Args:
+            span: The original ReadableSpan to wrap.
+            extra_attributes: Additional attributes to merge with the original.
+        """
+        self._span = span
+        self._extra_attributes = extra_attributes
+
+    @property
+    def attributes(self) -> types.Attributes:
+        """Return merged attributes from original span and extra attributes."""
+        original = dict(self._span.attributes or {})
+        original.update(self._extra_attributes)
+        return original
+
+    @property
+    def name(self):
+        """Return the span name."""
+        return self._span.name
+
+    @property
+    def context(self):
+        """Return the span context."""
+        return self._span.context
+
+    @property
+    def parent(self):
+        """Return the parent span context."""
+        return self._span.parent
+
+    @property
+    def start_time(self):
+        """Return the span start time."""
+        return self._span.start_time
+
+    @property
+    def end_time(self):
+        """Return the span end time."""
+        return self._span.end_time
+
+    @property
+    def status(self):
+        """Return the span status."""
+        return self._span.status
+
+    @property
+    def kind(self):
+        """Return the span kind."""
+        return self._span.kind
+
+    @property
+    def events(self):
+        """Return the span events."""
+        return self._span.events
+
+    @property
+    def links(self):
+        """Return the span links."""
+        return self._span.links
+
+    @property
+    def resource(self):
+        """Return the span resource."""
+        return self._span.resource
+
+    @property
+    def instrumentation_scope(self):
+        """Return the instrumentation scope."""
+        return self._span.instrumentation_scope
+
+    def to_json(self, indent: int | None = 4) -> str:
+        """
+        Convert span to JSON string with enriched attributes.
+
+        Args:
+            indent: JSON indentation level.
+
+        Returns:
+            JSON string representation of the span.
+        """
+        # Build the JSON dict manually to include enriched attributes
+        return json.dumps(
+            {
+                "name": self.name,
+                "context": {
+                    "trace_id": f"0x{self.context.trace_id:032x}",
+                    "span_id": f"0x{self.context.span_id:016x}",
+                    "trace_state": str(self.context.trace_state),
+                }
+                if self.context
+                else None,
+                "kind": str(self.kind),
+                "parent_id": f"0x{self.parent.span_id:016x}" if self.parent else None,
+                "start_time": self._format_time(self.start_time),
+                "end_time": self._format_time(self.end_time),
+                "status": {
+                    "status_code": str(self.status.status_code),
+                    "description": self.status.description,
+                }
+                if self.status
+                else None,
+                "attributes": dict(self.attributes) if self.attributes else None,
+                "events": [self._format_event(e) for e in self.events] if self.events else None,
+                "links": [self._format_link(lnk) for lnk in self.links] if self.links else None,
+                "resource": dict(self.resource.attributes) if self.resource else None,
+            },
+            indent=indent,
+        )
+
+    def _format_time(self, time_ns: int | None) -> str | None:
+        """Format nanosecond timestamp to ISO string."""
+        if time_ns is None:
+            return None
+        from datetime import datetime, timezone
+
+        return datetime.fromtimestamp(time_ns / 1e9, tz=timezone.utc).isoformat()
+
+    def _format_event(self, event: Any) -> dict:
+        """Format a span event."""
+        return {
+            "name": event.name,
+            "timestamp": self._format_time(event.timestamp),
+            "attributes": dict(event.attributes) if event.attributes else None,
+        }
+
+    def _format_link(self, link: Any) -> dict:
+        """Format a span link."""
+        return {
+            "context": {
+                "trace_id": f"0x{link.context.trace_id:032x}",
+                "span_id": f"0x{link.context.span_id:016x}",
+            }
+            if link.context
+            else None,
+            "attributes": dict(link.attributes) if link.attributes else None,
+        }

microsoft_agents_a365/observability/core/exporters/enriching_span_processor.py

@@ -0,0 +1,86 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Span enrichment support for the Agent365 exporter pipeline."""
+
+import logging
+import threading
+from collections.abc import Callable
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+logger = logging.getLogger(__name__)
+
+# Single span enricher - only one platform instrumentor should be active at a time
+_span_enricher: Callable[[ReadableSpan], ReadableSpan] | None = None
+_enricher_lock = threading.Lock()
+
+
+def register_span_enricher(enricher: Callable[[ReadableSpan], ReadableSpan]) -> None:
+    """Register the span enricher for the active platform instrumentor.
+
+    Only one enricher can be registered at a time since auto-instrumentation
+    is platform-specific (Semantic Kernel, LangChain, or OpenAI Agents).
+
+    Args:
+        enricher: Function that takes a ReadableSpan and returns an enriched span.
+
+    Raises:
+        RuntimeError: If an enricher is already registered.
+    """
+    global _span_enricher
+    with _enricher_lock:
+        if _span_enricher is not None:
+            raise RuntimeError(
+                "A span enricher is already registered. "
+                "Only one platform instrumentor can be active at a time."
+            )
+        _span_enricher = enricher
+        logger.debug("Span enricher registered: %s", enricher.__name__)
+
+
+def unregister_span_enricher() -> None:
+    """Unregister the current span enricher.
+
+    Called during uninstrumentation to clean up.
+    """
+    global _span_enricher
+    with _enricher_lock:
+        if _span_enricher is not None:
+            logger.debug("Span enricher unregistered: %s", _span_enricher.__name__)
+            _span_enricher = None
+
+
+def get_span_enricher() -> Callable[[ReadableSpan], ReadableSpan] | None:
+    """Get the currently registered span enricher.
+
+    Returns:
+        The registered enricher function, or None if no enricher is registered.
+    """
+    with _enricher_lock:
+        return _span_enricher
+
+
+class _EnrichingBatchSpanProcessor(BatchSpanProcessor):
+    """BatchSpanProcessor that applies the registered enricher before batching."""
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """Apply the span enricher and pass to parent for batching.
+
+        Args:
+            span: The span that has ended.
+        """
+        enriched_span = span
+
+        enricher = get_span_enricher()
+        if enricher is not None:
+            try:
+                enriched_span = enricher(span)
+            except Exception:
+                logger.exception(
+                    "Span enricher %s raised an exception, using original span",
+                    enricher.__name__,
+                )
+
+        super().on_end(enriched_span)

{microsoft_agents_a365_observability_core-0.2.1.dev7.dist-info → microsoft_agents_a365_observability_core-0.2.1.dev10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-a365-observability-core
-Version: 0.2.1.dev7
+Version: 0.2.1.dev10
 Summary: Telemetry, tracing, and monitoring components for AI agents
 Author-email: Microsoft <support@microsoft.com>
 License: MIT

{microsoft_agents_a365_observability_core-0.2.1.dev7.dist-info → microsoft_agents_a365_observability_core-0.2.1.dev10.dist-info}/RECORD

@@ -1,6 +1,6 @@
-microsoft_agents_a365/observability/core/__init__.py,sha256=r613vGLepo9ttTRmq3_EQz3hfDd4Ukp3v8AVS-6Uf_o,1762
+microsoft_agents_a365/observability/core/__init__.py,sha256=1wuG2_VL_XF0aNZ2EPF3M_3VGZe70LP6KAhS5UL73wQ,2090
 microsoft_agents_a365/observability/core/agent_details.py,sha256=7x4tqcocig1hz4T6eCRZy7fSF2gOCpM0pvE6Q3Txww0,1210
-microsoft_agents_a365/observability/core/config.py,sha256=YhnQaJr-SVNJLGM_HvYvaAfwXn-h9KinbNNZeXG9w90,11751
+microsoft_agents_a365/observability/core/config.py,sha256=p8p9Chyol6Ar-qM6MfHWl6mTw4lNupSagjArHclVg3M,11900
 microsoft_agents_a365/observability/core/constants.py,sha256=suvJc4JgB9o3eeDVyiJDk0kjFVkjeDrl6u43XsvPWBc,4747
 microsoft_agents_a365/observability/core/execute_tool_scope.py,sha256=XgramOBLhpilR5VjFsigdDCqYkDkG0D6CIrwN5xgeJw,3654
 microsoft_agents_a365/observability/core/execution_type.py,sha256=qnNGmo9-Tlb3PBTK3pen2QIAm2hlQiKl8vRuMPWHtk8,328
@@ -19,6 +19,8 @@ microsoft_agents_a365/observability/core/utils.py,sha256=fnZBCEsD-1FlxpJ5hcbwovr
 microsoft_agents_a365/observability/core/exporters/__init__.py,sha256=UEaMJYkbTViVAUVQTFSf1BUvni1pNTcDwriKzOzvGFU,296
 microsoft_agents_a365/observability/core/exporters/agent365_exporter.py,sha256=Q8ylOrgBF2gNB_KAn8QdtJu8E3aiC6kUUomCgNLqgb4,13490
 microsoft_agents_a365/observability/core/exporters/agent365_exporter_options.py,sha256=f-p11ZQfxtDIiK-kVPDfebBgT83onxdE29IQryYoAPk,1648
+microsoft_agents_a365/observability/core/exporters/enriched_span.py,sha256=PcXw4M-he-CuCw5OZT4ZbIbc1Uvskvp_N3Dz3qiNnPc,5056
+microsoft_agents_a365/observability/core/exporters/enriching_span_processor.py,sha256=9JXCMRjrKTc2VJ_rmSX8u5_DopBN_AR4WwyhFL9H4Ic,2781
 microsoft_agents_a365/observability/core/exporters/utils.py,sha256=tICuOuWfgUKL1dHoGuyG5_xNOrREPTXFE-RJZehpVT4,6989
 microsoft_agents_a365/observability/core/middleware/__init__.py,sha256=KNH2QjJBIGhn1xf_r3HdOVYUw9ngKEcy0HV9eHuTaqk,202
 microsoft_agents_a365/observability/core/middleware/baggage_builder.py,sha256=KaTb8n0D8dbjS-qph3o160VUEn4kYy8YdaFvGMd5Vck,10505
@@ -29,7 +31,7 @@ microsoft_agents_a365/observability/core/models/operation_source.py,sha256=HJp-S
 microsoft_agents_a365/observability/core/trace_processor/__init__.py,sha256=0QDkZgvgGekJVcZXjubSqipYhCGMZaAAxLSanyR76pg,219
 microsoft_agents_a365/observability/core/trace_processor/span_processor.py,sha256=O_DLuLR-6sV9VmkYfMzUF3s6n1OLrtK5qkD6csen73g,2980
 microsoft_agents_a365/observability/core/trace_processor/util.py,sha256=h5oOFAGIY6x9WtgfErPetblSkWZsQZjOgbwoR_tL-7k,2364
-microsoft_agents_a365_observability_core-0.2.1.dev7.dist-info/METADATA,sha256=5hQwVbA2sbJRdEZFebNaI_vMXRlurtx4XsOBUi1Jidg,3871
-microsoft_agents_a365_observability_core-0.2.1.dev7.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-microsoft_agents_a365_observability_core-0.2.1.dev7.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
-microsoft_agents_a365_observability_core-0.2.1.dev7.dist-info/RECORD,,
+microsoft_agents_a365_observability_core-0.2.1.dev10.dist-info/METADATA,sha256=5za0Ke8X9hZuZR1NpRcM9JWydFX6MCUqR--k_n_-yU4,3872
+microsoft_agents_a365_observability_core-0.2.1.dev10.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+microsoft_agents_a365_observability_core-0.2.1.dev10.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_observability_core-0.2.1.dev10.dist-info/RECORD,,