microsoft-opentelemetry 0.1.0a1__py3-none-any.whl

microsoft/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

microsoft/agents/a365/observability/__init__.py

@@ -0,0 +1,19 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""Agent365 exporter integration for the Microsoft OpenTelemetry Distro."""
+
+from microsoft.agents.a365.observability.core.exporters.utils import (  # noqa: F401
+    A365Handlers,
+    create_a365_components,
+    is_a365_enabled,
+)
+
+__all__ = [
+    "A365Handlers",
+    "create_a365_components",
+    "is_a365_enabled",
+]

microsoft/agents/a365/observability/constants.py

@@ -0,0 +1,133 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""Constants for Agent365 observability.
+
+Superset of microsoft-agents-a365-observability-core constants plus
+distro-specific environment variable constants.
+"""
+
+# --- Span operation names ---
+INVOKE_AGENT_OPERATION_NAME = "invoke_agent"
+EXECUTE_TOOL_OPERATION_NAME = "execute_tool"
+OUTPUT_MESSAGES_OPERATION_NAME = "output_messages"
+CHAT_OPERATION_NAME = "chat"
+
+# --- OpenTelemetry semantic conventions ---
+ERROR_TYPE_KEY = "error.type"
+ERROR_MESSAGE_KEY = "error.message"
+AZ_NAMESPACE_KEY = "az.namespace"
+AZURE_RP_NAMESPACE_VALUE = "Microsoft.CognitiveServices"
+SOURCE_NAME = "Agent365Sdk"
+
+# --- Feature switches ---
+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 = "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_FINISH_REASONS_KEY = "gen_ai.response.finish_reasons"
+GEN_AI_RESPONSE_MODEL_KEY = "gen_ai.response.model"
+GEN_AI_RESPONSE_ID_KEY = "gen_ai.response.id"
+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_AGENT_VERSION_KEY = "gen_ai.agent.version"
+GEN_AI_AGENT_PLATFORM_ID_KEY = "microsoft.a365.agent.platform.id"
+GEN_AI_AGENT_THOUGHT_PROCESS_KEY = "microsoft.a365.agent.thought.process"
+GEN_AI_CONVERSATION_ID_KEY = "gen_ai.conversation.id"
+GEN_AI_CONVERSATION_ITEM_LINK_KEY = "microsoft.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_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"
+
+# --- Tool execution ---
+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.call.arguments"
+GEN_AI_TOOL_CALL_RESULT_KEY = "gen_ai.tool.call.result"
+GEN_AI_TOOL_TYPE_KEY = "gen_ai.tool.type"
+
+# --- Human caller ---
+USER_ID_KEY = "user.id"
+USER_NAME_KEY = "user.name"
+USER_EMAIL_KEY = "user.email"
+GEN_AI_CALLER_CLIENT_IP_KEY = "client.address"
+
+# --- Agent-to-Agent caller ---
+GEN_AI_CALLER_AGENT_USER_ID_KEY = "microsoft.a365.caller.agent.user.id"
+GEN_AI_CALLER_AGENT_EMAIL_KEY = "microsoft.a365.caller.agent.user.email"
+GEN_AI_CALLER_AGENT_NAME_KEY = "microsoft.a365.caller.agent.name"
+GEN_AI_CALLER_AGENT_ID_KEY = "microsoft.a365.caller.agent.id"
+GEN_AI_CALLER_AGENT_APPLICATION_ID_KEY = "microsoft.a365.caller.agent.blueprint.id"
+GEN_AI_CALLER_AGENT_PLATFORM_ID_KEY = "microsoft.a365.caller.agent.platform.id"
+GEN_AI_CALLER_AGENT_VERSION_KEY = "microsoft.a365.caller.agent.version"
+
+# --- Agent-specific dimensions ---
+AGENT_ID_KEY = "gen_ai.agent.id"
+GEN_AI_TASK_ID_KEY = "gen_ai.task.id"
+GEN_AI_ICON_URI_KEY = "gen_ai.agent365.icon_uri"
+GEN_AI_EXECUTION_PAYLOAD_KEY = "gen_ai.execution.payload"
+TENANT_ID_KEY = "microsoft.tenant.id"
+GEN_AI_AGENT_AUID_KEY = "microsoft.agent.user.id"
+GEN_AI_AGENT_EMAIL_KEY = "microsoft.agent.user.email"
+GEN_AI_AGENT_BLUEPRINT_ID_KEY = "microsoft.a365.agent.blueprint.id"
+SESSION_ID_KEY = "microsoft.session.id"
+SESSION_DESCRIPTION_KEY = "microsoft.session.description"
+
+# --- Error type constants ---
+ERROR_TYPE_CANCELLED = "TaskCanceledException"
+
+# --- OTel standard keys ---
+SERVER_ADDRESS_KEY = "server.address"
+SERVER_PORT_KEY = "server.port"
+SERVICE_NAME_KEY = "service.name"
+
+# --- Custom span keys ---
+CUSTOM_PARENT_SPAN_ID_KEY = "custom.parent.span.id"
+CUSTOM_SPAN_NAME_KEY = "custom.span.name"
+
+# --- Channel ---
+CHANNEL_NAME_KEY = "microsoft.channel.name"
+CHANNEL_LINK_KEY = "microsoft.channel.link"
+
+# --- Telemetry SDK attributes ---
+TELEMETRY_SDK_NAME_KEY = "telemetry.sdk.name"
+TELEMETRY_SDK_LANGUAGE_KEY = "telemetry.sdk.language"
+TELEMETRY_SDK_VERSION_KEY = "telemetry.sdk.version"
+TELEMETRY_SDK_NAME_VALUE = "A365ObservabilitySDK"
+TELEMETRY_SDK_LANGUAGE_VALUE = "python"
+
+# --- Distro environment variable names ---
+ENABLE_A365_OBSERVABILITY_EXPORTER = "ENABLE_A365_OBSERVABILITY_EXPORTER"
+A365_OBSERVABILITY_DOMAIN_OVERRIDE = "A365_OBSERVABILITY_DOMAIN_OVERRIDE"
+A365_TENANT_ID_ENV = "A365_TENANT_ID"
+A365_AGENT_ID_ENV = "A365_AGENT_ID"
+A365_CLUSTER_CATEGORY_ENV = "A365_CLUSTER_CATEGORY"
+A365_USE_S2S_ENDPOINT_ENV = "A365_USE_S2S_ENDPOINT"
+A365_SUPPRESS_INVOKE_AGENT_INPUT_ENV = "A365_SUPPRESS_INVOKE_AGENT_INPUT"
+
+# --- FIC (Federated Identity Credential) token flow env vars ---
+A365_AGENT_APP_INSTANCE_ID_ENV = "A365_AGENT_APP_INSTANCE_ID"
+A365_AGENTIC_USER_ID_ENV = "A365_AGENTIC_USER_ID"
+A365_SERVICE_CLIENT_ID_ENV = "CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID"
+A365_SERVICE_CLIENT_SECRET_ENV = "CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET"
+A365_SERVICE_TENANT_ID_ENV = "CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID"

microsoft/agents/a365/observability/core/__init__.py

@@ -0,0 +1,131 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# Microsoft Agent 365 Python SDK for OpenTelemetry tracing.
+
+from microsoft.agents.a365.observability.core.agent_details import AgentDetails
+from microsoft.agents.a365.observability.core.config import (
+    configure,
+    get_tracer,
+    get_tracer_provider,
+    is_configured,
+)
+from microsoft.agents.a365.observability.core.execute_tool_scope import ExecuteToolScope
+from microsoft.agents.a365.observability.core.exporters.agent365_exporter_options import Agent365ExporterOptions
+from microsoft.agents.a365.observability.core.exporters.enriched_span import EnrichedReadableSpan
+from microsoft.agents.a365.observability.core.exporters.enriching_span_processor import (
+    get_span_enricher,
+    register_span_enricher,
+    unregister_span_enricher,
+)
+from microsoft.agents.a365.observability.core.exporters.spectra_exporter_options import SpectraExporterOptions
+from microsoft.agents.a365.observability.core.inference_call_details import InferenceCallDetails
+from microsoft.agents.a365.observability.core.models.service_endpoint import ServiceEndpoint
+from microsoft.agents.a365.observability.core.inference_operation_type import InferenceOperationType
+from microsoft.agents.a365.observability.core.inference_scope import InferenceScope
+from microsoft.agents.a365.observability.core.invoke_agent_details import InvokeAgentScopeDetails
+from microsoft.agents.a365.observability.core.invoke_agent_scope import InvokeAgentScope
+from microsoft.agents.a365.observability.core.middleware.baggage_builder import BaggageBuilder
+from microsoft.agents.a365.observability.core.models.caller_details import CallerDetails
+from microsoft.agents.a365.observability.core.models.messages import (
+    BlobPart,
+    ChatMessage,
+    FilePart,
+    FinishReason,
+    GenericPart,
+    InputMessages,
+    InputMessagesParam,
+    MessagePart,
+    MessageRole,
+    Modality,
+    OutputMessage,
+    OutputMessages,
+    OutputMessagesParam,
+    ReasoningPart,
+    ServerToolCallPart,
+    ServerToolCallResponsePart,
+    TextPart,
+    ToolCallRequestPart,
+    ToolCallResponsePart,
+    UriPart,
+)
+from microsoft.agents.a365.observability.core.models.response import Response
+from microsoft.agents.a365.observability.core.models.user_details import UserDetails
+from microsoft.agents.a365.observability.core.opentelemetry_scope import OpenTelemetryScope
+from microsoft.agents.a365.observability.core.request import Request
+from microsoft.agents.a365.observability.core.channel import Channel
+from microsoft.agents.a365.observability.core.span_details import SpanDetails
+from microsoft.agents.a365.observability.core.spans_scopes.output_scope import OutputScope
+from microsoft.agents.a365.observability.core.tool_call_details import ToolCallDetails
+from microsoft.agents.a365.observability.core.tool_type import ToolType
+from microsoft.agents.a365.observability.core.exporters.span_processor import A365SpanProcessor as SpanProcessor
+from microsoft.agents.a365.observability.core.utils import extract_context_from_headers, get_traceparent
+
+__all__ = [
+    # Main SDK functions
+    "configure",
+    "is_configured",
+    "get_tracer",
+    "get_tracer_provider",
+    # Exporter options
+    "Agent365ExporterOptions",
+    "SpectraExporterOptions",
+    # Span enrichment
+    "register_span_enricher",
+    "unregister_span_enricher",
+    "get_span_enricher",
+    "EnrichedReadableSpan",
+    # Span processor
+    "SpanProcessor",
+    # Base scope class
+    "OpenTelemetryScope",
+    # Specific scope classes
+    "ExecuteToolScope",
+    "InvokeAgentScope",
+    "InferenceScope",
+    "OutputScope",
+    # Middleware
+    "BaggageBuilder",
+    # Data classes
+    "InvokeAgentScopeDetails",
+    "AgentDetails",
+    "CallerDetails",
+    "UserDetails",
+    "ToolCallDetails",
+    "Channel",
+    "Request",
+    "Response",
+    "SpanDetails",
+    "InferenceCallDetails",
+    "ServiceEndpoint",
+    # Enums
+    "InferenceOperationType",
+    "ToolType",
+    # OTEL gen-ai message format types
+    "MessageRole",
+    "FinishReason",
+    "Modality",
+    "TextPart",
+    "ToolCallRequestPart",
+    "ToolCallResponsePart",
+    "ReasoningPart",
+    "BlobPart",
+    "FilePart",
+    "UriPart",
+    "ServerToolCallPart",
+    "ServerToolCallResponsePart",
+    "GenericPart",
+    "MessagePart",
+    "ChatMessage",
+    "OutputMessage",
+    "InputMessages",
+    "OutputMessages",
+    "InputMessagesParam",
+    "OutputMessagesParam",
+    # Utility functions
+    "extract_context_from_headers",
+    "get_traceparent",
+]
+
+# This is a namespace package
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

microsoft/agents/a365/observability/core/agent_details.py

@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+# pylint: disable=too-many-instance-attributes
+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."""
+
+    agentic_user_id: Optional[str] = None
+    """Agentic User ID for the agent."""
+
+    agentic_user_email: Optional[str] = None
+    """Email address for the agentic user."""
+
+    agent_blueprint_id: Optional[str] = None
+    """Blueprint/Application ID for the agent."""
+
+    agent_platform_id: Optional[str] = None
+    """Platform ID for the agent."""
+
+    tenant_id: Optional[str] = None
+    """Tenant ID for the agent."""
+
+    icon_uri: Optional[str] = None
+    """Optional icon URI for the agent."""
+
+    provider_name: Optional[str] = None
+    """The provider name (e.g., openai, anthropic)."""
+
+    agent_version: Optional[str] = None
+    """Optional version of the agent (e.g., "1.0.0", "2025-05-01")."""

microsoft/agents/a365/observability/core/channel.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+# Channel class.
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Channel:
+    """Channel information for agent execution context."""
+
+    name: str | None = None
+    link: str | None = None

microsoft/agents/a365/observability/core/config.py

@@ -0,0 +1,325 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+import os
+import logging
+import threading
+from collections.abc import Callable
+from typing import Any, Optional
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+    OTLPSpanExporter as GrpcOTLPSpanExporter,
+)
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import SERVICE_NAME, SERVICE_NAMESPACE, Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter
+
+from microsoft.agents.a365.observability.core.exporters.agent365_exporter import _Agent365Exporter
+from microsoft.agents.a365.observability.core.exporters.agent365_exporter_options import Agent365ExporterOptions
+from microsoft.agents.a365.observability.core.exporters.enriching_span_processor import _EnrichingBatchSpanProcessor
+from microsoft.agents.a365.observability.core.exporters.utils import is_agent365_exporter_enabled
+from microsoft.agents.a365.observability.core.exporters.spectra_exporter_options import SpectraExporterOptions
+from microsoft.agents.a365.observability.core.exporters.span_processor import A365SpanProcessor as SpanProcessor
+
+# mypy: disable-error-code="no-untyped-def, assignment, attr-defined, arg-type"
+
+DEFAULT_LOGGER_NAME = __name__
+
+# pylint: disable=broad-exception-caught, too-many-instance-attributes
+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",
+        exporter_options: Agent365ExporterOptions | SpectraExporterOptions | None = None,
+        suppress_invoke_agent_input: bool = False,
+        **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: (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: Exporter configuration. Pass Agent365ExporterOptions for A365 API
+            export, SpectraExporterOptions for Spectra Collector sidecar export, or None (default)
+            to construct Agent365ExporterOptions from legacy parameters.
+        :param suppress_invoke_agent_input: If True, suppress input messages for InvokeAgent spans.
+        :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,
+                    exporter_options,
+                    suppress_invoke_agent_input,
+                    **kwargs,
+                )
+        except Exception as e:
+            self._logger.error("Failed to configure telemetry: %s", 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",
+        exporter_options: Agent365ExporterOptions | SpectraExporterOptions | None = None,
+        suppress_invoke_agent_input: bool = False,
+        **kwargs: Any,
+    ) -> bool:
+        """Internal configuration method - not thread-safe, must be called with lock."""
+
+        # Check if a365 observability is already configured
+        if self._tracer_provider is not None:
+            self._logger.warning("a365 observability already configured. Ignoring repeated configure() call.")
+            return True
+
+        # Create resource with service information
+        resource = Resource.create(
+            {
+                SERVICE_NAMESPACE: service_namespace,
+                SERVICE_NAME: service_name,
+            }
+        )
+
+        # Check if there's an existing TracerProvider (from app's OTEL setup)
+        tracer_provider = trace.get_tracer_provider()
+
+        # Determine if we should use existing provider or create new one
+        # Check if it's a real TracerProvider with a resource (not a proxy/no-op)
+        if getattr(tracer_provider, "resource", None):
+            # Use existing provider from application's OTEL setup
+            self._logger.info(
+                "Detected existing TracerProvider with resource. Adding a365 observability processors to it."
+            )
+        else:
+            # Create new TracerProvider with our resource
+            self._logger.info("Creating new TracerProvider for a365 observability.")
+            tracer_provider = TracerProvider(resource=resource)
+            trace.set_tracer_provider(tracer_provider)
+
+        # Store reference
+        self._tracer_provider = tracer_provider
+
+        # Use exporter_options if provided, otherwise create default options with legacy parameters
+        if exporter_options is None:
+            exporter_options = Agent365ExporterOptions(
+                cluster_category=cluster_category,
+                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,
+        }
+
+        # Type-based exporter dispatch
+        if isinstance(exporter_options, SpectraExporterOptions):
+            # Spectra path — OTLP exporter to sidecar
+            # ENABLE_A365_OBSERVABILITY_EXPORTER is intentionally ignored.
+            if exporter_options.protocol == "grpc":
+                exporter = GrpcOTLPSpanExporter(
+                    endpoint=exporter_options.endpoint,
+                    insecure=exporter_options.insecure,
+                )
+            else:
+                exporter = OTLPSpanExporter(
+                    endpoint=exporter_options.endpoint,
+                )
+
+        elif 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()
+            self._logger.warning(
+                "is_agent365_exporter_enabled() not enabled or token_resolver not set."
+                " Falling back to console exporter."
+            )
+
+        # Add span processors
+
+        # Create _EnrichingBatchSpanProcessor with optimized settings
+        # This allows extensions to enrich spans before export
+        batch_processor = _EnrichingBatchSpanProcessor(
+            exporter,
+            suppress_invoke_agent_input=suppress_invoke_agent_input,
+            **batch_processor_kwargs,
+        )
+        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
+
+        if os.environ.get("ENABLE_OTLP_EXPORTER", "").lower() == "true":
+            # The OTLPSpanExporter is auto configured from the environment variables
+            otlp_exporter = OTLPSpanExporter()
+            tracer_provider.add_span_processor(_EnrichingBatchSpanProcessor(otlp_exporter, **batch_processor_kwargs))
+
+        # 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",
+    exporter_options: Agent365ExporterOptions | SpectraExporterOptions | None = None,
+    suppress_invoke_agent_input: bool = False,
+    **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.
+    :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: Exporter configuration. Pass Agent365ExporterOptions for A365 API
+        export, SpectraExporterOptions for Spectra Collector sidecar export, or None (default)
+        to construct Agent365ExporterOptions from legacy parameters.
+    :param suppress_invoke_agent_input: If True, suppress input messages for InvokeAgent spans.
+    :return: True if configuration succeeded, False otherwise.
+    """
+    return _telemetry_manager.configure(
+        service_name,
+        service_namespace,
+        logger_name,
+        token_resolver,
+        cluster_category,
+        exporter_options,
+        suppress_invoke_agent_input,
+        **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()