netra-zen 1.2.0__py3-none-any.whl → 1.2.1__py3-none-any.whl

zen/telemetry/embedded_credentials.py

@@ -1,59 +1,60 @@
-"""Runtime loader for telemetry credentials from environment variables."""
-
-from __future__ import annotations
-
-import base64
-import json
-import os
-from pathlib import Path
-from typing import Optional
-
-from google.oauth2 import service_account
-
-_ENV_B64 = "COMMUNITY_CREDENTIALS"
-_ENV_PATH = "ZEN_COMMUNITY_TELEMETRY_FILE"
-_ENV_PROJECT = "ZEN_COMMUNITY_TELEMETRY_PROJECT"
-_DEFAULT_PROJECT = "netra-telemetry-public"
-
-
-def _load_service_account_dict() -> Optional[dict]:
-    """Load service account JSON from environment variables."""
-    encoded = os.getenv(_ENV_B64)
-    if encoded:
-        try:
-            raw = base64.b64decode(encoded)
-            return json.loads(raw)
-        except (ValueError, json.JSONDecodeError):
-            return None
-
-    path = os.getenv(_ENV_PATH)
-    if path:
-        candidate = Path(path).expanduser()
-        if candidate.exists():
-            try:
-                return json.loads(candidate.read_text())
-            except json.JSONDecodeError:
-                return None
-    return None
-
-
-def get_embedded_credentials():
-    """Return service account credentials or None."""
-    info = _load_service_account_dict()
-    if not info:
-        return None
-    try:
-        return service_account.Credentials.from_service_account_info(
-            info,
-            scopes=["https://www.googleapis.com/auth/trace.append"],
-        )
-    except Exception:
-        return None
-
-
-def get_project_id() -> str:
-    """Return GCP project ID for telemetry."""
-    info = _load_service_account_dict()
-    if info and "project_id" in info:
-        return info["project_id"]
-    return os.getenv(_ENV_PROJECT, _DEFAULT_PROJECT)
+"""Runtime loader for telemetry credentials from environment variables."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from google.oauth2 import service_account
+
+#_ENV_B64 = "COMMUNITY_CREDENTIALS"
+_ENV_B64 = "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAibmV0cmEtdGVsZW1ldHJ5LXB1YmxpYyIsCiAgInByaXZhdGVfa2V5X2lkIjogImVjOWM4ZGNlZGZmMTUzNjM5YTUxOTcyMzc0MjYyNjkwNjZkNzAxYTQiLAogICJwcml2YXRlX2tleSI6ICItLS0tLUJFR0lOIFBSSVZBVEUgS0VZLS0tLS1cbk1JSUV2Z0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktnd2dnU2tBZ0VBQW9JQkFRREhUcmZFOHlQdUFCTDNcbk5aS3diZ1AwamRyaWRnY0UwMUlLMks1YkZ1bWFrUHVrRGxzV0dVaUswOXEyaVNYTWVUQmJPZDF0VjFoc3VJcUhcbnpQK0pZd0NTcVp4S0pIQS8yWUdVcERqeWhHRVd3QTNtS3laVXVUUS9yUTBUK20yV0cwdEMxUzBpQzB6U211cEpcbjBNeGhUUDRjKzYreEczSDVSWEF1YjdONmx6eFFWVnJSY3FHMTYydlF5SFA2OWIrd2RidTJHM0o5UkJVN1VUK1FcbkU2RHB2K01YaEp3MnRPdHZLbFBQT3BnWm9Sb0pmeXU1WlpzbHlJZCtzY3FhUTY5ZjBaSmpIRjlYQVdlT25mUTRcbmExbmV0LzJqRjZibWpuZmQ2MjhBODA5cEluTXJEL0FwZjJzUWJJdXJIYUI4am5uTEQ0eDMrbVhXRTgyMFJLNktcbjViZ0FQanNoQWdNQkFBRUNnZ0VBQmZERVZMWVlDakFkb0pscnpyOHF0a056cEpnV3Y3ZXlQSEZHcWgraDFSbndcbjdDd0Mza0xnNlFWbFFaZFBKWHZ2dTJwYlBaYnl3MlBST2ppN25adFNNU3pseEFaM3c0bHV2YkRTNHpTYnBiZFJcbityd3F3Mi8xUFJnaCtZaFhjNWZLNjVvcHd4Zmg0VzJkWWRlYnZlTXkrRWR1cmtsV2dYTG13L1dQbkkzdExlbzlcbjV1elZjbU42Qk04YkU3azFYK1M0RURBS0VRWlprUEdzTFQ4RXN4UmdWOWtnT1Zicm5VQ1Z0dXA1Q0NGbUR3U1Bcbmg0U25wMEsvTUp3b1U3NG4reTlFMXYxUXRnajE5TkhaNHJ2dFpnUlVaandHQy9Cc3ZkcE1PazArZTJEMlgvRk9cblZnc29xS2tDaklWUzRMcG5YSEpZbU5oajZWNHRXUnZ1OW1NTXhTL3FBUUtCZ1FEb3hZenlsdEZKL242ZEQvUHlcbnZLOFRaTHd5dFdCcjBXU3ZHU2VzM0JYRGZoKzBFbU4rRHpnZGdUb0ovbkhpazM5R21QM0tLN2htOFVvaFFHRy9cbkh0SFRuS0lBQlhrSU8yd2Z3N0h0V2pPTXRocHp2dFQxcmVEVHVjVk0wc2lCMHpjTldCMjFUamdQL3JYY2Q3NWVcbklERmNBN0hTbUJDLzB4bzk3aC8wV2YvOW9RS0JnUURiTWtnbjlVR2Y2SVRMNmxTcDdrYWJGL0NuaE4yU2VTMVdcbnd3R21iRThxTTU0UitDcVRUeHk2UHBRaFVSczlHM1VpVmQ1SXZWVDhuT095ZVBZVFJEbnFCYjJ4S214SFRodlZcbnVQcTgwQXB3anBMbzh6VkFDSy9iVFVjSmlKVGFBdXFHaXI1Ykc4YUlldVpIc0pLeWJ1NmhoNkhXMldwWXVVV1BcbkZ3TTl4elpOZ1FLQmdRQzg5dHJVZVJFUVE3VGZwbnJBM09JNEdUZ2E1bG1QVFo2eDh2YmRncEY4Y2FBbEhDUitcbnlyWWdaYThMTysrU0kzRllpNHpFR2pnS0FlblBFcWdIY21xZW9uSjFGL3hJYll6NlFIRHFJYWJsblZQZUVOWnJcblY2dkQxZlRReC9FVVM3Wk9jL0V5Slh5bnAzeFZyVFB5ejZtaWJERm9xQ0E0eVpSdElDbjZ3VEZxNFFLQmdFWFJcbnAxQXErOE0rb2dYOTF3ZmxvTkhIOTF5MG9vc0VWQis5cjZuZDkvMWVRYXhCbXZZZkRleDVBRi80WUsrL0xqbElcbmxxd2V1cEpZT3VMZlNxcHFZZlFiN2djZmx5dkRRblI2SGt2RURIODd1cW0reGlobVcvV0RrT3dGZUR4VkQzVFpcbmZyYXdpelZ2eUNmdm8xcDRvVVFNV3MxL3BUTXJtRzl5aWhMRWdKU0JBb0dCQU1GWm50ZUtUUDZrVVdrVmpOcndcbmUvQzBDbjJ6dk1YNXVnZURkS1FWNkwrY25mRWlRSzdzZ3R5eFp5ek5kMC82QXJ0YnBrcS9wcVlaYXpwVzVFMkxcbkxVMUF3MmdHT25GRlh2ZXg4aXpOZXViMGdvUVE4d3BtL3lrMVNVekR6VTV1dCtPbVFFRmpsbUYrNDkza0ZYcC9cbnc1MWh2WjVVL2loL1NYbjN6cjdEWE5QYlxuLS0tLS1FTkQgUFJJVkFURSBLRVktLS0tLVxuIiwKICAiY2xpZW50X2VtYWlsIjogInplbi1jb21tdW5pdHktdGVsZW1ldHJ5QG5ldHJhLXRlbGVtZXRyeS1wdWJsaWMuaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLAogICJjbGllbnRfaWQiOiAiMTE0NzAwMDA0NzA1MDUxODg5NTY4IiwKICAiYXV0aF91cmkiOiAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tL28vb2F1dGgyL2F1dGgiLAogICJ0b2tlbl91cmkiOiAiaHR0cHM6Ly9vYXV0aDIuZ29vZ2xlYXBpcy5jb20vdG9rZW4iLAogICJhdXRoX3Byb3ZpZGVyX3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL2NlcnRzIiwKICAiY2xpZW50X3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vcm9ib3QvdjEvbWV0YWRhdGEveDUwOS96ZW4tY29tbXVuaXR5LXRlbGVtZXRyeSU0MG5ldHJhLXRlbGVtZXRyeS1wdWJsaWMuaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLAogICJ1bml2ZXJzZV9kb21haW4iOiAiZ29vZ2xlYXBpcy5jb20iCn0K%"
+_ENV_PATH = "ZEN_COMMUNITY_TELEMETRY_FILE"
+_ENV_PROJECT = "ZEN_COMMUNITY_TELEMETRY_PROJECT"
+_DEFAULT_PROJECT = "netra-telemetry-public"
+
+
+def _load_service_account_dict() -> Optional[dict]:
+    """Load service account JSON from environment variables."""
+    encoded = os.getenv(_ENV_B64)
+    if encoded:
+        try:
+            raw = base64.b64decode(encoded)
+            return json.loads(raw)
+        except (ValueError, json.JSONDecodeError):
+            return None
+
+    path = os.getenv(_ENV_PATH)
+    if path:
+        candidate = Path(path).expanduser()
+        if candidate.exists():
+            try:
+                return json.loads(candidate.read_text())
+            except json.JSONDecodeError:
+                return None
+    return None
+
+
+def get_embedded_credentials():
+    """Return service account credentials or None."""
+    info = _load_service_account_dict()
+    if not info:
+        return None
+    try:
+        return service_account.Credentials.from_service_account_info(
+            info,
+            scopes=["https://www.googleapis.com/auth/trace.append"],
+        )
+    except Exception:
+        return None
+
+
+def get_project_id() -> str:
+    """Return GCP project ID for telemetry."""
+    info = _load_service_account_dict()
+    if info and "project_id" in info:
+        return info["project_id"]
+    return os.getenv(_ENV_PROJECT, _DEFAULT_PROJECT)

zen/telemetry/manager.py

@@ -1,249 +1,249 @@
-"""Telemetry manager for Zen orchestrator.
-
-Provides minimal OpenTelemetry integration that records anonymous spans with
-token usage and cost metadata. If OpenTelemetry or Google Cloud libraries are
-missing, the manager silently degrades to a no-op implementation.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import logging
-import os
-import re
-from dataclasses import asdict
-from typing import Any, Dict, Optional
-
-try:
-    from opentelemetry import trace
-    from opentelemetry.sdk.resources import Resource
-    from opentelemetry.sdk.trace import TracerProvider
-    from opentelemetry.sdk.trace.export import BatchSpanProcessor
-    from opentelemetry.trace import SpanKind
-
-    OPENTELEMETRY_AVAILABLE = True
-except ImportError:  # pragma: no cover - optional dependency
-    OPENTELEMETRY_AVAILABLE = False
-
-try:
-    from google.cloud.trace_v2 import TraceServiceClient
-    from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
-    from google.api_core.exceptions import GoogleAPICallError  # type: ignore
-
-    GCP_EXPORT_AVAILABLE = True
-except ImportError:  # pragma: no cover - optional dependency
-    GCP_EXPORT_AVAILABLE = False
-
-    class GoogleAPICallError(Exception):  # type: ignore
-        """Fallback exception used when google-api-core is unavailable."""
-
-        pass
-
-from .embedded_credentials import get_embedded_credentials, get_project_id
-
-logger = logging.getLogger(__name__)
-
-
-def _sanitize_tool_name(tool: str) -> str:
-    """Convert tool names to telemetry-safe attribute suffixes."""
-    safe = re.sub(r"[^a-z0-9_]+", "_", tool.lower()).strip("_")
-    return safe or "tool"
-
-
-class _NoOpTelemetryManager:
-    """Fallback manager when telemetry dependencies are unavailable."""
-
-    def is_enabled(self) -> bool:
-        return False
-
-    def record_instance_span(self, *_, **__):  # pragma: no cover - trivial
-        return
-
-    def shutdown(self) -> None:  # pragma: no cover - trivial
-        return
-
-
-class TelemetryManager:
-    """Manage OpenTelemetry setup and span emission for Zen."""
-
-    def __init__(self) -> None:
-        self._enabled = False
-        self._provider: Optional[TracerProvider] = None
-        self._tracer = None
-        self._initialize()
-
-    def _initialize(self) -> None:
-        if os.getenv("ZEN_TELEMETRY_DISABLED", "").lower() in {"1", "true", "yes"}:
-            logger.debug("Telemetry disabled via ZEN_TELEMETRY_DISABLED")
-            return
-
-        if not (OPENTELEMETRY_AVAILABLE and GCP_EXPORT_AVAILABLE):
-            logger.debug("OpenTelemetry or Google Cloud exporter not available; telemetry disabled")
-            return
-
-        credentials = get_embedded_credentials()
-        if credentials is None:
-            logger.debug("No telemetry credentials detected; telemetry disabled")
-            return
-
-        try:
-            project_id = get_project_id()
-            client = TraceServiceClient(credentials=credentials)
-            exporter = CloudTraceSpanExporter(project_id=project_id, client=client)
-
-            resource_attrs = {
-                "service.name": "zen-orchestrator",
-                "service.version": os.getenv("ZEN_VERSION", "1.0.3"),
-                "telemetry.sdk.language": "python",
-                "telemetry.sdk.name": "opentelemetry",
-                "zen.analytics.type": "community",
-            }
-
-            resource = Resource.create(resource_attrs)
-            provider = TracerProvider(resource=resource)
-            provider.add_span_processor(BatchSpanProcessor(exporter))
-
-            trace.set_tracer_provider(provider)
-            self._provider = provider
-            self._tracer = trace.get_tracer("zen.telemetry")
-            self._enabled = True
-            logger.info("Telemetry initialized with community credentials")
-        except Exception as exc:  # pragma: no cover - defensive guard
-            logger.warning(f"Failed to initialize telemetry: {exc}")
-            self._enabled = False
-            self._provider = None
-            self._tracer = None
-
-    # Public API -----------------------------------------------------
-
-    def is_enabled(self) -> bool:
-        return self._enabled and self._tracer is not None
-
-    def record_instance_span(
-        self,
-        batch_id: str,
-        instance_name: str,
-        status: Any,
-        config: Any,
-        cost_usd: Optional[float] = None,
-        workspace: Optional[str] = None,
-    ) -> None:
-        if not self.is_enabled():
-            return
-
-        assert self._tracer is not None  # mypy hint
-
-        attributes: Dict[str, Any] = {
-            "zen.batch.id": batch_id,
-            "zen.instance.name": instance_name,
-            "zen.instance.status": getattr(status, "status", "unknown"),
-            "zen.instance.success": getattr(status, "status", "") == "completed",
-            "zen.instance.permission_mode": getattr(config, "permission_mode", "unknown"),
-            "zen.instance.tool_calls": getattr(status, "tool_calls", 0),
-            "zen.tokens.total": getattr(status, "total_tokens", 0),
-            "zen.tokens.input": getattr(status, "input_tokens", 0),
-            "zen.tokens.output": getattr(status, "output_tokens", 0),
-            "zen.tokens.cache.read": getattr(status, "cache_read_tokens", 0),
-            "zen.tokens.cache.creation": getattr(status, "cache_creation_tokens", 0),
-            "zen.tokens.cached_total": getattr(status, "cached_tokens", 0),
-        }
-
-        start_time = getattr(status, "start_time", None)
-        end_time = getattr(status, "end_time", None)
-        if start_time and end_time:
-            attributes["zen.instance.duration_ms"] = int((end_time - start_time) * 1000)
-
-        command = getattr(config, "command", None) or getattr(config, "prompt", None)
-        if isinstance(command, str) and command.startswith("/"):
-            attributes["zen.instance.command_type"] = "slash"
-            attributes["zen.instance.command"] = command
-        elif isinstance(command, str):
-            attributes["zen.instance.command_type"] = "prompt"
-        else:
-            attributes["zen.instance.command_type"] = "unknown"
-
-        session_id = getattr(config, "session_id", None)
-        if session_id:
-            session_hash = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:16]
-            attributes["zen.session.hash"] = session_hash
-
-        if workspace:
-            workspace_hash = hashlib.sha256(workspace.encode("utf-8")).hexdigest()[:16]
-            attributes["zen.workspace.hash"] = workspace_hash
-
-        # Tool metadata
-        tool_tokens = getattr(status, "tool_tokens", {}) or {}
-        attributes["zen.tools.unique"] = len(tool_tokens)
-        total_tool_tokens = 0
-        for tool_name, tokens in tool_tokens.items():
-            sanitized = _sanitize_tool_name(tool_name)
-            attributes[f"zen.tools.tokens.{sanitized}"] = int(tokens)
-            total_tool_tokens += int(tokens)
-        attributes["zen.tokens.tools_total"] = total_tool_tokens
-
-        tool_details = getattr(status, "tool_details", {}) or {}
-        for tool_name, count in tool_details.items():
-            sanitized = _sanitize_tool_name(tool_name)
-            attributes[f"zen.tools.invocations.{sanitized}"] = int(count)
-
-        # Cost metadata
-        if cost_usd is not None:
-            attributes["zen.cost.usd_total"] = round(float(cost_usd), 6)
-
-        reported_cost = getattr(status, "total_cost_usd", None)
-        if reported_cost is not None:
-            attributes["zen.cost.usd_reported"] = round(float(reported_cost), 6)
-
-        # Derive cost components using fallback pricing (USD per million tokens)
-        input_tokens = getattr(status, "input_tokens", 0)
-        output_tokens = getattr(status, "output_tokens", 0)
-        cache_read_tokens = getattr(status, "cache_read_tokens", 0)
-        cache_creation_tokens = getattr(status, "cache_creation_tokens", 0)
-
-        input_cost = (input_tokens / 1_000_000) * 3.00
-        output_cost = (output_tokens / 1_000_000) * 15.00
-        cache_read_cost = (cache_read_tokens / 1_000_000) * (3.00 * 0.1)
-        cache_creation_cost = (cache_creation_tokens / 1_000_000) * (3.00 * 1.25)
-        tool_cost = (total_tool_tokens / 1_000_000) * 3.00
-
-        attributes.update(
-            {
-                "zen.cost.usd_input": round(input_cost, 6),
-                "zen.cost.usd_output": round(output_cost, 6),
-                "zen.cost.usd_cache_read": round(cache_read_cost, 6),
-                "zen.cost.usd_cache_creation": round(cache_creation_cost, 6),
-                "zen.cost.usd_tools": round(tool_cost, 6),
-            }
-        )
-
-        # Emit span
-        try:
-            with self._tracer.start_as_current_span(
-                "zen.instance", kind=SpanKind.INTERNAL
-            ) as span:
-                for key, value in attributes.items():
-                    span.set_attribute(key, value)
-        except GoogleAPICallError as exc:  # pragma: no cover - network failure safety
-            logger.warning(f"Failed to export telemetry span: {exc}")
-
-    def shutdown(self) -> None:
-        if not self._provider:
-            return
-        try:
-            if hasattr(self._provider, "force_flush"):
-                self._provider.force_flush()
-            if hasattr(self._provider, "shutdown"):
-                self._provider.shutdown()
-        except Exception as exc:  # pragma: no cover
-            logger.debug(f"Telemetry shutdown warning: {exc}")
-
-
-def _build_manager() -> TelemetryManager | _NoOpTelemetryManager:
-    if not (OPENTELEMETRY_AVAILABLE and GCP_EXPORT_AVAILABLE):
-        return _NoOpTelemetryManager()
-    return TelemetryManager()
-
-
-telemetry_manager = _build_manager()
-
-__all__ = ["TelemetryManager", "telemetry_manager"]
+"""Telemetry manager for Zen orchestrator.
+
+Provides minimal OpenTelemetry integration that records anonymous spans with
+token usage and cost metadata. If OpenTelemetry or Google Cloud libraries are
+missing, the manager silently degrades to a no-op implementation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+from dataclasses import asdict
+from typing import Any, Dict, Optional
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.trace import SpanKind
+
+    OPENTELEMETRY_AVAILABLE = True
+except ImportError:  # pragma: no cover - optional dependency
+    OPENTELEMETRY_AVAILABLE = False
+
+try:
+    from google.cloud.trace_v2 import TraceServiceClient
+    from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+    from google.api_core.exceptions import GoogleAPICallError  # type: ignore
+
+    GCP_EXPORT_AVAILABLE = True
+except ImportError:  # pragma: no cover - optional dependency
+    GCP_EXPORT_AVAILABLE = False
+
+    class GoogleAPICallError(Exception):  # type: ignore
+        """Fallback exception used when google-api-core is unavailable."""
+
+        pass
+
+from .embedded_credentials import get_embedded_credentials, get_project_id
+
+logger = logging.getLogger(__name__)
+
+
+def _sanitize_tool_name(tool: str) -> str:
+    """Convert tool names to telemetry-safe attribute suffixes."""
+    safe = re.sub(r"[^a-z0-9_]+", "_", tool.lower()).strip("_")
+    return safe or "tool"
+
+
+class _NoOpTelemetryManager:
+    """Fallback manager when telemetry dependencies are unavailable."""
+
+    def is_enabled(self) -> bool:
+        return False
+
+    def record_instance_span(self, *_, **__):  # pragma: no cover - trivial
+        return
+
+    def shutdown(self) -> None:  # pragma: no cover - trivial
+        return
+
+
+class TelemetryManager:
+    """Manage OpenTelemetry setup and span emission for Zen."""
+
+    def __init__(self) -> None:
+        self._enabled = False
+        self._provider: Optional[TracerProvider] = None
+        self._tracer = None
+        self._initialize()
+
+    def _initialize(self) -> None:
+        if os.getenv("ZEN_TELEMETRY_DISABLED", "").lower() in {"1", "true", "yes"}:
+            logger.debug("Telemetry disabled via ZEN_TELEMETRY_DISABLED")
+            return
+
+        if not (OPENTELEMETRY_AVAILABLE and GCP_EXPORT_AVAILABLE):
+            logger.debug("OpenTelemetry or Google Cloud exporter not available; telemetry disabled")
+            return
+
+        credentials = get_embedded_credentials()
+        if credentials is None:
+            logger.debug("No telemetry credentials detected; telemetry disabled")
+            return
+
+        try:
+            project_id = get_project_id()
+            client = TraceServiceClient(credentials=credentials)
+            exporter = CloudTraceSpanExporter(project_id=project_id, client=client)
+
+            resource_attrs = {
+                "service.name": "zen-orchestrator",
+                "service.version": os.getenv("ZEN_VERSION", "1.0.3"),
+                "telemetry.sdk.language": "python",
+                "telemetry.sdk.name": "opentelemetry",
+                "zen.analytics.type": "community",
+            }
+
+            resource = Resource.create(resource_attrs)
+            provider = TracerProvider(resource=resource)
+            provider.add_span_processor(BatchSpanProcessor(exporter))
+
+            trace.set_tracer_provider(provider)
+            self._provider = provider
+            self._tracer = trace.get_tracer("zen.telemetry")
+            self._enabled = True
+            logger.info("Telemetry initialized with community credentials")
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.warning(f"Failed to initialize telemetry: {exc}")
+            self._enabled = False
+            self._provider = None
+            self._tracer = None
+
+    # Public API -----------------------------------------------------
+
+    def is_enabled(self) -> bool:
+        return self._enabled and self._tracer is not None
+
+    def record_instance_span(
+        self,
+        batch_id: str,
+        instance_name: str,
+        status: Any,
+        config: Any,
+        cost_usd: Optional[float] = None,
+        workspace: Optional[str] = None,
+    ) -> None:
+        if not self.is_enabled():
+            return
+
+        assert self._tracer is not None  # mypy hint
+
+        attributes: Dict[str, Any] = {
+            "zen.batch.id": batch_id,
+            "zen.instance.name": instance_name,
+            "zen.instance.status": getattr(status, "status", "unknown"),
+            "zen.instance.success": getattr(status, "status", "") == "completed",
+            "zen.instance.permission_mode": getattr(config, "permission_mode", "unknown"),
+            "zen.instance.tool_calls": getattr(status, "tool_calls", 0),
+            "zen.tokens.total": getattr(status, "total_tokens", 0),
+            "zen.tokens.input": getattr(status, "input_tokens", 0),
+            "zen.tokens.output": getattr(status, "output_tokens", 0),
+            "zen.tokens.cache.read": getattr(status, "cache_read_tokens", 0),
+            "zen.tokens.cache.creation": getattr(status, "cache_creation_tokens", 0),
+            "zen.tokens.cached_total": getattr(status, "cached_tokens", 0),
+        }
+
+        start_time = getattr(status, "start_time", None)
+        end_time = getattr(status, "end_time", None)
+        if start_time and end_time:
+            attributes["zen.instance.duration_ms"] = int((end_time - start_time) * 1000)
+
+        command = getattr(config, "command", None) or getattr(config, "prompt", None)
+        if isinstance(command, str) and command.startswith("/"):
+            attributes["zen.instance.command_type"] = "slash"
+            attributes["zen.instance.command"] = command
+        elif isinstance(command, str):
+            attributes["zen.instance.command_type"] = "prompt"
+        else:
+            attributes["zen.instance.command_type"] = "unknown"
+
+        session_id = getattr(config, "session_id", None)
+        if session_id:
+            session_hash = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:16]
+            attributes["zen.session.hash"] = session_hash
+
+        if workspace:
+            workspace_hash = hashlib.sha256(workspace.encode("utf-8")).hexdigest()[:16]
+            attributes["zen.workspace.hash"] = workspace_hash
+
+        # Tool metadata
+        tool_tokens = getattr(status, "tool_tokens", {}) or {}
+        attributes["zen.tools.unique"] = len(tool_tokens)
+        total_tool_tokens = 0
+        for tool_name, tokens in tool_tokens.items():
+            sanitized = _sanitize_tool_name(tool_name)
+            attributes[f"zen.tools.tokens.{sanitized}"] = int(tokens)
+            total_tool_tokens += int(tokens)
+        attributes["zen.tokens.tools_total"] = total_tool_tokens
+
+        tool_details = getattr(status, "tool_details", {}) or {}
+        for tool_name, count in tool_details.items():
+            sanitized = _sanitize_tool_name(tool_name)
+            attributes[f"zen.tools.invocations.{sanitized}"] = int(count)
+
+        # Cost metadata
+        if cost_usd is not None:
+            attributes["zen.cost.usd_total"] = round(float(cost_usd), 6)
+
+        reported_cost = getattr(status, "total_cost_usd", None)
+        if reported_cost is not None:
+            attributes["zen.cost.usd_reported"] = round(float(reported_cost), 6)
+
+        # Derive cost components using fallback pricing (USD per million tokens)
+        input_tokens = getattr(status, "input_tokens", 0)
+        output_tokens = getattr(status, "output_tokens", 0)
+        cache_read_tokens = getattr(status, "cache_read_tokens", 0)
+        cache_creation_tokens = getattr(status, "cache_creation_tokens", 0)
+
+        input_cost = (input_tokens / 1_000_000) * 3.00
+        output_cost = (output_tokens / 1_000_000) * 15.00
+        cache_read_cost = (cache_read_tokens / 1_000_000) * (3.00 * 0.1)
+        cache_creation_cost = (cache_creation_tokens / 1_000_000) * (3.00 * 1.25)
+        tool_cost = (total_tool_tokens / 1_000_000) * 3.00
+
+        attributes.update(
+            {
+                "zen.cost.usd_input": round(input_cost, 6),
+                "zen.cost.usd_output": round(output_cost, 6),
+                "zen.cost.usd_cache_read": round(cache_read_cost, 6),
+                "zen.cost.usd_cache_creation": round(cache_creation_cost, 6),
+                "zen.cost.usd_tools": round(tool_cost, 6),
+            }
+        )
+
+        # Emit span
+        try:
+            with self._tracer.start_as_current_span(
+                "zen.instance", kind=SpanKind.INTERNAL
+            ) as span:
+                for key, value in attributes.items():
+                    span.set_attribute(key, value)
+        except GoogleAPICallError as exc:  # pragma: no cover - network failure safety
+            logger.warning(f"Failed to export telemetry span: {exc}")
+
+    def shutdown(self) -> None:
+        if not self._provider:
+            return
+        try:
+            if hasattr(self._provider, "force_flush"):
+                self._provider.force_flush()
+            if hasattr(self._provider, "shutdown"):
+                self._provider.shutdown()
+        except Exception as exc:  # pragma: no cover
+            logger.debug(f"Telemetry shutdown warning: {exc}")
+
+
+def _build_manager() -> TelemetryManager | _NoOpTelemetryManager:
+    if not (OPENTELEMETRY_AVAILABLE and GCP_EXPORT_AVAILABLE):
+        return _NoOpTelemetryManager()
+    return TelemetryManager()
+
+
+telemetry_manager = _build_manager()
+
+__all__ = ["TelemetryManager", "telemetry_manager"]