feat(toolbox-core): add observability with OpenTelemetry

packages/toolbox-core/pyproject.toml

@@ -43,6 +43,11 @@ Repository = "https://github.com/googleapis/mcp-toolbox-sdk-python.git"
 Changelog = "https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/CHANGELOG.md"
 
 [project.optional-dependencies]
+telemetry = [
+    "opentelemetry-api>=1.20.0,<2.0.0",
+    "opentelemetry-sdk>=1.20.0,<2.0.0",
+    "opentelemetry-exporter-otlp>=1.20.0,<2.0.0"
+]
 test = [
     "black[jupyter]==26.1.0",
     "isort==8.0.0",

packages/toolbox-core/src/toolbox_core/client.py

@@ -28,6 +28,8 @@
     McpHttpTransportV20250618,
     McpHttpTransportV20251125,
 )
+from . import version
+from .mcp_transport.telemetry import TELEMETRY_AVAILABLE, setup_telemetry
 from .protocol import Protocol, ToolSchema
 from .tool import ToolboxTool
 from .utils import identify_auth_requirements, resolve_value, warn_if_http_and_headers
@@ -54,6 +56,7 @@ def __init__(
         protocol: Protocol = Protocol.MCP,
         client_name: Optional[str] = None,
         client_version: Optional[str] = None,
+        telemetry_url: Optional[str] = None,
     ):
         """
         Initializes the ToolboxClient.
@@ -67,29 +70,70 @@ def __init__(
             client_headers: Headers to include in each request sent through this
             client.
             protocol: The communication protocol to use.
+            client_name: Optional client name for identification.
+            client_version: Optional client version for identification.
+            telemetry_url: Optional OTLP endpoint URL for sending telemetry
+                (e.g., "http://localhost:4318"). If provided, sets up an OTLP
+                tracer provider to export traces to this endpoint.
         """
+
+        # Setup OpenTelemetry (metrics and traces) if endpoint is provided
+        if telemetry_url:
+            try:
+                setup_telemetry(
+                    service_name="toolbox",
+                    service_version=version.__version__,
+                    use_console_exporter=False,  # Using OTLP endpoint instead
+                    otlp_endpoint=telemetry_url,
+                )
+            except Exception as e:
+                logging.warning(f"Failed to setup telemetry: {e}")
+
         if protocol != Protocol.MCP_LATEST:
             logging.warning(
                 f"A newer version of MCP ({Protocol.MCP_LATEST.value}) is available. "
                 "Please use Protocol.MCP_LATEST to use the latest features."
             )
 
+        # Telemetry is only enabled if URL is provided AND OpenTelemetry is available
+        telemetry_enabled = bool(telemetry_url) and TELEMETRY_AVAILABLE
+
         match protocol:
             case Protocol.MCP_v20251125:
                 self.__transport = McpHttpTransportV20251125(
-                    url, session, protocol, client_name, client_version
+                    url,
+                    session,
+                    protocol,
+                    client_name,
+                    client_version,
+                    telemetry_enabled=telemetry_enabled,
                 )
             case Protocol.MCP_v20250618:
                 self.__transport = McpHttpTransportV20250618(
-                    url, session, protocol, client_name, client_version
+                    url,
+                    session,
+                    protocol,
+                    client_name,
+                    client_version,
+                    telemetry_enabled=telemetry_enabled,
                 )
             case Protocol.MCP_v20250326:
                 self.__transport = McpHttpTransportV20250326(
-                    url, session, protocol, client_name, client_version
+                    url,
+                    session,
+                    protocol,
+                    client_name,
+                    client_version,
+                    telemetry_enabled=telemetry_enabled,
                 )
             case Protocol.MCP_v20241105:
                 self.__transport = McpHttpTransportV20241105(
-                    url, session, protocol, client_name, client_version
+                    url,
+                    session,
+                    protocol,
+                    client_name,
+                    client_version,
+                    telemetry_enabled=telemetry_enabled,
                 )
             case _:
                 raise ValueError(f"Unsupported MCP protocol version: {protocol}")