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

microsoft_agents_a365/observability/core/__init__.py

@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+# Microsoft Agent 365 Python SDK for OpenTelemetry tracing.
+
+from .agent_details import AgentDetails
+from .config import (
+    configure,
+    get_tracer,
+    get_tracer_provider,
+    is_configured,
+)
+from .execute_tool_scope import ExecuteToolScope
+from .execution_type import ExecutionType
+from .inference_call_details import InferenceCallDetails
+from .inference_operation_type import InferenceOperationType
+from .inference_scope import InferenceScope
+from .invoke_agent_details import InvokeAgentDetails
+from .invoke_agent_scope import InvokeAgentScope
+from .middleware.baggage_builder import BaggageBuilder
+from .opentelemetry_scope import OpenTelemetryScope
+from .request import Request
+from .source_metadata import SourceMetadata
+from .tenant_details import TenantDetails
+from .tool_call_details import ToolCallDetails
+from .tool_type import ToolType
+from .trace_processor.span_processor import SpanProcessor
+
+__all__ = [
+    # Main SDK functions
+    "configure",
+    "is_configured",
+    "get_tracer",
+    "get_tracer_provider",
+    # Span processor
+    "SpanProcessor",
+    # Base scope class
+    "OpenTelemetryScope",
+    # Specific scope classes
+    "ExecuteToolScope",
+    "InvokeAgentScope",
+    "InferenceScope",
+    # Middleware
+    "BaggageBuilder",
+    # Data classes
+    "InvokeAgentDetails",
+    "AgentDetails",
+    "TenantDetails",
+    "ToolCallDetails",
+    "SourceMetadata",
+    "Request",
+    "InferenceCallDetails",
+    # Enums
+    "ExecutionType",
+    "InferenceOperationType",
+    "ToolType",
+    # Constants
+    # all constants from constants.py are exported via *
+]
+
+# This is a namespace package
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

microsoft_agents_a365/observability/core/agent_details.py

@@ -0,0 +1,42 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .models.agent_type import AgentType
+
+
+@dataclass
+class AgentDetails:
+    """Details about an AI agent in the system."""
+
+    agent_id: str
+    """The unique identifier for the AI agent."""
+
+    agent_name: Optional[str] = None
+    """The human-readable name of the AI agent."""
+
+    agent_description: Optional[str] = None
+    """A description of the AI agent's purpose or capabilities."""
+
+    agent_auid: Optional[str] = None
+    """Optional Agent User ID for the agent."""
+
+    agent_upn: Optional[str] = None
+    """Optional User Principal Name (UPN) for the agent."""
+
+    agent_blueprint_id: Optional[str] = None
+    """Optional 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."""
+
+    conversation_id: Optional[str] = None
+    """Optional conversation ID for compatibility."""
+
+    icon_uri: Optional[str] = None
+    """Optional icon URI for the agent."""

microsoft_agents_a365/observability/core/config.py

@@ -0,0 +1,246 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import threading
+from collections.abc import Callable
+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 .exporters.agent365_exporter import Agent365Exporter
+from .exporters.utils import is_agent365_exporter_enabled
+from .trace_processor.span_processor import SpanProcessor
+
+DEFAULT_LOGGER_NAME = __name__
+
+
+class TelemetryManager:
+    """
+    Thread-safe singleton manager for telemetry operations.
+
+    This class encapsulates all telemetry state and operations, providing
+    a clean interface for configuration, flushing, and shutdown without
+    relying on global variables.
+    """
+
+    _instance: Optional["TelemetryManager"] = None
+    _lock = threading.Lock()
+
+    def __new__(cls) -> "TelemetryManager":
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self):
+        if not getattr(self, "_initialized", False):
+            self._tracer_provider: TracerProvider | None = None
+            self._span_processors: dict[str, Any] = {}
+            self._logger = logging.getLogger(__name__)
+            self._initialized = True
+
+    def configure(
+        self,
+        service_name: str,
+        service_namespace: str,
+        logger_name: str = DEFAULT_LOGGER_NAME,
+        token_resolver: Callable[[str, str], str | None] | None = None,
+        cluster_category: str = "prod",
+        **kwargs: Any,
+    ) -> bool:
+        """
+        Configure telemetry.
+
+        :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").
+        :return: True if configuration succeeded, False otherwise.
+        """
+        try:
+            with self._lock:
+                return self._configure_internal(
+                    service_name,
+                    service_namespace,
+                    logger_name,
+                    token_resolver,
+                    cluster_category,
+                    **kwargs,
+                )
+        except Exception as e:
+            self._logger.error(f"❌ Failed to configure telemetry: {e}")
+            return False
+
+    def _configure_internal(
+        self,
+        service_name: str,
+        service_namespace: str,
+        logger_name: str,
+        token_resolver: Callable[[str, str], str | None] | None = None,
+        cluster_category: str = "prod",
+        **kwargs: Any,
+    ) -> bool:
+        """Internal configuration method - not thread-safe, must be called with lock."""
+
+        # Create resource with service information
+        resource = Resource.create(
+            {
+                SERVICE_NAMESPACE: service_namespace,
+                SERVICE_NAME: service_name,
+            }
+        )
+
+        # Get existing tracer provider or create new one
+        try:
+            tracer_provider = trace.get_tracer_provider()
+            # Check if it's already configured
+            if hasattr(tracer_provider, "resource") and tracer_provider.resource:
+                # Already configured, just add our span processor
+                agent_processor = SpanProcessor()
+                tracer_provider.add_span_processor(agent_processor)
+                self._tracer_provider = tracer_provider
+                self._span_processors["agent"] = agent_processor
+                return True
+        except Exception:
+            pass
+
+        # Configure tracer provider
+        tracer_provider = TracerProvider(resource=resource)
+        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,
+                cluster_category=cluster_category,
+                **kwargs,
+            )
+        else:
+            exporter = ConsoleSpanExporter()
+            self._logger.warning(
+                "is_agent365_exporter_enabled() not enabled or token_resolver not set.Falling back to console exporter."
+            )
+
+        # Add span processors
+
+        # Create BatchSpanProcessor with optimized settings
+        batch_processor = BatchSpanProcessor(exporter)
+        agent_processor = SpanProcessor()
+
+        tracer_provider.add_span_processor(batch_processor)
+        tracer_provider.add_span_processor(agent_processor)
+
+        # Store references for cleanup
+        self._span_processors["batch"] = batch_processor
+        self._span_processors["agent"] = agent_processor
+
+        # Configure logging if logger_name is provided
+        if logger_name:
+            target_logger = logging.getLogger(logger_name)
+            target_logger.setLevel(logging.INFO)
+
+        return True
+
+    def is_configured(self) -> bool:
+        """Check if the telemetry manager is configured."""
+        return self._tracer_provider is not None
+
+    def get_tracer(self, name: str | None = None, version: str | None = None):
+        """
+        Return an OpenTelemetry Tracer tied to the TracerProvider configured by agent365.
+
+        If the telemetry manager is not configured yet, this returns the default
+        (no-op) tracer from OpenTelemetry and logs a warning. Callers should prefer
+        to call `configure(...)` during application startup so the tracer
+        returned is backed by the configured TracerProvider.
+
+        :param name: Optional tracer name. Defaults to 'microsoft_agents_a365.observability.core' when not provided.
+        :param version: Optional tracer version.
+        :return: An OpenTelemetry Tracer instance.
+        """
+        tracer_name = name or DEFAULT_LOGGER_NAME
+        if self._tracer_provider is None:
+            # Not configured — return whatever tracer OpenTelemetry provides (no-op)
+            self._logger.warning(
+                "agent365 telemetry not configured; returning a no-op tracer for '%s'", tracer_name
+            )
+            return trace.get_tracer(tracer_name, version)
+
+        # Ensure global tracer provider is set (should already be by configure)
+        try:
+            return trace.get_tracer(tracer_name, version)
+        except Exception as e:
+            self._logger.error("Failed to get tracer '%s': %s", tracer_name, e)
+            return trace.get_tracer(tracer_name, version)
+
+    def get_tracer_provider(self):
+        """
+        Return the configured TracerProvider instance.
+        """
+        return self._tracer_provider
+
+
+# Singleton instance
+_telemetry_manager = TelemetryManager()
+
+
+# Public API functions that delegate to the singleton manager
+def configure(
+    service_name: str,
+    service_namespace: str,
+    logger_name: str = DEFAULT_LOGGER_NAME,
+    token_resolver: Callable[[str, str], str | None] | None = None,
+    cluster_category: str = "prod",
+    **kwargs: Any,
+) -> bool:
+    """
+    Configure telemetry with OpenTelemetry.
+
+    :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.
+    :return: True if configuration succeeded, False otherwise.
+    """
+    return _telemetry_manager.configure(
+        service_name,
+        service_namespace,
+        logger_name,
+        token_resolver,
+        cluster_category,
+        **kwargs,
+    )
+
+
+def is_configured() -> bool:
+    """
+    Check if telemetry is currently configured.
+
+    :return: True if telemetry is configured and ready to use, False otherwise
+    """
+    return _telemetry_manager.is_configured()
+
+
+def get_tracer(name: str | None = None, version: str | None = None):
+    """
+    Return a tracer tied to the TracerProvider configured by the SDK.
+
+    :param name: Optional tracer name. If omitted, defaults to 'microsoft_agents_a365.observability.core'.
+    :param version: Optional tracer version.
+    :return: An OpenTelemetry Tracer (may be a no-op tracer if SDK isn't configured).
+    """
+    return _telemetry_manager.get_tracer(name, version)
+
+
+def get_tracer_provider():
+    """
+    Return the TracerProvider configured by the SDK.
+
+    :return: Configured OpenTelemetry TracerProvider
+    """
+    return _telemetry_manager.get_tracer_provider()

microsoft_agents_a365/observability/core/constants.py

@@ -0,0 +1,107 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+# Constants for SDK OpenTelemetry implementation.
+
+# Span operation names
+INVOKE_AGENT_OPERATION_NAME = "invoke_agent"
+EXECUTE_TOOL_OPERATION_NAME = "execute_tool"
+
+# OpenTelemetry semantic conventions
+ERROR_TYPE_KEY = "error.type"
+ERROR_MESSAGE_KEY = "error.message"
+AZ_NAMESPACE_KEY = "az.namespace"
+SERVER_ADDRESS_KEY = "server.address"
+SERVER_PORT_KEY = "server.port"
+AZURE_RP_NAMESPACE_VALUE = "Microsoft.CognitiveServices"
+SOURCE_NAME = "Agent365Sdk"
+ENABLE_OPENTELEMETRY_SWITCH = "Azure.Experimental.EnableActivitySource"
+TRACE_CONTENTS_SWITCH = "Azure.Experimental.TraceGenAIMessageContent"
+TRACE_CONTENTS_ENVIRONMENT_VARIABLE = "AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"
+ENABLE_OBSERVABILITY = "ENABLE_OBSERVABILITY"
+ENABLE_A365_OBSERVABILITY_EXPORTER = "ENABLE_A365_OBSERVABILITY_EXPORTER"
+ENABLE_A365_OBSERVABILITY = "ENABLE_A365_OBSERVABILITY"
+
+# GenAI semantic conventions
+GEN_AI_CLIENT_OPERATION_DURATION_METRIC_NAME = "gen_ai.client.operation.duration"
+GEN_AI_CLIENT_TOKEN_USAGE_METRIC_NAME = "gen_ai.client.token.usage"
+GEN_AI_OPERATION_NAME_KEY = "gen_ai.operation.name"
+GEN_AI_REQUEST_MAX_TOKENS_KEY = "gen_ai.request.max_tokens"
+GEN_AI_REQUEST_MODEL_KEY = "gen_ai.request.model"
+GEN_AI_REQUEST_TEMPERATURE_KEY = "gen_ai.request.temperature"
+GEN_AI_REQUEST_TOP_P_KEY = "gen_ai.request.top_p"
+GEN_AI_RESPONSE_ID_KEY = "gen_ai.response.id"
+GEN_AI_RESPONSE_FINISH_REASONS_KEY = "gen_ai.response.finish_reasons"
+GEN_AI_RESPONSE_MODEL_KEY = "gen_ai.response.model"
+GEN_AI_SYSTEM_KEY = "gen_ai.system"
+GEN_AI_SYSTEM_VALUE = "az.ai.agent365"
+GEN_AI_THOUGHT_PROCESS_KEY = "gen_ai.agent.thought.process"
+
+GEN_AI_AGENT_ID_KEY = "gen_ai.agent.id"
+GEN_AI_AGENT_NAME_KEY = "gen_ai.agent.name"
+GEN_AI_AGENT_DESCRIPTION_KEY = "gen_ai.agent.description"
+GEN_AI_CONVERSATION_ID_KEY = "gen_ai.conversation.id"
+GEN_AI_CONVERSATION_ITEM_LINK_KEY = "gen_ai.conversation.item.link"
+GEN_AI_TOKEN_TYPE_KEY = "gen_ai.token.type"
+GEN_AI_USAGE_INPUT_TOKENS_KEY = "gen_ai.usage.input_tokens"
+GEN_AI_USAGE_OUTPUT_TOKENS_KEY = "gen_ai.usage.output_tokens"
+GEN_AI_CHOICE = "gen_ai.choice"
+GEN_AI_PROVIDER_NAME_KEY = "gen_ai.provider.name"
+GEN_AI_AGENT_TYPE_KEY = "gen_ai.agent.type"
+
+GEN_AI_SYSTEM_INSTRUCTIONS_KEY = "gen_ai.system_instructions"
+GEN_AI_INPUT_MESSAGES_KEY = "gen_ai.input.messages"
+GEN_AI_OUTPUT_MESSAGES_KEY = "gen_ai.output.messages"
+GEN_AI_EVENT_CONTENT = "gen_ai.event.content"
+
+# Tool execution constants
+GEN_AI_TOOL_CALL_ID_KEY = "gen_ai.tool.call.id"
+GEN_AI_TOOL_NAME_KEY = "gen_ai.tool.name"
+GEN_AI_TOOL_DESCRIPTION_KEY = "gen_ai.tool.description"
+GEN_AI_TOOL_ARGS_KEY = "gen_ai.tool.arguments"
+GEN_AI_TOOL_CALL_RESULT_KEY = GEN_AI_EVENT_CONTENT  # GEN_AI_EVENT_CONTENT
+GEN_AI_TOOL_TYPE_KEY = "gen_ai.tool.type"
+
+# Agent user(user tied to agent instance during creation) or caller dimensions
+GEN_AI_AGENT_USER_ID_KEY = "gen_ai.agent.userid"
+GEN_AI_CALLER_USER_ID_KEY = "gen_ai.caller.userid"
+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"
+
+# Agent to Agent caller agent dimensions
+GEN_AI_CALLER_AGENT_USER_ID_KEY = "gen_ai.caller.agent.userid"
+GEN_AI_CALLER_AGENT_UPN_KEY = "gen_ai.caller.agent.upn"
+GEN_AI_CALLER_AGENT_TENANT_ID_KEY = "gen_ai.caller.agent.tenantid"
+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"
+
+# Agent-specific dimensions
+AGENT_ID_KEY = "gen_ai.agent.id"
+GEN_AI_TASK_ID_KEY = "gen_ai.task.id"
+SESSION_ID_KEY = "session.id"
+GEN_AI_ICON_URI_KEY = "gen_ai.agent365.icon_uri"
+TENANT_ID_KEY = "tenant.id"
+
+# Baggage keys
+OPERATION_SOURCE_KEY = "operation.source"
+GEN_AI_AGENT_AUID_KEY = "gen_ai.agent.user.id"
+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"
+
+# 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"
+
+# custom parent id and parent name key
+CUSTOM_PARENT_SPAN_ID_KEY = "custom.parent.span.id"
+CUSTOM_SPAN_NAME_KEY = "custom.span.name"

microsoft_agents_a365/observability/core/execute_tool_scope.py

@@ -0,0 +1,88 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from .agent_details import AgentDetails
+from .constants import (
+    EXECUTE_TOOL_OPERATION_NAME,
+    GEN_AI_EVENT_CONTENT,
+    GEN_AI_TOOL_ARGS_KEY,
+    GEN_AI_TOOL_CALL_ID_KEY,
+    GEN_AI_TOOL_DESCRIPTION_KEY,
+    GEN_AI_TOOL_NAME_KEY,
+    GEN_AI_TOOL_TYPE_KEY,
+    SERVER_ADDRESS_KEY,
+    SERVER_PORT_KEY,
+)
+from .opentelemetry_scope import OpenTelemetryScope
+from .tenant_details import TenantDetails
+from .tool_call_details import ToolCallDetails
+
+
+class ExecuteToolScope(OpenTelemetryScope):
+    """Provides OpenTelemetry tracing scope for AI tool execution operations."""
+
+    @staticmethod
+    def start(
+        details: ToolCallDetails,
+        agent_details: AgentDetails,
+        tenant_details: TenantDetails,
+    ) -> "ExecuteToolScope":
+        """Creates and starts a new scope for tool execution tracing.
+
+        Args:
+            details: The details of the tool call
+            agent_details: The details of the agent making the call
+            tenant_details: The details of the tenant
+
+        Returns:
+            A new ExecuteToolScope instance
+        """
+        return ExecuteToolScope(details, agent_details, tenant_details)
+
+    def __init__(
+        self,
+        details: ToolCallDetails,
+        agent_details: AgentDetails,
+        tenant_details: TenantDetails,
+    ):
+        """Initialize the tool execution scope.
+
+        Args:
+            details: The details of the tool call
+            agent_details: The details of the agent making the call
+            tenant_details: The details of the tenant
+        """
+        super().__init__(
+            kind="Internal",
+            operation_name=EXECUTE_TOOL_OPERATION_NAME,
+            activity_name=f"{EXECUTE_TOOL_OPERATION_NAME} {details.tool_name}",
+            agent_details=agent_details,
+            tenant_details=tenant_details,
+        )
+
+        # Extract details using deconstruction-like approach
+        tool_name = details.tool_name
+        arguments = details.arguments
+        tool_call_id = details.tool_call_id
+        description = details.description
+        tool_type = details.tool_type
+        endpoint = details.endpoint
+
+        self.set_tag_maybe(GEN_AI_TOOL_NAME_KEY, tool_name)
+        self.set_tag_maybe(GEN_AI_TOOL_ARGS_KEY, arguments)
+        self.set_tag_maybe(GEN_AI_TOOL_TYPE_KEY, tool_type)
+        self.set_tag_maybe(GEN_AI_TOOL_CALL_ID_KEY, tool_call_id)
+        self.set_tag_maybe(GEN_AI_TOOL_DESCRIPTION_KEY, description)
+
+        if endpoint:
+            self.set_tag_maybe(SERVER_ADDRESS_KEY, endpoint.hostname)
+            if endpoint.port and endpoint.port != 443:
+                self.set_tag_maybe(SERVER_PORT_KEY, endpoint.port)
+
+    def record_response(self, response: str) -> None:
+        """Records response information for telemetry tracking.
+
+        Args:
+            response: The response to record
+        """
+        self.set_tag_maybe(GEN_AI_EVENT_CONTENT, response)

microsoft_agents_a365/observability/core/execution_type.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+# Execution type enum.
+
+from enum import Enum
+
+
+class ExecutionType(Enum):
+    """Enumeration for different types of agent execution contexts."""
+
+    AGENT_TO_AGENT = "Agent2Agent"
+    EVENT_TO_AGENT = "EventToAgent"
+    HUMAN_TO_AGENT = "HumanToAgent"