Skip to main content
Hopx provides comprehensive observability to help you monitor sandbox performance, debug issues, and optimize resource usage.

​
Metrics

Get real-time metrics about your sandbox’s resource usage:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Get current metrics
metrics = sandbox.get_metrics_snapshot()

# Access nested metrics structure
system = metrics.get('system', {})
cpu = system.get('cpu', {})
memory = system.get('memory', {})
disk = system.get('disk', {})

print(f"CPU Usage: {cpu.get('usage_percent', 0)}%")
print(f"Memory: {memory.get('used', 0) / 1024 / 1024:.2f} MB / {memory.get('total', 0) / 1024 / 1024:.2f} MB")
print(f"Disk: {disk.get('used', 0) / 1024 / 1024 / 1024:.2f} GB / {disk.get('total', 0) / 1024 / 1024 / 1024:.2f} GB")

sandbox.kill()  # Cleanup

​
Available Metrics

  • CPU Usage: Percentage of CPU cores in use
  • Memory Usage: Current memory usage vs. total allocated
  • Disk Usage: Current disk usage vs. total allocated
  • Network I/O: Network traffic statistics (if available)

​
Request Tracing

Every API request returns a unique Request-ID header for debugging:
  • Python
  • JavaScript/TypeScript
from hopx_ai import Sandbox, APIError

sandbox = Sandbox.create(template="code-interpreter")

try:
    result = sandbox.run_code("print('test')")
except APIError as e:
    if e.request_id:
    print(f"Error - Request ID: {e.request_id}")
    # Share this ID with support for debugging
    else:
        print(f"Error: {e}")

sandbox.kill()  # Cleanup
Always include the Request ID when reporting issues or contacting support. It helps us trace the exact request and diagnose problems quickly.

​
Monitoring Best Practices

Regularly check metrics to ensure you’re using resources efficiently:
  • Python
  • JavaScript/TypeScript
import time

# Monitor metrics over time
for i in range(10):
    metrics = sandbox.get_metrics_snapshot()
    system = metrics.get('system', {})
    cpu = system.get('cpu', {})
    memory = system.get('memory', {})
    print(f"CPU: {cpu.get('usage_percent', 0)}%, Memory: {memory.get('used', 0) / 1024 / 1024:.2f}MB")
    time.sleep(5)

sandbox.kill()  # Cleanup
Log request IDs for important operations:
  • Python
  • JavaScript/TypeScript
import logging

logger = logging.getLogger(__name__)

try:
    result = sandbox.run_code("important_operation()")
    # Note: ExecutionResult doesn't have request_id, but errors do
    logger.info("Operation successful")
except Exception as e:
    if hasattr(e, 'request_id') and e.request_id:
    logger.error(f"Operation failed - Request ID: {e.request_id}")
    else:
        logger.error(f"Operation failed: {e}")

sandbox.kill()  # Cleanup
Monitor metrics and set up alerts for unusual activity:
  • Python
  • JavaScript/TypeScript
metrics = sandbox.get_metrics_snapshot()
system = metrics.get('system', {})
cpu = system.get('cpu', {})
memory = system.get('memory', {})

# Alert if CPU usage is high
cpu_percent = cpu.get('usage_percent', 0)
if cpu_percent > 90:
    print("⚠️ High CPU usage detected!")

# Alert if memory is low
memory_used = memory.get('used', 0)
memory_total = memory.get('total', 1)
memory_usage = memory_used / memory_total if memory_total > 0 else 0
if memory_usage > 0.9:
    print("⚠️ Low memory available!")

sandbox.kill()  # Cleanup

​
Logging

View sandbox logs to understand what’s happening inside:
  • Python
  • JavaScript/TypeScript
# Stream logs (if available)
# for log in sandbox.stream_logs():
#     print(log.message)
Logging features may vary by template and configuration. Check the SDK documentation for available logging methods.

​
Integration with Monitoring Tools

You can integrate Hopx metrics with external monitoring tools:

​
Prometheus

Export metrics in Prometheus format (if supported):
  • Python
  • JavaScript/TypeScript
metrics = sandbox.get_metrics_snapshot()
system = metrics.get('system', {})
cpu = system.get('cpu', {})
memory = system.get('memory', {})
disk = system.get('disk', {})

# Format for Prometheus
prometheus_metrics = f"""
hopx-ai_cpu_usage{{sandbox_id="{sandbox.sandbox_id}"}} {cpu.get('usage_percent', 0)}
hopx-ai_memory_used{{sandbox_id="{sandbox.sandbox_id}"}} {memory.get('used', 0) / 1024 / 1024}
hopx-ai_disk_used{{sandbox_id="{sandbox.sandbox_id}"}} {disk.get('used', 0) / 1024 / 1024 / 1024}
"""

sandbox.kill()  # Cleanup

​
Next Steps

Core Concepts

Back to Core Concepts overview

Resources

Configure resources based on metrics

Cost Optimization

Optimize costs using metrics

Architecture

Understand the architecture