microsoft-agents-a365-observability-core 0.1.0__py3-none-any.whl → 0.2.0.dev5__py3-none-any.whl

microsoft_agents_a365/observability/core/agent_details.py

@@ -21,22 +21,25 @@ class AgentDetails:
     """A description of the AI agent's purpose or capabilities."""
 
     agent_auid: Optional[str] = None
-    """Optional Agent User ID for the agent."""
+    """Agentic User ID for the agent."""
 
     agent_upn: Optional[str] = None
-    """Optional User Principal Name (UPN) for the agent."""
+    """User Principal Name (UPN) for the agentic user."""
 
     agent_blueprint_id: Optional[str] = None
-    """Optional Blueprint/Application ID for the agent."""
+    """Blueprint/Application ID for the agent."""
 
     agent_type: Optional[AgentType] = None
     """The agent type."""
 
     tenant_id: Optional[str] = None
-    """Optional Tenant ID for the agent."""
+    """Tenant ID for the agent."""
 
     conversation_id: Optional[str] = None
     """Optional conversation ID for compatibility."""
 
     icon_uri: Optional[str] = None
     """Optional icon URI for the agent."""
+
+    agent_client_ip: Optional[str] = None
+    """Client IP address of the agent user."""

microsoft_agents_a365/observability/core/config.py

@@ -11,6 +11,7 @@ from opentelemetry.sdk.trace import TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
 
 from .exporters.agent365_exporter import Agent365Exporter
+from .exporters.agent365_exporter_options import Agent365ExporterOptions
 from .exporters.utils import is_agent365_exporter_enabled
 from .trace_processor.span_processor import SpanProcessor
 
@@ -51,6 +52,7 @@ class TelemetryManager:
         logger_name: str = DEFAULT_LOGGER_NAME,
         token_resolver: Callable[[str, str], str | None] | None = None,
         cluster_category: str = "prod",
+        exporter_options: Optional[Agent365ExporterOptions] = None,
         **kwargs: Any,
     ) -> bool:
         """
@@ -59,8 +61,12 @@ class TelemetryManager:
         :param service_name: The name of the service.
         :param service_namespace: The namespace of the service.
         :param logger_name: The name of the logger to collect telemetry from.
-        :param token_resolver: Callable that returns an auth token for a given agent + tenant.
-        :param cluster_category: Environment / cluster category (e.g., "preprod", "prod").
+        :param token_resolver: (Deprecated) Callable that returns an auth token for a given agent + tenant.
+            Use exporter_options instead.
+        :param cluster_category: (Deprecated) Environment / cluster category (e.g. "prod").
+            Use exporter_options instead.
+        :param exporter_options: Agent365ExporterOptions instance for configuring the exporter.
+            If provided, exporter_options takes precedence. If exporter_options is None, the token_resolver and cluster_category parameters are used as fallback/legacy support to construct a default Agent365ExporterOptions instance.
         :return: True if configuration succeeded, False otherwise.
         """
         try:
@@ -71,6 +77,7 @@ class TelemetryManager:
                     logger_name,
                     token_resolver,
                     cluster_category,
+                    exporter_options,
                     **kwargs,
                 )
         except Exception as e:
@@ -84,6 +91,7 @@ class TelemetryManager:
         logger_name: str,
         token_resolver: Callable[[str, str], str | None] | None = None,
         cluster_category: str = "prod",
+        exporter_options: Optional[Agent365ExporterOptions] = None,
         **kwargs: Any,
     ) -> bool:
         """Internal configuration method - not thread-safe, must be called with lock."""
@@ -115,11 +123,26 @@ class TelemetryManager:
         trace.set_tracer_provider(tracer_provider)
         self._tracer_provider = tracer_provider
 
-        if is_agent365_exporter_enabled() and token_resolver is not None:
-            exporter = Agent365Exporter(
-                token_resolver=token_resolver,
+        # Use exporter_options if provided, otherwise create default options with legacy parameters
+        if exporter_options is None:
+            exporter_options = Agent365ExporterOptions(
                 cluster_category=cluster_category,
-                **kwargs,
+                token_resolver=token_resolver,
+            )
+
+        # Extract configuration for BatchSpanProcessor
+        batch_processor_kwargs = {
+            "max_queue_size": exporter_options.max_queue_size,
+            "schedule_delay_millis": exporter_options.scheduled_delay_ms,
+            "export_timeout_millis": exporter_options.exporter_timeout_ms,
+            "max_export_batch_size": exporter_options.max_export_batch_size,
+        }
+
+        if is_agent365_exporter_enabled() and exporter_options.token_resolver is not None:
+            exporter = Agent365Exporter(
+                token_resolver=exporter_options.token_resolver,
+                cluster_category=exporter_options.cluster_category,
+                use_s2s_endpoint=exporter_options.use_s2s_endpoint,
             )
         else:
             exporter = ConsoleSpanExporter()
@@ -130,7 +153,7 @@ class TelemetryManager:
         # Add span processors
 
         # Create BatchSpanProcessor with optimized settings
-        batch_processor = BatchSpanProcessor(exporter)
+        batch_processor = BatchSpanProcessor(exporter, **batch_processor_kwargs)
         agent_processor = SpanProcessor()
 
         tracer_provider.add_span_processor(batch_processor)
@@ -197,6 +220,7 @@ def configure(
     logger_name: str = DEFAULT_LOGGER_NAME,
     token_resolver: Callable[[str, str], str | None] | None = None,
     cluster_category: str = "prod",
+    exporter_options: Optional[Agent365ExporterOptions] = None,
     **kwargs: Any,
 ) -> bool:
     """
@@ -205,6 +229,12 @@ def configure(
     :param service_name: The name of the service.
     :param service_namespace: The namespace of the service.
     :param logger_name: The name of the logger to collect telemetry from.
+    :param token_resolver: (Deprecated) Callable that returns an auth token for a given agent + tenant.
+        Use exporter_options instead.
+    :param cluster_category: (Deprecated) Environment / cluster category (e.g. "prod").
+        Use exporter_options instead.
+    :param exporter_options: Agent365ExporterOptions instance for configuring the exporter.
+        If provided, exporter_options takes precedence. If exporter_options is None, the token_resolver and cluster_category parameters are used as fallback/legacy support to construct a default Agent365ExporterOptions instance.
     :return: True if configuration succeeded, False otherwise.
     """
     return _telemetry_manager.configure(
@@ -213,6 +243,7 @@ def configure(
         logger_name,
         token_resolver,
         cluster_category,
+        exporter_options,
         **kwargs,
     )
 

microsoft_agents_a365/observability/core/constants.py

@@ -68,6 +68,7 @@ GEN_AI_CALLER_TENANT_ID_KEY = "gen_ai.caller.tenantid"
 GEN_AI_CALLER_ID_KEY = "gen_ai.caller.id"
 GEN_AI_CALLER_NAME_KEY = "gen_ai.caller.name"
 GEN_AI_CALLER_UPN_KEY = "gen_ai.caller.upn"
+GEN_AI_CALLER_CLIENT_IP_KEY = "gen_ai.caller.client.ip"
 
 # Agent to Agent caller agent dimensions
 GEN_AI_CALLER_AGENT_USER_ID_KEY = "gen_ai.caller.agent.userid"
@@ -77,6 +78,7 @@ GEN_AI_CALLER_AGENT_NAME_KEY = "gen_ai.caller.agent.name"
 GEN_AI_CALLER_AGENT_ID_KEY = "gen_ai.caller.agent.id"
 GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY = "gen_ai.caller.agent.applicationid"
 GEN_AI_CALLER_AGENT_TYPE_KEY = "gen_ai.caller.agent.type"
+GEN_AI_CALLER_AGENT_USER_CLIENT_IP = "gen_ai.caller.agent.user.client.ip"
 
 # Agent-specific dimensions
 AGENT_ID_KEY = "gen_ai.agent.id"
@@ -92,13 +94,13 @@ GEN_AI_AGENT_UPN_KEY = "gen_ai.agent.upn"
 GEN_AI_AGENT_BLUEPRINT_ID_KEY = "gen_ai.agent.applicationid"
 CORRELATION_ID_KEY = "correlation.id"
 HIRING_MANAGER_ID_KEY = "hiring.manager.id"
+SESSION_DESCRIPTION_KEY = "session.description"
 
 # Execution context dimensions
 GEN_AI_EXECUTION_TYPE_KEY = "gen_ai.execution.type"
 GEN_AI_EXECUTION_PAYLOAD_KEY = "gen_ai.execution.payload"
 
 # Source metadata dimensions
-GEN_AI_EXECUTION_SOURCE_ID_KEY = "gen_ai.execution.sourceMetadata.id"
 GEN_AI_EXECUTION_SOURCE_NAME_KEY = "gen_ai.channel.name"
 GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY = "gen_ai.channel.link"
 

microsoft_agents_a365/observability/core/exporters/agent365_exporter.py

@@ -23,6 +23,7 @@ from .utils import (
     kind_name,
     partition_by_identity,
     status_name,
+    truncate_span,
 )
 
 # ---- Exporter ---------------------------------------------------------------
@@ -295,7 +296,7 @@ class Agent365Exporter(SpanExporter):
         start_ns = sp.start_time
         end_ns = sp.end_time
 
-        return {
+        span_dict = {
             "traceId": hex_trace_id(ctx.trace_id),
             "spanId": hex_span_id(ctx.span_id),
             "parentSpanId": parent_span_id,
@@ -308,3 +309,6 @@ class Agent365Exporter(SpanExporter):
             "links": links,
             "status": status,
         }
+
+        # Apply truncation if needed
+        return truncate_span(span_dict)

microsoft_agents_a365/observability/core/exporters/agent365_exporter_options.py

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from typing import Awaitable, Callable, Optional
+
+
+class Agent365ExporterOptions:
+    """
+    Configuration for Agent365Exporter.
+    Only cluster_category and token_resolver are required for core operation.
+    """
+
+    def __init__(
+        self,
+        cluster_category: str = "prod",
+        token_resolver: Optional[Callable[[str, str], Awaitable[Optional[str]]]] = None,
+        use_s2s_endpoint: bool = False,
+        max_queue_size: int = 2048,
+        scheduled_delay_ms: int = 5000,
+        exporter_timeout_ms: int = 30000,
+        max_export_batch_size: int = 512,
+    ):
+        """
+        Args:
+            cluster_category: Cluster region argument. Defaults to 'prod'.
+            token_resolver: Async callable that resolves the auth token (REQUIRED).
+            use_s2s_endpoint: Use the S2S endpoint instead of standard endpoint.
+            max_queue_size: Maximum queue size for the batch processor. Default is 2048.
+            scheduled_delay_ms: Delay between export batches (ms). Default is 5000.
+            exporter_timeout_ms: Timeout for the export operation (ms). Default is 30000.
+            max_export_batch_size: Maximum batch size for export operations. Default is 512.
+        """
+        self.cluster_category = cluster_category
+        self.token_resolver = token_resolver
+        self.use_s2s_endpoint = use_s2s_endpoint
+        self.max_queue_size = max_queue_size
+        self.scheduled_delay_ms = scheduled_delay_ms
+        self.exporter_timeout_ms = exporter_timeout_ms
+        self.max_export_batch_size = max_export_batch_size

microsoft_agents_a365/observability/core/exporters/utils.py

@@ -1,5 +1,7 @@
 # Copyright (c) Microsoft. All rights reserved.
 
+import json
+import logging
 import os
 from collections.abc import Sequence
 from typing import Any
@@ -13,6 +15,11 @@ from ..constants import (
     TENANT_ID_KEY,
 )
 
+logger = logging.getLogger(__name__)
+
+# Maximum allowed span size in bytes (250KB)
+MAX_SPAN_SIZE_BYTES = 250 * 1024
+
 
 def hex_trace_id(value: int) -> str:
     # 128-bit -> 32 hex chars
@@ -46,6 +53,76 @@ def status_name(code: StatusCode) -> str:
         return str(code)
 
 
+def truncate_span(span_dict: dict[str, Any]) -> dict[str, Any]:
+    """
+    Truncate span attributes if the serialized span exceeds MAX_SPAN_SIZE_BYTES.
+
+    Args:
+        span_dict: The span dictionary to potentially truncate
+
+    Returns:
+        The potentially truncated span dictionary
+    """
+    try:
+        # Serialize the span to check its size
+        serialized = json.dumps(span_dict, separators=(",", ":"))
+        current_size = len(serialized.encode("utf-8"))
+
+        if current_size <= MAX_SPAN_SIZE_BYTES:
+            return span_dict
+
+        logger.warning(
+            f"Span size ({current_size} bytes) exceeds limit ({MAX_SPAN_SIZE_BYTES} bytes). "
+            "Truncating large payload attributes."
+        )
+
+        # Create a deep copy to modify (shallow copy would still reference original attributes)
+        truncated_span = span_dict.copy()
+        if "attributes" in truncated_span:
+            truncated_span["attributes"] = truncated_span["attributes"].copy()
+        attributes = truncated_span.get("attributes", {})
+
+        # Track what was truncated for logging
+        truncated_keys = []
+
+        # Sort attributes by size (largest first) and truncate until size is acceptable
+        if attributes:
+            # Calculate size of each attribute value when serialized
+            attr_sizes = []
+            for key, value in attributes.items():
+                try:
+                    value_size = len(json.dumps(value, separators=(",", ":")).encode("utf-8"))
+                    attr_sizes.append((key, value_size))
+                except Exception:
+                    # If we can't serialize the value, assume it's small
+                    attr_sizes.append((key, 0))
+
+            # Sort by size (descending - largest first)
+            attr_sizes.sort(key=lambda x: x[1], reverse=True)
+
+            # Truncate largest attributes first until size is acceptable
+            for key, _ in attr_sizes:
+                if key in attributes:
+                    attributes[key] = "TRUNCATED"
+                    truncated_keys.append(key)
+
+                    # Check size after truncation
+                    serialized = json.dumps(truncated_span, separators=(",", ":"))
+                    current_size = len(serialized.encode("utf-8"))
+
+                    if current_size <= MAX_SPAN_SIZE_BYTES:
+                        break
+
+        if truncated_keys:
+            logger.info(f"Truncated attributes: {', '.join(truncated_keys)}")
+
+        return truncated_span
+
+    except Exception as e:
+        logger.error(f"Error during span truncation: {e}")
+        return span_dict
+
+
 def partition_by_identity(
     spans: Sequence[ReadableSpan],
 ) -> dict[tuple[str, str], list[ReadableSpan]]:

microsoft_agents_a365/observability/core/invoke_agent_scope.py

@@ -3,6 +3,8 @@
 
 # Invoke agent scope for tracing agent invocation.
 
+import logging
+
 from .agent_details import AgentDetails
 from .constants import (
     GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY,
@@ -10,6 +12,7 @@ from .constants import (
     GEN_AI_CALLER_AGENT_NAME_KEY,
     GEN_AI_CALLER_AGENT_TENANT_ID_KEY,
     GEN_AI_CALLER_AGENT_UPN_KEY,
+    GEN_AI_CALLER_AGENT_USER_CLIENT_IP,
     GEN_AI_CALLER_AGENT_USER_ID_KEY,
     GEN_AI_CALLER_ID_KEY,
     GEN_AI_CALLER_NAME_KEY,
@@ -17,7 +20,6 @@ from .constants import (
     GEN_AI_CALLER_UPN_KEY,
     GEN_AI_CALLER_USER_ID_KEY,
     GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY,
-    GEN_AI_EXECUTION_SOURCE_ID_KEY,
     GEN_AI_EXECUTION_SOURCE_NAME_KEY,
     GEN_AI_EXECUTION_TYPE_KEY,
     GEN_AI_INPUT_MESSAGES_KEY,
@@ -32,7 +34,9 @@ from .models.caller_details import CallerDetails
 from .opentelemetry_scope import OpenTelemetryScope
 from .request import Request
 from .tenant_details import TenantDetails
-from .utils import safe_json_dumps
+from .utils import safe_json_dumps, validate_and_normalize_ip
+
+logger = logging.getLogger(__name__)
 
 
 class InvokeAgentScope(OpenTelemetryScope):
@@ -111,7 +115,6 @@ class InvokeAgentScope(OpenTelemetryScope):
         # Set request metadata if provided
         if request:
             if request.source_metadata:
-                self.set_tag_maybe(GEN_AI_EXECUTION_SOURCE_ID_KEY, request.source_metadata.id)
                 self.set_tag_maybe(GEN_AI_EXECUTION_SOURCE_NAME_KEY, request.source_metadata.name)
                 self.set_tag_maybe(
                     GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY, request.source_metadata.description
@@ -121,6 +124,7 @@ class InvokeAgentScope(OpenTelemetryScope):
                 GEN_AI_EXECUTION_TYPE_KEY,
                 request.execution_type.value if request.execution_type else None,
             )
+            self.set_tag_maybe(GEN_AI_INPUT_MESSAGES_KEY, safe_json_dumps([request.content]))
 
         # Set caller details tags
         if caller_details:
@@ -140,6 +144,11 @@ class InvokeAgentScope(OpenTelemetryScope):
             self.set_tag_maybe(GEN_AI_CALLER_AGENT_USER_ID_KEY, caller_agent_details.agent_auid)
             self.set_tag_maybe(GEN_AI_CALLER_AGENT_UPN_KEY, caller_agent_details.agent_upn)
             self.set_tag_maybe(GEN_AI_CALLER_AGENT_TENANT_ID_KEY, caller_agent_details.tenant_id)
+            # Validate and set caller agent client IP
+            self.set_tag_maybe(
+                GEN_AI_CALLER_AGENT_USER_CLIENT_IP,
+                validate_and_normalize_ip(caller_agent_details.agent_client_ip),
+            )
 
     def record_response(self, response: str) -> None:
         """Record response information for telemetry tracking.

microsoft_agents_a365/observability/core/middleware/baggage_builder.py

@@ -2,6 +2,7 @@
 
 # Per request baggage builder for OpenTelemetry context propagation.
 
+import logging
 from typing import Any
 
 from opentelemetry import baggage, context
@@ -14,20 +15,26 @@ from ..constants import (
     GEN_AI_AGENT_ID_KEY,
     GEN_AI_AGENT_NAME_KEY,
     GEN_AI_AGENT_UPN_KEY,
+    GEN_AI_CALLER_CLIENT_IP_KEY,
     GEN_AI_CALLER_ID_KEY,
     GEN_AI_CALLER_NAME_KEY,
     GEN_AI_CALLER_UPN_KEY,
     GEN_AI_CONVERSATION_ID_KEY,
     GEN_AI_CONVERSATION_ITEM_LINK_KEY,
     GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY,
-    GEN_AI_EXECUTION_SOURCE_ID_KEY,
     GEN_AI_EXECUTION_SOURCE_NAME_KEY,
     HIRING_MANAGER_ID_KEY,
     OPERATION_SOURCE_KEY,
+    SESSION_DESCRIPTION_KEY,
+    SESSION_ID_KEY,
     TENANT_ID_KEY,
 )
+from ..models.operation_source import OperationSource
+from ..utils import deprecated, validate_and_normalize_ip
 from .turn_context_baggage import from_turn_context
 
+logger = logging.getLogger(__name__)
+
 
 class BaggageBuilder:
     """Per request baggage builder.
@@ -50,16 +57,18 @@ class BaggageBuilder:
         """Initialize the baggage builder."""
         self._pairs: dict[str, str] = {}
 
-    def operation_source(self, value: str | None) -> "BaggageBuilder":
+    def operation_source(self, value: OperationSource | None) -> "BaggageBuilder":
         """Set the operation source baggage value.
 
         Args:
-            value: The operation source value
+            value: The operation source enum value
 
         Returns:
             Self for method chaining
         """
-        self._set(OPERATION_SOURCE_KEY, value)
+        # Convert enum to string value for baggage storage
+        str_value = value.value if value is not None else None
+        self._set(OPERATION_SOURCE_KEY, str_value)
         return self
 
     def tenant_id(self, value: str | None) -> "BaggageBuilder":
@@ -178,6 +187,11 @@ class BaggageBuilder:
         self._set(GEN_AI_CALLER_UPN_KEY, value)
         return self
 
+    def caller_client_ip(self, value: str | None) -> "BaggageBuilder":
+        """Set the caller client IP baggage value."""
+        self._set(GEN_AI_CALLER_CLIENT_IP_KEY, validate_and_normalize_ip(value))
+        return self
+
     def conversation_id(self, value: str | None) -> "BaggageBuilder":
         """Set the conversation ID baggage value."""
         self._set(GEN_AI_CONVERSATION_ID_KEY, value)
@@ -188,18 +202,33 @@ class BaggageBuilder:
         self._set(GEN_AI_CONVERSATION_ITEM_LINK_KEY, value)
         return self
 
-    def source_metadata_id(self, value: str | None) -> "BaggageBuilder":
-        """Set the execution source metadata ID (e.g., channel ID)."""
-        self._set(GEN_AI_EXECUTION_SOURCE_ID_KEY, value)
-        return self
-
+    @deprecated("Use channel_name() instead")
     def source_metadata_name(self, value: str | None) -> "BaggageBuilder":
         """Set the execution source metadata name (e.g., channel name)."""
-        self._set(GEN_AI_EXECUTION_SOURCE_NAME_KEY, value)
-        return self
+        return self.channel_name(value)
 
+    @deprecated("Use channel_links() instead")
     def source_metadata_description(self, value: str | None) -> "BaggageBuilder":
         """Set the execution source metadata description (e.g., channel description)."""
+        return self.channel_links(value)
+
+    def session_id(self, value: str | None) -> "BaggageBuilder":
+        """Set the session ID baggage value."""
+        self._set(SESSION_ID_KEY, value)
+        return self
+
+    def session_description(self, value: str | None) -> "BaggageBuilder":
+        """Set the session description baggage value."""
+        self._set(SESSION_DESCRIPTION_KEY, value)
+        return self
+
+    def channel_name(self, value: str | None) -> "BaggageBuilder":
+        """Sets the channel name baggage value (e.g., 'Teams', 'msteams')."""
+        self._set(GEN_AI_EXECUTION_SOURCE_NAME_KEY, value)
+        return self
+
+    def channel_links(self, value: str | None) -> "BaggageBuilder":
+        """Sets the channel link baggage value. (e.g., channel links or description)."""
         self._set(GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY, value)
         return self
 

microsoft_agents_a365/observability/core/middleware/turn_context_baggage.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import json
-from typing import Any, Iterable, Iterator, Mapping
+from typing import Any, Iterator, Mapping
 
 from ..constants import (
     GEN_AI_AGENT_AUID_KEY,
@@ -17,7 +17,6 @@ from ..constants import (
     GEN_AI_CONVERSATION_ID_KEY,
     GEN_AI_CONVERSATION_ITEM_LINK_KEY,
     GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY,
-    GEN_AI_EXECUTION_SOURCE_ID_KEY,
     GEN_AI_EXECUTION_SOURCE_NAME_KEY,
     GEN_AI_EXECUTION_TYPE_KEY,
     TENANT_ID_KEY,
@@ -26,9 +25,6 @@ from ..execution_type import ExecutionType
 
 AGENT_ROLE = "agenticUser"
 CHANNEL_ID_AGENTS = "agents"
-ENTITY_TYPE_WPX_COMMENT = "wpxcomment"
-ENTITY_TYPE_EMAIL_NOTIFICATION = "emailNotification"
-WPX_CONVERSATION_ID_FORMAT = "{document_id}_{parent_comment_id}"
 
 
 def _safe_get(obj: Any, *names: str) -> Any:
@@ -135,37 +131,40 @@ def _iter_tenant_id_pair(activity: Any) -> Iterator[tuple[str, Any]]:
 
 
 def _iter_source_metadata_pairs(activity: Any) -> Iterator[tuple[str, Any]]:
+    """
+    Generate source metadata pairs from activity, handling both string and ChannelId object cases.
+
+    :param activity: The activity object (Activity instance or dict)
+    :return: Iterator of (key, value) tuples for source metadata
+    """
+    # Handle channel_id (can be string or ChannelId object)
     channel_id = _safe_get(activity, "channel_id")
-    yield GEN_AI_EXECUTION_SOURCE_ID_KEY, channel_id
-    yield GEN_AI_EXECUTION_SOURCE_NAME_KEY, channel_id
-    yield GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY, _safe_get(activity, "type", "Type")
+
+    # Extract channel name from either string or ChannelId object
+    channel_name = None
+    sub_channel = None
+
+    if channel_id is not None:
+        if isinstance(channel_id, str):
+            # Direct string value
+            channel_name = channel_id
+        elif hasattr(channel_id, "channel"):
+            # ChannelId object
+            channel_name = channel_id.channel
+            sub_channel = getattr(channel_id, "sub_channel", None)
+        elif isinstance(channel_id, dict):
+            # Serialized ChannelId as dict
+            channel_name = channel_id.get("channel")
+            sub_channel = channel_id.get("sub_channel")
+
+    # Yield channel name as source name
+    yield GEN_AI_EXECUTION_SOURCE_NAME_KEY, channel_name
+    yield GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY, sub_channel
 
 
 def _iter_conversation_pairs(activity: Any) -> Iterator[tuple[str, Any]]:
-    channel_id = _safe_get(activity, "channel_id")
-    entities = _safe_get(activity, "entities") or []
-    conversation_id = None
-
-    if channel_id == CHANNEL_ID_AGENTS and isinstance(entities, Iterable):
-        # search entities for wpxcomment or emailNotification
-        for e in entities:
-            etype = _safe_get(e, "type", "Type")
-            if etype == ENTITY_TYPE_WPX_COMMENT:
-                document_id = _safe_get(e, "documentId", "document_id")
-                parent_comment_id = _safe_get(e, "parentCommentId", "parent_comment_id")
-                if document_id and parent_comment_id:
-                    conversation_id = WPX_CONVERSATION_ID_FORMAT.format(
-                        document_id=document_id,
-                        parent_comment_id=parent_comment_id,
-                    )
-                    break
-            elif etype == ENTITY_TYPE_EMAIL_NOTIFICATION:
-                conversation_id = _safe_get(e, "conversationId", "conversation_id")
-                if conversation_id:
-                    break
-    if not conversation_id:
-        conv = _safe_get(activity, "conversation")
-        conversation_id = _safe_get(conv, "id", "Id")
+    conv = _safe_get(activity, "conversation")
+    conversation_id = _safe_get(conv, "id")
 
     item_link = _safe_get(activity, "service_url")
 

microsoft_agents_a365/observability/core/models/operation_source.py

@@ -0,0 +1,21 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Operation source enumeration for Agent365 SDK."""
+
+from enum import Enum
+
+
+class OperationSource(Enum):
+    """
+    Enumeration representing the source of an operation.
+    """
+
+    SDK = "SDK"
+    """Operation executed by SDK."""
+
+    GATEWAY = "Gateway"
+    """Operation executed by Gateway."""
+
+    MCP_SERVER = "MCPServer"
+    """Operation executed by MCP Server."""

microsoft_agents_a365/observability/core/request.py

@@ -16,4 +16,3 @@ class Request:
     execution_type: ExecutionType
     session_id: str | None = None
     source_metadata: SourceMetadata | None = None
-    payload: str | None = None

microsoft_agents_a365/observability/core/trace_processor/span_processor.py

@@ -16,7 +16,8 @@ For every new span:
 from opentelemetry import baggage, context
 from opentelemetry.sdk.trace import SpanProcessor as BaseSpanProcessor
 
-from ..constants import GEN_AI_OPERATION_NAME_KEY, INVOKE_AGENT_OPERATION_NAME
+from ..constants import GEN_AI_OPERATION_NAME_KEY, INVOKE_AGENT_OPERATION_NAME, OPERATION_SOURCE_KEY
+from ..models.operation_source import OperationSource
 from .util import COMMON_ATTRIBUTES, INVOKE_AGENT_ATTRIBUTES
 
 
@@ -41,6 +42,14 @@ class SpanProcessor(BaseSpanProcessor):
         except Exception:
             baggage_map = {}
 
+        # Set operation source - coalesce baggage value with SDK default
+        if OPERATION_SOURCE_KEY not in existing:
+            operation_source = baggage_map.get(OPERATION_SOURCE_KEY) or OperationSource.SDK.value
+            try:
+                span.set_attribute(OPERATION_SOURCE_KEY, operation_source)
+            except Exception:
+                pass
+
         operation_name = existing.get(GEN_AI_OPERATION_NAME_KEY)
         is_invoke_agent = False
         if operation_name == INVOKE_AGENT_OPERATION_NAME:

microsoft_agents_a365/observability/core/trace_processor/util.py

@@ -19,6 +19,13 @@ COMMON_ATTRIBUTES = [
     consts.GEN_AI_AGENT_BLUEPRINT_ID_KEY,  # gen_ai.agent.applicationid
     consts.GEN_AI_AGENT_AUID_KEY,
     consts.GEN_AI_AGENT_TYPE_KEY,
+    consts.OPERATION_SOURCE_KEY,  # operation.source
+    consts.SESSION_ID_KEY,
+    consts.SESSION_DESCRIPTION_KEY,
+    consts.HIRING_MANAGER_ID_KEY,
+    # Execution context
+    consts.GEN_AI_EXECUTION_SOURCE_NAME_KEY,  # gen_ai.channel.name
+    consts.GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY,  # gen_ai.channel.link
 ]
 
 # Invoke Agent–specific attributes
@@ -36,9 +43,5 @@ INVOKE_AGENT_ATTRIBUTES = [
     consts.GEN_AI_CALLER_AGENT_UPN_KEY,  # gen_ai.caller.agent.upn
     consts.GEN_AI_CALLER_AGENT_TENANT_ID_KEY,  # gen_ai.caller.agent.tenantid
     consts.GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY,  # gen_ai.caller.agent.applicationid
-    # Execution context
     consts.GEN_AI_EXECUTION_TYPE_KEY,  # gen_ai.execution.type
-    consts.GEN_AI_EXECUTION_SOURCE_ID_KEY,  # gen_ai.execution.sourceMetadata.id
-    consts.GEN_AI_EXECUTION_SOURCE_NAME_KEY,  # gen_ai.execution.sourceMetadata.name
-    consts.GEN_AI_EXECUTION_SOURCE_DESCRIPTION_KEY,  # gen_ai.execution.sourceMetadata.description
 ]

microsoft_agents_a365/observability/core/utils.py

@@ -1,15 +1,22 @@
-# Copyright (c) Microsoft. All rights reserved.
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
 
 import datetime
+import functools
 import json
 import logging
 import traceback
+import warnings
 from collections.abc import Callable, Hashable, Iterable, Iterator, Mapping
 from enum import Enum
+from ipaddress import AddressValueError, ip_address
 from threading import RLock
 from typing import Any, Generic, TypeVar, cast
 
-from opentelemetry.semconv.trace import SpanAttributes as OTELSpanAttributes
+from opentelemetry.semconv.attributes.exception_attributes import (
+    EXCEPTION_MESSAGE,
+    EXCEPTION_STACKTRACE,
+)
 from opentelemetry.trace import Span
 from opentelemetry.util.types import AttributeValue
 from wrapt import ObjectProxy
@@ -69,10 +76,10 @@ def record_exception(span: Span, error: BaseException) -> None:
         exception_message = repr(error)
     attributes: dict[str, AttributeValue] = {
         ERROR_TYPE_KEY: exception_type,
-        OTELSpanAttributes.EXCEPTION_MESSAGE: exception_message,
+        EXCEPTION_MESSAGE: exception_message,
     }
     try:
-        attributes[OTELSpanAttributes.EXCEPTION_STACKTRACE] = traceback.format_exc()
+        attributes[EXCEPTION_STACKTRACE] = traceback.format_exc()
     except Exception:
         logger.exception("Failed to record exception stacktrace.")
     span.add_event(name="exception", attributes=attributes)
@@ -149,3 +156,45 @@ def extract_model_name(span_name: str) -> str | None:
         return model_name.strip()
 
     return None
+
+
+def deprecated(reason: str):
+    """Decorator to mark functions as deprecated."""
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f"{func.__name__}() is deprecated. {reason}",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def validate_and_normalize_ip(ip_string: str | None) -> str | None:
+    """Validate and normalize an IP address string.
+
+    Args:
+        ip_string: The IP address string to validate (IPv4 or IPv6)
+
+    Returns:
+        The normalized IP address string if valid, None if invalid or None input
+
+    Logs:
+        Error message if the IP address is invalid
+    """
+    if ip_string is None:
+        return None
+
+    try:
+        # Validate and normalize IP address
+        ip_obj = ip_address(ip_string)
+        return str(ip_obj)
+    except (ValueError, AddressValueError):
+        logger.error(f"Invalid IP address: '{ip_string}'")
+        return None

{microsoft_agents_a365_observability_core-0.1.0.dist-info → microsoft_agents_a365_observability_core-0.2.0.dev5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-a365-observability-core
-Version: 0.1.0
+Version: 0.2.0.dev5
 Summary: Telemetry, tracing, and monitoring components for AI agents
 Author-email: Microsoft <support@microsoft.com>
 License: MIT
@@ -64,7 +64,7 @@ For usage examples and detailed documentation, see the [Observability documentat
 For issues, questions, or feedback:
 
 - File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section
-- See the [main documentation](../../../README.md) for more information
+- See the [main documentation](../../README.md) for more information
  
 ## Trademarks
  
@@ -74,5 +74,5 @@ For issues, questions, or feedback:
 
 Copyright (c) Microsoft Corporation. All rights reserved.
 
-Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details.
+Licensed under the MIT License - see the [LICENSE](../../LICENSE.md) file for details.
 

{microsoft_agents_a365_observability_core-0.1.0.dist-info → microsoft_agents_a365_observability_core-0.2.0.dev5.dist-info}/RECORD

@@ -1,33 +1,35 @@
 microsoft_agents_a365/observability/core/__init__.py,sha256=1-Jmokc2cQv7p_RB7W22ZEdqQ0Doq8yDENx_Yews2p8,1737
-microsoft_agents_a365/observability/core/agent_details.py,sha256=U0xgrtrnNXrI8yjmBk7teXuMCvIIk0zWEOti_RvJP1o,1147
-microsoft_agents_a365/observability/core/config.py,sha256=-sCfRUQNSk2XHnh-Ez1DSVrXS2vHr_2YD-lZ8byyFjk,8828
-microsoft_agents_a365/observability/core/constants.py,sha256=K__ga_vnsqrOIVzPtW4gWeu8xLJnAxJdkmbMzYYwPXY,4614
+microsoft_agents_a365/observability/core/agent_details.py,sha256=7x4tqcocig1hz4T6eCRZy7fSF2gOCpM0pvE6Q3Txww0,1210
+microsoft_agents_a365/observability/core/config.py,sha256=BK1Yg2ykt5yYUBmA-z_wKy2H4k8UB6InF4C5Xh8ZM-g,10996
+microsoft_agents_a365/observability/core/constants.py,sha256=sypi1CXrTX5lX-19qQTq6VL6CZ691w5-gFVh5W6OpbY,4722
 microsoft_agents_a365/observability/core/execute_tool_scope.py,sha256=RcibM_Q-lEhSOpAoRioDao-HiC72W741-SCbcPDWqyI,2989
 microsoft_agents_a365/observability/core/execution_type.py,sha256=Qsf-7_7DzZnRQZ5NHYU31ggfxAjPwneNnda1hOodmG0,303
 microsoft_agents_a365/observability/core/inference_call_details.py,sha256=V1-KQPNq0V36J91ptX96UNRcOW6cy-AV5eIlwbzsrSg,483
 microsoft_agents_a365/observability/core/inference_operation_type.py,sha256=ZLdDdYC0V_0Sff_aTSaiIRVB4a9wEduS7EXpYlme6_M,273
 microsoft_agents_a365/observability/core/inference_scope.py,sha256=87r367uQ4qVp8NpR0na-uQScRR5ID1FlP6c3cmIxvMc,4973
 microsoft_agents_a365/observability/core/invoke_agent_details.py,sha256=PEwkJq-nUz8sxLsbz44hIydGHiO2tHj-sVBkMpZXC1A,389
-microsoft_agents_a365/observability/core/invoke_agent_scope.py,sha256=NJSeKeNmvutn_MZARIGSg80n7HxTW3BazqyXw-9LFlY,6600
+microsoft_agents_a365/observability/core/invoke_agent_scope.py,sha256=A2syvvT9lUE1x7M1Ns7DuXY0J4STMiOBe7kGmPpyLmQ,6917
 microsoft_agents_a365/observability/core/opentelemetry_scope.py,sha256=I8WQoQkCygC7jZRrP2aHsJScGqQKDVktLlRGxApfiZo,9734
-microsoft_agents_a365/observability/core/request.py,sha256=fcqsmxPl0BMITwbvy5lK5DkDm5YjIXKIwlJTclcdMCs,430
+microsoft_agents_a365/observability/core/request.py,sha256=x9kRlUbbaK0btsJ8Ym-Ctp5jgsiy54b3eMPst7Olirk,399
 microsoft_agents_a365/observability/core/source_metadata.py,sha256=ijMIiJGvfepDnBqSuZbGsjvrTivz3f_Ub1azyZsCeMA,321
 microsoft_agents_a365/observability/core/tenant_details.py,sha256=eC5S9Zq5sJrpGFWJLKBXVlj-OipysPSoLKSl-8I5YY0,218
 microsoft_agents_a365/observability/core/tool_call_details.py,sha256=sPDW5yvey9_itpKxoo76pwoncOZyhONt9fy3cDdSYyY,455
 microsoft_agents_a365/observability/core/tool_type.py,sha256=O9snmopwdhBjK5eqwyQU3aSdLZzX88c1UMi7oW7lFHg,271
-microsoft_agents_a365/observability/core/utils.py,sha256=PkoB6J65HhRbiFU2uz_WMn5XHLiRbtvPWzkMWe5Vkos,4850
-microsoft_agents_a365/observability/core/exporters/agent365_exporter.py,sha256=j_u0fykKK7BY0sg1PsEFE4ABoU4HPwEJMjeZ_KZ1fhk,11386
-microsoft_agents_a365/observability/core/exporters/utils.py,sha256=6G09FlUmtpq57415QQal22AMJQi21IZqBE8_4No_Qfg,1877
+microsoft_agents_a365/observability/core/utils.py,sha256=fnZBCEsD-1FlxpJ5hcbwovrEK4baeSKOyKJADSD3n3Q,6063
+microsoft_agents_a365/observability/core/exporters/agent365_exporter.py,sha256=lhicYBnuoDL9RrvGOADEefKV8JCoJd9ChcFn5XS8YjM,11488
+microsoft_agents_a365/observability/core/exporters/agent365_exporter_options.py,sha256=f-p11ZQfxtDIiK-kVPDfebBgT83onxdE29IQryYoAPk,1648
+microsoft_agents_a365/observability/core/exporters/utils.py,sha256=VHhZOELtZtsNEFYcCA-rb7JNX9_aDcJ9XC6OhVIBjl8,4646
 microsoft_agents_a365/observability/core/middleware/__init__.py,sha256=v_vLyv0BQOW9pAvuUeL6Q0ZQ3Ji4MdYYcFDfP7CqvMk,177
-microsoft_agents_a365/observability/core/middleware/baggage_builder.py,sha256=RCdaOuXO6T_5zFP1K_xukTuibee2CIIQmYuvvFjXtNw,9538
-microsoft_agents_a365/observability/core/middleware/turn_context_baggage.py,sha256=6IuS8SLbM-W-G5FgHncBurXi9fF-hRaFHjI78Bh3qsI,6698
+microsoft_agents_a365/observability/core/middleware/baggage_builder.py,sha256=F1HcLKEA4-h1tjfp0AgXMqIsEn58waP6nvyChvo-cAI,10752
+microsoft_agents_a365/observability/core/middleware/turn_context_baggage.py,sha256=teDtlB38zKKdTynYaV9egI3G8wShgCw4KSPxzukSrmQ,6326
 microsoft_agents_a365/observability/core/models/__init__.py,sha256=aCOr6sEsQpv9z4cJgWFA4qOs4xJqclqYYnxOVcxiK2Q,75
 microsoft_agents_a365/observability/core/models/agent_type.py,sha256=ZazwwMAQRrYzzN3Ytz69F6thV4R6nemA6JrK-70fyt0,560
 microsoft_agents_a365/observability/core/models/caller_details.py,sha256=8oaRKeGNteZq_RAQShhfUBs0iO-Sr9yjfk13Mv-xSjA,674
+microsoft_agents_a365/observability/core/models/operation_source.py,sha256=HJp-SNR-lNSPIgoLlF6DMMlijtu4ZGhnqSyu58lIgnk,448
 microsoft_agents_a365/observability/core/trace_processor/__init__.py,sha256=GML9CA7ssJPngxpGFPdVlp-0NmhgS4Ke9IGW5vm5Gys,194
-microsoft_agents_a365/observability/core/trace_processor/span_processor.py,sha256=9Sou0m1huEncNcGdU-ThE8b9uPwHosZNSPdldOUdlkU,2513
-microsoft_agents_a365/observability/core/trace_processor/util.py,sha256=-jM4ei60f5HKEDAVvBlZiTmhMhq8hVvvt4SwGgEnPuI,2239
-microsoft_agents_a365_observability_core-0.1.0.dist-info/METADATA,sha256=MBThT80LmnRbrnUkb90Wyvau2hXUlTu2KilAapZTd9I,3872
-microsoft_agents_a365_observability_core-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-microsoft_agents_a365_observability_core-0.1.0.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
-microsoft_agents_a365_observability_core-0.1.0.dist-info/RECORD,,
+microsoft_agents_a365/observability/core/trace_processor/span_processor.py,sha256=4gEvm8gcf7_A-Fty-InBc2wJG80WCvn8Sh7GKBuFYzU,2953
+microsoft_agents_a365/observability/core/trace_processor/util.py,sha256=xoBZ7qbucZGYJCKgKylaUrl0tP34bcd34fgmh8sXZ_E,2270
+microsoft_agents_a365_observability_core-0.2.0.dev5.dist-info/METADATA,sha256=OGU05eHdSN_0kiUd9CM2xJqE6iI9XOZqBe5mMcNln3k,3871
+microsoft_agents_a365_observability_core-0.2.0.dev5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_a365_observability_core-0.2.0.dev5.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_observability_core-0.2.0.dev5.dist-info/RECORD,,