Skip to main content
Monitor your sandbox’s agent performance in real-time with execution metrics. Track uptime, execution counts, error rates, and per-endpoint statistics to optimize your workloads and troubleshoot issues.

​
Overview

HopX provides agent performance metrics to monitor sandbox execution performance:
  • Agent Metrics: Agent performance metrics including uptime, execution counts, error rates, and per-endpoint statistics
Both get_metrics_snapshot() and get_agent_metrics() return agent performance metrics. They provide the same data structure.

​
Agent Metrics Snapshot

Get a snapshot of current agent performance metrics:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Get agent metrics snapshot
metrics = sandbox.get_metrics_snapshot()

print(f"Uptime: {metrics['uptime_seconds']} seconds")
print(f"Total Executions: {metrics['total_executions']}")
print(f"Active Executions: {metrics['active_executions']}")
print(f"Error Count: {metrics['error_count']}")

# Per-endpoint statistics
if 'requests_total' in metrics:
    print("\nRequests by Endpoint:")
    for endpoint, count in metrics['requests_total'].items():
        print(f"  {endpoint}: {count}")

sandbox.kill()

​
Agent Performance Metrics

Get detailed agent performance metrics:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Get agent metrics
agent_metrics = sandbox.get_agent_metrics()

print(f"Agent Uptime: {agent_metrics['uptime_seconds']} seconds")
print(f"Total Executions: {agent_metrics['total_executions']}")
print(f"Active Executions: {agent_metrics['active_executions']}")
print(f"Error Count: {agent_metrics['error_count']}")

# Per-endpoint metrics
if 'requests_total' in agent_metrics:
    print("\nRequests by Endpoint:")
    for endpoint, count in agent_metrics['requests_total'].items():
        print(f"  {endpoint}: {count}")

if 'avg_duration_ms' in agent_metrics:
    print("\nAverage Duration by Endpoint:")
    for endpoint, duration in agent_metrics['avg_duration_ms'].items():
        print(f"  {endpoint}: {duration:.2f} ms")

if 'p95_duration_ms' in agent_metrics:
    print("\nP95 Duration by Endpoint:")
    for endpoint, duration in agent_metrics['p95_duration_ms'].items():
        print(f"  {endpoint}: {duration:.2f} ms")

sandbox.kill()

​
Monitoring Agent Performance

Monitor agent metrics over time to track performance:
  • Python
  • JavaScript
from hopx_ai import Sandbox
import time

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

# Monitor metrics every 5 seconds
for i in range(5):
    metrics = sandbox.get_metrics_snapshot()
    
    print(f"Snapshot {i+1}:")
    print(f"  Uptime: {metrics['uptime_seconds']}s")
    print(f"  Total Executions: {metrics['total_executions']}")
    print(f"  Active Executions: {metrics['active_executions']}")
    print(f"  Error Count: {metrics['error_count']}")
    
    if i < 4:  # Don't sleep after last iteration
        time.sleep(5)

sandbox.kill()

​
Metrics Structure

​
Agent Metrics Response

Both get_metrics_snapshot() and get_agent_metrics() return the same structure: 
{
  "uptime_seconds": 1234,
  "total_executions": 1250,
  "active_executions": 2,
  "error_count": 3,
  "requests_total": {
    "/execute": 800,
    "/files/read": 300,
    "/files/write": 150
  },
  "avg_duration_ms": {
    "/execute": 1250.5,
    "/files/read": 45.2,
    "/files/write": 78.9
  },
  "p95_duration_ms": {
    "/execute": 2500.0,
    "/files/read": 100.0,
    "/files/write": 150.0
  }
}

​
Field Descriptions

  • uptime_seconds: Agent uptime in seconds
  • total_executions: Total number of code executions processed
  • active_executions: Currently running executions
  • error_count: Total number of errors encountered
  • requests_total: Per-endpoint request counts
  • avg_duration_ms: Average request duration by endpoint (milliseconds)
  • p95_duration_ms: 95th percentile request duration by endpoint (milliseconds)

​
Use Cases

​
Monitoring Execution Performance

Monitor agent performance during code execution:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Get baseline metrics
baseline = sandbox.get_metrics_snapshot()
print(f"Baseline Executions: {baseline['total_executions']}")
print(f"Baseline Errors: {baseline['error_count']}")

# Run some code
sandbox.run_code("""
import time
for i in range(5):
    print(f"Step {i+1}")
    time.sleep(0.1)
""")

# Check metrics after execution
after = sandbox.get_metrics_snapshot()
print(f"After Execution - Total: {after['total_executions']}")
print(f"After Execution - Errors: {after['error_count']}")
print(f"Executions Added: {after['total_executions'] - baseline['total_executions']}")

sandbox.kill()

​
Performance Analysis

Analyze agent performance to identify bottlenecks:
  • Python
  • JavaScript
from hopx_ai import Sandbox

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

# Get agent metrics
metrics = sandbox.get_agent_metrics()

# Calculate error rate
if metrics['total_executions'] > 0:
    error_rate = (metrics['error_count'] / metrics['total_executions']) * 100
    print(f"Error Rate: {error_rate:.2f}%")
else:
    print("No executions yet")

# Find slowest endpoint
if 'avg_duration_ms' in metrics and metrics['avg_duration_ms']:
    slowest = max(metrics['avg_duration_ms'].items(), key=lambda x: x[1])
    print(f"Slowest Endpoint: {slowest[0]} ({slowest[1]:.2f} ms)")

sandbox.kill()

​
Best Practices

Monitor metrics before and after operations to track execution performance and identify bottlenecks or error patterns.
Use agent metrics to identify frequently used endpoints and optimize your code patterns accordingly.
Metrics are snapshots, not continuous monitoring. For real-time streaming metrics, use the monitoring endpoint with SSE.
Check agent version before using agent metrics. Use sandbox.get_agent_info() to verify v3.1.0+ support.

​
API Reference

​
Python SDK

  • sandbox.get_metrics_snapshot() - Get agent performance metrics snapshot
  • sandbox.get_agent_metrics() - Get agent performance metrics (same as get_metrics_snapshot)

​
JavaScript SDK

  • sandbox.getMetricsSnapshot() - Get agent performance metrics snapshot
  • sandbox.getAgentMetrics() - Get agent performance metrics (same as getMetricsSnapshot)

​
API Endpoints

  • GET /metrics/snapshot - Get agent performance metrics snapshot

​
Next Steps