microsoft-agents-a365-observability-extensions-semantic-kernel 0.2.1.dev7__py3-none-any.whl → 0.2.1.dev9__py3-none-any.whl

microsoft_agents_a365/observability/extensions/semantickernel/span_enricher.py

@@ -0,0 +1,75 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Span enricher for Semantic Kernel."""
+
+from microsoft_agents_a365.observability.core.constants import (
+    EXECUTE_TOOL_OPERATION_NAME,
+    GEN_AI_INPUT_MESSAGES_KEY,
+    GEN_AI_OUTPUT_MESSAGES_KEY,
+    GEN_AI_TOOL_ARGS_KEY,
+    GEN_AI_TOOL_CALL_RESULT_KEY,
+    INVOKE_AGENT_OPERATION_NAME,
+)
+from microsoft_agents_a365.observability.core.exporters.enriched_span import EnrichedReadableSpan
+from opentelemetry.sdk.trace import ReadableSpan
+
+from .utils import extract_content_as_string_list
+
+# Semantic Kernel specific attribute keys
+SK_TOOL_CALL_ARGUMENTS_KEY = "gen_ai.tool.call.arguments"
+SK_TOOL_CALL_RESULT_KEY = "gen_ai.tool.call.result"
+
+
+def enrich_semantic_kernel_span(span: ReadableSpan) -> ReadableSpan:
+    """
+    Enricher function for Semantic Kernel spans.
+
+    Transforms SK-specific attributes to standard gen_ai attributes
+    before the span is exported. Enrichment is applied based on span type:
+    - invoke_agent spans: Extract only content from input/output messages
+    - execute_tool spans: Map tool arguments and results to standard keys
+
+    Args:
+        span: The ReadableSpan to enrich.
+
+    Returns:
+        The enriched span (wrapped if attributes were added), or the
+        original span if no enrichment was needed.
+    """
+    extra_attributes = {}
+    attributes = span.attributes or {}
+
+    # Only extract content for invoke_agent spans
+    if span.name.startswith(INVOKE_AGENT_OPERATION_NAME):
+        # Transform SK-specific agent invocation attributes to standard gen_ai attributes
+        # Extract only the content from the full message objects
+        # Support both gen_ai.agent.invocation_input and gen_ai.input_messages as sources
+        input_messages = attributes.get("gen_ai.agent.invocation_input") or attributes.get(
+            GEN_AI_INPUT_MESSAGES_KEY
+        )
+        if input_messages:
+            extra_attributes[GEN_AI_INPUT_MESSAGES_KEY] = extract_content_as_string_list(
+                input_messages
+            )
+
+        output_messages = attributes.get("gen_ai.agent.invocation_output") or attributes.get(
+            GEN_AI_OUTPUT_MESSAGES_KEY
+        )
+        if output_messages:
+            extra_attributes[GEN_AI_OUTPUT_MESSAGES_KEY] = extract_content_as_string_list(
+                output_messages
+            )
+
+    # Map tool attributes for execute_tool spans
+    elif span.name.startswith(EXECUTE_TOOL_OPERATION_NAME):
+        if SK_TOOL_CALL_ARGUMENTS_KEY in attributes:
+            extra_attributes[GEN_AI_TOOL_ARGS_KEY] = attributes[SK_TOOL_CALL_ARGUMENTS_KEY]
+
+        if SK_TOOL_CALL_RESULT_KEY in attributes:
+            extra_attributes[GEN_AI_TOOL_CALL_RESULT_KEY] = attributes[SK_TOOL_CALL_RESULT_KEY]
+
+    if extra_attributes:
+        return EnrichedReadableSpan(span, extra_attributes)
+
+    return span

microsoft_agents_a365/observability/extensions/semantickernel/span_processor.py

@@ -1,11 +1,16 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
-# Custom Span Processor
-
-from microsoft_agents_a365.observability.core.constants import GEN_AI_OPERATION_NAME_KEY
+from microsoft_agents_a365.observability.core.constants import (
+    GEN_AI_EXECUTION_TYPE_KEY,
+    GEN_AI_OPERATION_NAME_KEY,
+    INVOKE_AGENT_OPERATION_NAME,
+)
+from microsoft_agents_a365.observability.core.execution_type import ExecutionType
 from microsoft_agents_a365.observability.core.inference_operation_type import InferenceOperationType
 from microsoft_agents_a365.observability.core.utils import extract_model_name
+from opentelemetry import context as context_api
+from opentelemetry.sdk.trace import ReadableSpan, Span
 from opentelemetry.sdk.trace.export import SpanProcessor
 
 
@@ -15,13 +20,42 @@ class SemanticKernelSpanProcessor(SpanProcessor):
     """
 
     def __init__(self, service_name: str | None = None):
+        """
+        Initialize the Semantic Kernel span processor.
+
+        Args:
+            service_name: Optional service name for span enrichment.
+        """
         self.service_name = service_name
 
-    def on_start(self, span, parent_context):
+    def on_start(self, span: Span, parent_context: context_api.Context | None) -> None:
+        """
+        Modify span while it's still writable.
+
+        Args:
+            span: The span that is starting (writable).
+            parent_context: The parent context of the span.
+        """
         if span.name.startswith("chat."):
             span.set_attribute(GEN_AI_OPERATION_NAME_KEY, InferenceOperationType.CHAT.value.lower())
             model_name = extract_model_name(span.name)
             span.update_name(f"{InferenceOperationType.CHAT.value.lower()} {model_name}")
 
-    def on_end(self, span):
+        if span.name.startswith(INVOKE_AGENT_OPERATION_NAME):
+            span.set_attribute(
+                GEN_AI_EXECUTION_TYPE_KEY, ExecutionType.HUMAN_TO_AGENT.value.lower()
+            )
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """
+        Called when a span ends.
+        """
         pass
+
+    def shutdown(self) -> None:
+        """Shutdown the processor."""
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """Force flush any pending spans."""
+        return True

microsoft_agents_a365/observability/extensions/semantickernel/trace_instrumentor.py

@@ -6,30 +6,35 @@ from __future__ import annotations
 from collections.abc import Collection
 from typing import Any
 
-from microsoft_agents_a365.observability.core.config import get_tracer_provider, is_configured
+from microsoft_agents_a365.observability.core.config import (
+    get_tracer_provider,
+    is_configured,
+)
+from microsoft_agents_a365.observability.core.exporters.enriching_span_processor import (
+    register_span_enricher,
+    unregister_span_enricher,
+)
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
 
+from microsoft_agents_a365.observability.extensions.semantickernel.span_enricher import (
+    enrich_semantic_kernel_span,
+)
 from microsoft_agents_a365.observability.extensions.semantickernel.span_processor import (
     SemanticKernelSpanProcessor,
 )
 
-# -----------------------------
-# 3) The Instrumentor class
-# -----------------------------
 _instruments = ("semantic-kernel >= 1.0.0",)
 
 
 class SemanticKernelInstrumentor(BaseInstrumentor):
     """
-    Instruments Semantic Kernel:
-      • Installs your custom OTel SpanProcessor
-      • (Optionally) attaches an SK function-invocation filter to enrich spans
+    Instruments Semantic Kernel with Agent365 observability.
     """
 
     def __init__(self):
         if not is_configured():
             raise RuntimeError(
-                "Microsoft Agent 365 (or your telemetry config) is not initialized. Configure it before instrumenting."
+                "Microsoft Agent 365 is not initialized. Call configure() before instrumenting."
             )
         super().__init__()
 
@@ -38,13 +43,32 @@ class SemanticKernelInstrumentor(BaseInstrumentor):
 
     def _instrument(self, **kwargs: Any) -> None:
         """
-        kwargs (all optional):
-        """
+        Instrument Semantic Kernel.
 
-        # Ensure we have an SDK TracerProvider
+        Args:
+            **kwargs: Optional configuration parameters.
+        """
         provider = get_tracer_provider()
+
+        # Add processor for on_start modifications (rename spans, add attributes)
         self._processor = SemanticKernelSpanProcessor()
         provider.add_span_processor(self._processor)
 
+        # Register enricher for on_end modifications
+        # This enricher runs before the span is exported, allowing us to
+        # transform SK-specific attributes to standard gen_ai attributes
+        register_span_enricher(enrich_semantic_kernel_span)
+
     def _uninstrument(self, **kwargs: Any) -> None:
-        pass
+        """
+        Remove Semantic Kernel instrumentation.
+
+        Args:
+            **kwargs: Optional configuration parameters.
+        """
+        # Unregister the enricher
+        unregister_span_enricher()
+
+        # Shutdown the processor
+        if hasattr(self, "_processor"):
+            self._processor.shutdown()

microsoft_agents_a365/observability/extensions/semantickernel/utils.py

@@ -0,0 +1,37 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Utility functions for Semantic Kernel observability extensions."""
+
+from __future__ import annotations
+
+import json
+
+
+def extract_content_as_string_list(messages_json: str) -> str:
+    """Extract content values from messages JSON and return as JSON string list.
+
+    Transforms from: [{"role": "user", "content": "Hello"}]
+    To: ["Hello"]
+
+    Args:
+        messages_json: JSON string like '[{"role": "user", "content": "Hello"}]'
+
+    Returns:
+        JSON string containing only the content values as an array,
+        or the original string if parsing fails.
+    """
+    try:
+        messages = json.loads(messages_json)
+        if isinstance(messages, list):
+            contents = []
+            for msg in messages:
+                if isinstance(msg, dict) and "content" in msg:
+                    contents.append(msg["content"])
+                elif isinstance(msg, str):
+                    contents.append(msg)
+            return json.dumps(contents)
+        return messages_json
+    except (json.JSONDecodeError, TypeError):
+        # If parsing fails, return as-is
+        return messages_json

{microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev7.dist-info → microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-a365-observability-extensions-semantic-kernel
-Version: 0.2.1.dev7
+Version: 0.2.1.dev9
 Summary: Semantic Kernel observability and tracing extensions for Microsoft Agent 365
 Author-email: Microsoft <support@microsoft.com>
 License: MIT

microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev9.dist-info/RECORD

@@ -0,0 +1,9 @@
+microsoft_agents_a365/observability/extensions/semantickernel/__init__.py,sha256=ftH5IKh1CBMvS1AYGEh6md7b7NX_80ZoIORUElbKBg4,74
+microsoft_agents_a365/observability/extensions/semantickernel/span_enricher.py,sha256=OTeTffta2QcI57nNwLUhtftucZ6Ctoe4AG7ETvy6w9c,2872
+microsoft_agents_a365/observability/extensions/semantickernel/span_processor.py,sha256=_pbNx_qc_PhQq79A37JozVr-FqwrvRJL_wV1a2OFHmw,2122
+microsoft_agents_a365/observability/extensions/semantickernel/trace_instrumentor.py,sha256=KaGekkBMYY2jZcbuB46tSWGbCiu0a394eZKnQDlEXto,2306
+microsoft_agents_a365/observability/extensions/semantickernel/utils.py,sha256=RdV0hlCnPD_i0g-CXKmN0qD5bybDhPHIiGPHjrMDNgY,1185
+microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev9.dist-info/METADATA,sha256=kxbSpbqbQ8RUTha_eTvVtT9qXMp4NomEWjkyHlfIpyQ,3713
+microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev9.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev9.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev9.dist-info/RECORD,,

microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev7.dist-info/RECORD

@@ -1,7 +0,0 @@
-microsoft_agents_a365/observability/extensions/semantickernel/__init__.py,sha256=ftH5IKh1CBMvS1AYGEh6md7b7NX_80ZoIORUElbKBg4,74
-microsoft_agents_a365/observability/extensions/semantickernel/span_processor.py,sha256=OFlXRbHY4YjM3FnvIaIzjMFCMf-xRnxuni6eIGNbdpg,993
-microsoft_agents_a365/observability/extensions/semantickernel/trace_instrumentor.py,sha256=avsopF76V_n5L6aAcbILlQTJ8af-PmKBYxGu3DCxDko,1551
-microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev7.dist-info/METADATA,sha256=_tA9X4o8E1hNBt6IsKqzkP0F8Kp6p7z8KWZb-hhgWkU,3713
-microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev7.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev7.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
-microsoft_agents_a365_observability_extensions_semantic_kernel-0.2.1.dev7.dist-info/RECORD,,