Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(core): add OpenTelemetry and Sentry instrumentation (#661)

r33drichardsb89c2b5babd8
diff --git a/libs/python/core/core/telemetry/__init__.py b/libs/python/core/core/telemetry/__init__.py
index a79fbbb243..3b51c5c1a8 100644
--- a/libs/python/core/core/telemetry/__init__.py
+++ b/libs/python/core/core/telemetry/__init__.py
@@ -1,6 +1,7 @@
"""This module provides the core telemetry functionality for Cua libraries.
-It provides a low-overhead way to collect anonymous usage data.
+It provides a low-overhead way to collect anonymous usage data via PostHog,
+operational metrics via OpenTelemetry, and error tracking via Sentry.
"""
from core.telemetry.posthog import (
@@ -9,8 +10,53 @@ from core.telemetry.posthog import (
record_event,
)
+# OpenTelemetry instrumentation for Four Golden Signals
+from core.telemetry.otel import (
+ create_span,
+ instrument_async,
+ instrument_sync,
+ is_otel_enabled,
+ record_error,
+ record_operation,
+ record_tokens,
+ track_concurrent,
+)
+
+# Sentry error tracking
+from core.telemetry.sentry import (
+ add_breadcrumb,
+ capture_exception,
+ capture_message,
+ flush,
+ is_sentry_enabled,
+ set_context,
+ set_tag,
+ set_user,
+ start_transaction,
+)
+
__all__ = [
+ # PostHog (product analytics)
"record_event",
"is_telemetry_enabled",
"destroy_telemetry_client",
+ # OpenTelemetry (operational metrics)
+ "is_otel_enabled",
+ "record_operation",
+ "record_error",
+ "record_tokens",
+ "track_concurrent",
+ "create_span",
+ "instrument_async",
+ "instrument_sync",
+ # Sentry (error tracking)
+ "is_sentry_enabled",
+ "capture_exception",
+ "capture_message",
+ "add_breadcrumb",
+ "set_user",
+ "set_tag",
+ "set_context",
+ "start_transaction",
+ "flush",
]
diff --git a/libs/python/core/core/telemetry/otel.py b/libs/python/core/core/telemetry/otel.py
new file mode 100644
index 0000000000..94c4b414fb
--- /dev/null
+++ b/libs/python/core/core/telemetry/otel.py
@@ -0,0 +1,503 @@
+"""OpenTelemetry instrumentation for CUA SDK.
+
+Provides metrics and tracing for the Four Golden Signals:
+- Latency: Operation duration histograms
+- Traffic: Operation counters
+- Errors: Error counters
+- Saturation: Concurrent operation gauges
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import time
+from contextlib import contextmanager
+from functools import wraps
+from threading import Lock
+from typing import Any, Callable, Dict, Generator, Optional, TypeVar, Union
+
+logger = logging.getLogger("core.telemetry.otel")
+
+# Type vars for decorator
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Default OTEL endpoint
+DEFAULT_OTEL_ENDPOINT = "https://otel.cua.ai"
+
+# Lazy initialization state
+_initialized = False
+_init_lock = Lock()
+
+# OTEL components (lazily initialized)
+_meter: Optional[Any] = None
+_tracer: Optional[Any] = None
+_meter_provider: Optional[Any] = None
+_tracer_provider: Optional[Any] = None
+
+# Metrics (lazily initialized)
+_operation_duration: Optional[Any] = None # Histogram
+_operations_total: Optional[Any] = None # Counter
+_errors_total: Optional[Any] = None # Counter
+_concurrent_operations: Optional[Any] = None # UpDownCounter
+_tokens_total: Optional[Any] = None # Counter
+
+
+def is_otel_enabled() -> bool:
+ """Check if OpenTelemetry is enabled.
+
+ Returns True unless CUA_TELEMETRY_DISABLED is set to a truthy value.
+ """
+ disabled = os.environ.get("CUA_TELEMETRY_DISABLED", "").lower()
+ return disabled not in {"1", "true", "yes", "on"}
+
+
+def _get_otel_endpoint() -> str:
+ """Get the OTLP endpoint URL."""
+ return os.environ.get("CUA_OTEL_ENDPOINT", DEFAULT_OTEL_ENDPOINT)
+
+
+def _get_service_name() -> str:
+ """Get the service name for OTEL."""
+ return os.environ.get("CUA_OTEL_SERVICE_NAME", "cua-sdk")
+
+
+def _initialize_otel() -> bool:
+ """Initialize OpenTelemetry components.
+
+ Returns True if initialization succeeded, False otherwise.
+ Thread-safe via lock.
+ """
+ global _initialized, _meter, _tracer, _meter_provider, _tracer_provider
+ global _operation_duration, _operations_total, _errors_total
+ global _concurrent_operations, _tokens_total
+
+ if _initialized:
+ return True
+
+ with _init_lock:
+ # Double-check after acquiring lock
+ if _initialized:
+ return True
+
+ if not is_otel_enabled():
+ logger.debug("OpenTelemetry disabled via CUA_TELEMETRY_DISABLED")
+ return False
+
+ try:
+ # Import OTEL packages lazily
+ from opentelemetry import metrics, trace
+ from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
+ OTLPMetricExporter,
+ )
+ from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+ OTLPSpanExporter,
+ )
+ from opentelemetry.sdk.metrics import MeterProvider
+ from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+ from opentelemetry.sdk.resources import Resource
+ from opentelemetry.sdk.trace import TracerProvider
+ from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+ # Create resource with service info
+ resource = Resource.create({
+ "service.name": _get_service_name(),
+ "service.version": _get_sdk_version(),
+ })
+
+ endpoint = _get_otel_endpoint()
+
+ # Set up metrics
+ metric_exporter = OTLPMetricExporter(
+ endpoint=f"{endpoint}/v1/metrics",
+ )
+ metric_reader = PeriodicExportingMetricReader(
+ metric_exporter,
+ export_interval_millis=60000, # Export every 60 seconds
+ )
+ _meter_provider = MeterProvider(
+ resource=resource,
+ metric_readers=[metric_reader],
+ )
+ metrics.set_meter_provider(_meter_provider)
+ _meter = metrics.get_meter("cua-sdk", _get_sdk_version())
+
+ # Set up tracing
+ trace_exporter = OTLPSpanExporter(
+ endpoint=f"{endpoint}/v1/traces",
+ )
+ _tracer_provider = TracerProvider(resource=resource)
+ _tracer_provider.add_span_processor(BatchSpanProcessor(trace_exporter))
+ trace.set_tracer_provider(_tracer_provider)
+ _tracer = trace.get_tracer("cua-sdk", _get_sdk_version())
+
+ # Create metrics instruments
+ _operation_duration = _meter.create_histogram(
+ name="cua_sdk_operation_duration_seconds",
+ description="Duration of SDK operations in seconds",
+ unit="s",
+ )
+
+ _operations_total = _meter.create_counter(
+ name="cua_sdk_operations_total",
+ description="Total number of SDK operations",
+ unit="1",
+ )
+
+ _errors_total = _meter.create_counter(
+ name="cua_sdk_errors_total",
+ description="Total number of SDK errors",
+ unit="1",
+ )
+
+ _concurrent_operations = _meter.create_up_down_counter(
+ name="cua_sdk_concurrent_operations",
+ description="Number of concurrent SDK operations",
+ unit="1",
+ )
+
+ _tokens_total = _meter.create_counter(
+ name="cua_sdk_tokens_total",
+ description="Total tokens consumed",
+ unit="1",
+ )
+
+ # Register shutdown handler
+ atexit.register(_shutdown_otel)
+
+ _initialized = True
+ logger.info(f"OpenTelemetry initialized with endpoint: {endpoint}")
+ return True
+
+ except ImportError as e:
+ logger.warning(
+ f"OpenTelemetry packages not installed: {e}. "
+ "Install with: pip install opentelemetry-api opentelemetry-sdk "
+ "opentelemetry-exporter-otlp-proto-http"
+ )
+ return False
+ except Exception as e:
+ logger.warning(f"Failed to initialize OpenTelemetry: {e}")
+ return False
+
+
+def _shutdown_otel() -> None:
+ """Shutdown OpenTelemetry providers gracefully."""
+ global _meter_provider, _tracer_provider
+
+ try:
+ if _meter_provider is not None:
+ _meter_provider.shutdown()
+ if _tracer_provider is not None:
+ _tracer_provider.shutdown()
+ logger.debug("OpenTelemetry shutdown complete")
+ except Exception as e:
+ logger.debug(f"Error during OpenTelemetry shutdown: {e}")
+
+
+def _get_sdk_version() -> str:
+ """Get the CUA SDK version."""
+ try:
+ from core import __version__
+ return __version__
+ except ImportError:
+ return "unknown"
+
+
+# --- Public API ---
+
+
+def record_operation(
+ operation: str,
+ duration_seconds: float,
+ status: str = "success",
+ model: Optional[str] = None,
+ os_type: Optional[str] = None,
+ **extra_attributes: Any,
+) -> None:
+ """Record an operation metric (latency + traffic).
+
+ Args:
+ operation: Operation name (e.g., "agent.run", "computer.action.click")
+ duration_seconds: Duration of the operation in seconds
+ status: Operation status ("success" or "error")
+ model: Model name if applicable
+ os_type: OS type if applicable
+ **extra_attributes: Additional attributes to record
+ """
+ if not _initialize_otel():
+ return
+
+ attributes: Dict[str, str] = {
+ "operation": operation,
+ "status": status,
+ }
+ if model:
+ attributes["model"] = model
+ if os_type:
+ attributes["os_type"] = os_type
+ for key, value in extra_attributes.items():
+ if value is not None:
+ attributes[key] = str(value)
+
+ try:
+ if _operation_duration is not None:
+ _operation_duration.record(duration_seconds, attributes)
+ if _operations_total is not None:
+ _operations_total.add(1, attributes)
+ except Exception as e:
+ logger.debug(f"Failed to record operation metric: {e}")
+
+
+def record_error(
+ error_type: str,
+ operation: str,
+ model: Optional[str] = None,
+ **extra_attributes: Any,
+) -> None:
+ """Record an error metric.
+
+ Args:
+ error_type: Type of error (e.g., "api_error", "timeout", "computer_error")
+ operation: Operation that failed
+ model: Model name if applicable
+ **extra_attributes: Additional attributes to record
+ """
+ if not _initialize_otel():
+ return
+
+ attributes: Dict[str, str] = {
+ "error_type": error_type,
+ "operation": operation,
+ }
+ if model:
+ attributes["model"] = model
+ for key, value in extra_attributes.items():
+ if value is not None:
+ attributes[key] = str(value)
+
+ try:
+ if _errors_total is not None:
+ _errors_total.add(1, attributes)
+ except Exception as e:
+ logger.debug(f"Failed to record error metric: {e}")
+
+
+def record_tokens(
+ prompt_tokens: int = 0,
+ completion_tokens: int = 0,
+ model: Optional[str] = None,
+) -> None:
+ """Record token usage metrics.
+
+ Args:
+ prompt_tokens: Number of prompt tokens
+ completion_tokens: Number of completion tokens
+ model: Model name
+ """
+ if not _initialize_otel():
+ return
+
+ try:
+ if _tokens_total is not None:
+ if prompt_tokens > 0:
+ _tokens_total.add(
+ prompt_tokens,
+ {"token_type": "prompt", "model": model or "unknown"},
+ )
+ if completion_tokens > 0:
+ _tokens_total.add(
+ completion_tokens,
+ {"token_type": "completion", "model": model or "unknown"},
+ )
+ except Exception as e:
+ logger.debug(f"Failed to record token metric: {e}")
+
+
+@contextmanager
+def track_concurrent(operation_type: str) -> Generator[None, None, None]:
+ """Context manager to track concurrent operations.
+
+ Args:
+ operation_type: Type of operation (e.g., "sessions", "runs")
+
+ Example:
+ with track_concurrent("agent_sessions"):
+ # session is active
+ pass
+ """
+ if not _initialize_otel():
+ yield
+ return
+
+ attributes = {"operation_type": operation_type}
+
+ try:
+ if _concurrent_operations is not None:
+ _concurrent_operations.add(1, attributes)
+ except Exception as e:
+ logger.debug(f"Failed to increment concurrent counter: {e}")
+
+ try:
+ yield
+ finally:
+ try:
+ if _concurrent_operations is not None:
+ _concurrent_operations.add(-1, attributes)
+ except Exception as e:
+ logger.debug(f"Failed to decrement concurrent counter: {e}")
+
+
+@contextmanager
+def create_span(
+ name: str,
+ attributes: Optional[Dict[str, Any]] = None,
+) -> Generator[Any, None, None]:
+ """Create a trace span context.
+
+ Args:
+ name: Span name
+ attributes: Span attributes
+
+ Yields:
+ The span object (or None if tracing disabled)
+
+ Example:
+ with create_span("agent.run", {"model": "claude-3"}) as span:
+ # do work
+ if span:
+ span.set_attribute("steps", 5)
+ """
+ if not _initialize_otel() or _tracer is None:
+ yield None
+ return
+
+ try:
+ with _tracer.start_as_current_span(name, attributes=attributes) as span:
+ yield span
+ except Exception as e:
+ logger.debug(f"Failed to create span: {e}")
+ yield None
+
+
+def instrument_async(
+ operation: str,
+ model_attr: Optional[str] = None,
+ os_type_attr: Optional[str] = None,
+) -> Callable[[F], F]:
+ """Decorator to instrument an async function.
+
+ Records duration, success/error status, and creates a trace span.
+
+ Args:
+ operation: Operation name for metrics
+ model_attr: Attribute name to extract model from kwargs
+ os_type_attr: Attribute name to extract os_type from kwargs
+
+ Example:
+ @instrument_async("agent.run", model_attr="model")
+ async def run(self, prompt: str, model: str = "claude-3"):
+ ...
+ """
+ def decorator(func: F) -> F:
+ @wraps(func)
+ async def wrapper(*args: Any, **kwargs: Any) -> Any:
+ if not is_otel_enabled():
+ return await func(*args, **kwargs)
+
+ model = kwargs.get(model_attr) if model_attr else None
+ os_type = kwargs.get(os_type_attr) if os_type_attr else None
+
+ start_time = time.perf_counter()
+ status = "success"
+ error_type = None
+
+ with create_span(operation, {"model": model, "os_type": os_type}):
+ try:
+ result = await func(*args, **kwargs)
+ return result
+ except Exception as e:
+ status = "error"
+ error_type = type(e).__name__
+ raise
+ finally:
+ duration = time.perf_counter() - start_time
+ record_operation(
+ operation=operation,
+ duration_seconds=duration,
+ status=status,
+ model=model,
+ os_type=os_type,
+ )
+ if error_type:
+ record_error(
+ error_type=error_type,
+ operation=operation,
+ model=model,
+ )
+
+ return wrapper # type: ignore
+
+ return decorator
+
+
+def instrument_sync(
+ operation: str,
+ model_attr: Optional[str] = None,
+ os_type_attr: Optional[str] = None,
+) -> Callable[[F], F]:
+ """Decorator to instrument a sync function.
+
+ Records duration, success/error status, and creates a trace span.
+
+ Args:
+ operation: Operation name for metrics
+ model_attr: Attribute name to extract model from kwargs
+ os_type_attr: Attribute name to extract os_type from kwargs
+
+ Example:
+ @instrument_sync("computer.screenshot")
+ def screenshot(self):
+ ...
+ """
+ def decorator(func: F) -> F:
+ @wraps(func)
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
+ if not is_otel_enabled():
+ return func(*args, **kwargs)
+
+ model = kwargs.get(model_attr) if model_attr else None
+ os_type = kwargs.get(os_type_attr) if os_type_attr else None
+
+ start_time = time.perf_counter()
+ status = "success"
+ error_type = None
+
+ with create_span(operation, {"model": model, "os_type": os_type}):
+ try:
+ result = func(*args, **kwargs)
+ return result
+ except Exception as e:
+ status = "error"
+ error_type = type(e).__name__
+ raise
+ finally:
+ duration = time.perf_counter() - start_time
+ record_operation(
+ operation=operation,
+ duration_seconds=duration,
+ status=status,
+ model=model,
+ os_type=os_type,
+ )
+ if error_type:
+ record_error(
+ error_type=error_type,
+ operation=operation,
+ model=model,
+ )
+
+ return wrapper # type: ignore
+
+ return decorator
diff --git a/libs/python/core/core/telemetry/sentry.py b/libs/python/core/core/telemetry/sentry.py
new file mode 100644
index 0000000000..187432f640
--- /dev/null
+++ b/libs/python/core/core/telemetry/sentry.py
@@ -0,0 +1,370 @@
+"""Sentry error tracking for CUA SDK.
+
+Provides error tracking, crash reporting, and performance monitoring.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from threading import Lock
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+logger = logging.getLogger("core.telemetry.sentry")
+
+# Type vars for decorator
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Public Sentry DSN for CUA SDK
+# This is intentionally public - it only allows sending events to our project
+PUBLIC_SENTRY_DSN = (
+ "https://d3fed5d05939cb8343dfcab552948d17@o4510539933483008.ingest.us.sentry.io/4510551288381440"
+)
+
+# Lazy initialization state
+_initialized = False
+_init_lock = Lock()
+_sentry_sdk: Optional[Any] = None
+
+
+def is_sentry_enabled() -> bool:
+ """Check if Sentry is enabled.
+
+ Returns True unless CUA_TELEMETRY_DISABLED is set to a truthy value.
+ """
+ disabled = os.environ.get("CUA_TELEMETRY_DISABLED", "").lower()
+ return disabled not in {"1", "true", "yes", "on"}
+
+
+def _get_sentry_dsn() -> str:
+ """Get the Sentry DSN."""
+ return os.environ.get("CUA_SENTRY_DSN", PUBLIC_SENTRY_DSN)
+
+
+def _get_sdk_version() -> str:
+ """Get the CUA SDK version."""
+ try:
+ from core import __version__
+ return __version__
+ except ImportError:
+ return "unknown"
+
+
+def _get_environment() -> str:
+ """Get the environment name."""
+ return os.environ.get("CUA_ENVIRONMENT", "production")
+
+
+def _initialize_sentry() -> bool:
+ """Initialize Sentry SDK.
+
+ Returns True if initialization succeeded, False otherwise.
+ Thread-safe via lock.
+ """
+ global _initialized, _sentry_sdk
+
+ if _initialized:
+ return True
+
+ with _init_lock:
+ # Double-check after acquiring lock
+ if _initialized:
+ return True
+
+ if not is_sentry_enabled():
+ logger.debug("Sentry disabled via CUA_TELEMETRY_DISABLED")
+ return False
+
+ try:
+ import sentry_sdk
+ from sentry_sdk.integrations.logging import LoggingIntegration
+
+ _sentry_sdk = sentry_sdk
+
+ # Configure logging integration to capture warnings and above
+ logging_integration = LoggingIntegration(
+ level=logging.WARNING,
+ event_level=logging.ERROR,
+ )
+
+ sentry_sdk.init(
+ dsn=_get_sentry_dsn(),
+ environment=_get_environment(),
+ release=f"cua-sdk@{_get_sdk_version()}",
+ # Performance monitoring
+ traces_sample_rate=0.1, # 10% of transactions
+ # Only send errors, not all transactions
+ profiles_sample_rate=0.0,
+ # Integrations
+ integrations=[logging_integration],
+ # Don't send PII
+ send_default_pii=False,
+ # Attach stacktrace to messages
+ attach_stacktrace=True,
+ # Set max breadcrumbs
+ max_breadcrumbs=50,
+ # Before send hook to filter sensitive data
+ before_send=_before_send,
+ )
+
+ # Set default tags
+ sentry_sdk.set_tag("sdk.name", "cua-sdk")
+ sentry_sdk.set_tag("sdk.version", _get_sdk_version())
+
+ _initialized = True
+ logger.info("Sentry initialized")
+ return True
+
+ except ImportError as e:
+ logger.warning(
+ f"Sentry SDK not installed: {e}. "
+ "Install with: pip install sentry-sdk"
+ )
+ return False
+ except Exception as e:
+ logger.warning(f"Failed to initialize Sentry: {e}")
+ return False
+
+
+def _before_send(event: Dict[str, Any], hint: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+ """Filter sensitive data before sending to Sentry."""
+ # Remove any potential PII from breadcrumbs
+ if "breadcrumbs" in event:
+ for breadcrumb in event.get("breadcrumbs", {}).get("values", []):
+ # Filter out any data that might contain prompts or user content
+ if "data" in breadcrumb:
+ data = breadcrumb["data"]
+ for key in list(data.keys()):
+ if any(
+ sensitive in key.lower()
+ for sensitive in ["prompt", "content", "message", "text", "input", "output"]
+ ):
+ data[key] = "[FILTERED]"
+
+ # Remove sensitive context
+ if "contexts" in event:
+ contexts = event["contexts"]
+ for key in list(contexts.keys()):
+ if any(
+ sensitive in key.lower()
+ for sensitive in ["prompt", "content", "message"]
+ ):
+ del contexts[key]
+
+ return event
+
+
+# --- Public API ---
+
+
+def capture_exception(
+ error: Optional[BaseException] = None,
+ context: Optional[Dict[str, Any]] = None,
+) -> Optional[str]:
+ """Capture an exception and send to Sentry.
+
+ Args:
+ error: The exception to capture. If None, captures current exception.
+ context: Additional context to attach to the event.
+
+ Returns:
+ Event ID if captured, None otherwise.
+ """
+ if not _initialize_sentry() or _sentry_sdk is None:
+ return None
+
+ try:
+ with _sentry_sdk.push_scope() as scope:
+ if context:
+ for key, value in context.items():
+ # Don't include potentially sensitive data
+ if not any(
+ sensitive in key.lower()
+ for sensitive in ["prompt", "content", "message", "text"]
+ ):
+ scope.set_extra(key, value)
+
+ return _sentry_sdk.capture_exception(error)
+ except Exception as e:
+ logger.debug(f"Failed to capture exception: {e}")
+ return None
+
+
+def capture_message(
+ message: str,
+ level: str = "info",
+ context: Optional[Dict[str, Any]] = None,
+) -> Optional[str]:
+ """Capture a message and send to Sentry.
+
+ Args:
+ message: The message to capture.
+ level: Log level (debug, info, warning, error, fatal).
+ context: Additional context to attach to the event.
+
+ Returns:
+ Event ID if captured, None otherwise.
+ """
+ if not _initialize_sentry() or _sentry_sdk is None:
+ return None
+
+ try:
+ with _sentry_sdk.push_scope() as scope:
+ if context:
+ for key, value in context.items():
+ if not any(
+ sensitive in key.lower()
+ for sensitive in ["prompt", "content", "message", "text"]
+ ):
+ scope.set_extra(key, value)
+
+ return _sentry_sdk.capture_message(message, level=level)
+ except Exception as e:
+ logger.debug(f"Failed to capture message: {e}")
+ return None
+
+
+def add_breadcrumb(
+ category: str,
+ message: str,
+ level: str = "info",
+ data: Optional[Dict[str, Any]] = None,
+) -> None:
+ """Add a breadcrumb for debugging context.
+
+ Args:
+ category: Breadcrumb category (e.g., "agent", "computer")
+ message: Breadcrumb message
+ level: Log level
+ data: Additional data (will be filtered for sensitive content)
+ """
+ if not _initialize_sentry() or _sentry_sdk is None:
+ return
+
+ try:
+ # Filter sensitive data
+ filtered_data = {}
+ if data:
+ for key, value in data.items():
+ if not any(
+ sensitive in key.lower()
+ for sensitive in ["prompt", "content", "message", "text", "input", "output"]
+ ):
+ filtered_data[key] = value
+
+ _sentry_sdk.add_breadcrumb(
+ category=category,
+ message=message,
+ level=level,
+ data=filtered_data if filtered_data else None,
+ )
+ except Exception as e:
+ logger.debug(f"Failed to add breadcrumb: {e}")
+
+
+def set_user(user_id: str) -> None:
+ """Set the user context (installation ID, not PII).
+
+ Args:
+ user_id: Anonymous user/installation ID
+ """
+ if not _initialize_sentry() or _sentry_sdk is None:
+ return
+
+ try:
+ _sentry_sdk.set_user({"id": user_id})
+ except Exception as e:
+ logger.debug(f"Failed to set user: {e}")
+
+
+def set_tag(key: str, value: str) -> None:
+ """Set a tag on all future events.
+
+ Args:
+ key: Tag key
+ value: Tag value
+ """
+ if not _initialize_sentry() or _sentry_sdk is None:
+ return
+
+ try:
+ _sentry_sdk.set_tag(key, value)
+ except Exception as e:
+ logger.debug(f"Failed to set tag: {e}")
+
+
+def set_context(name: str, data: Dict[str, Any]) -> None:
+ """Set a context on all future events.
+
+ Args:
+ name: Context name
+ data: Context data (will be filtered for sensitive content)
+ """
+ if not _initialize_sentry() or _sentry_sdk is None:
+ return
+
+ try:
+ # Filter sensitive data
+ filtered_data = {}
+ for key, value in data.items():
+ if not any(
+ sensitive in key.lower()
+ for sensitive in ["prompt", "content", "message", "text", "input", "output"]
+ ):
+ filtered_data[key] = value
+
+ _sentry_sdk.set_context(name, filtered_data)
+ except Exception as e:
+ logger.debug(f"Failed to set context: {e}")
+
+
+def start_transaction(
+ name: str,
+ op: str,
+ description: Optional[str] = None,
+) -> Any:
+ """Start a performance transaction.
+
+ Args:
+ name: Transaction name
+ op: Operation type (e.g., "agent.run", "computer.action")
+ description: Optional description
+
+ Returns:
+ Transaction object (use as context manager)
+
+ Example:
+ with start_transaction("agent.run", "agent") as transaction:
+ # do work
+ transaction.set_tag("model", "claude-3")
+ """
+ if not _initialize_sentry() or _sentry_sdk is None:
+ # Return a no-op context manager
+ from contextlib import nullcontext
+ return nullcontext()
+
+ try:
+ return _sentry_sdk.start_transaction(
+ name=name,
+ op=op,
+ description=description,
+ )
+ except Exception as e:
+ logger.debug(f"Failed to start transaction: {e}")
+ from contextlib import nullcontext
+ return nullcontext()
+
+
+def flush(timeout: float = 2.0) -> None:
+ """Flush pending events to Sentry.
+
+ Args:
+ timeout: Timeout in seconds
+ """
+ if not _initialized or _sentry_sdk is None:
+ return
+
+ try:
+ _sentry_sdk.flush(timeout=timeout)
+ except Exception as e:
+ logger.debug(f"Failed to flush Sentry: {e}")
diff --git a/libs/python/core/pyproject.toml b/libs/python/core/pyproject.toml
index 05417c897b..b743e7751e 100644
--- a/libs/python/core/pyproject.toml
+++ b/libs/python/core/pyproject.toml
@@ -17,6 +17,25 @@ dependencies = [
]
requires-python = ">=3.12,<3.14"
+[project.optional-dependencies]
+# OpenTelemetry for operational metrics (Four Golden Signals)
+otel = [
+ "opentelemetry-api>=1.20.0",
+ "opentelemetry-sdk>=1.20.0",
+ "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+]
+# Sentry for error tracking
+sentry = [
+ "sentry-sdk>=1.39.0",
+]
+# All telemetry features
+telemetry = [
+ "opentelemetry-api>=1.20.0",
+ "opentelemetry-sdk>=1.20.0",
+ "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+ "sentry-sdk>=1.39.0",
+]
+
[tool.pdm]
distribution = true
@@ -28,6 +47,7 @@ source-includes = ["tests/", "README.md", "LICENSE"]
asyncio_mode = "auto"
testpaths = ["tests"]
python_files = "test_*.py"
+
[dependency-groups]
dev = [
"pytest>=8.3.5",