System Metrics

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()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Get agent metrics snapshot
const metrics = await sandbox.getMetricsSnapshot();

console.log(`Uptime: ${metrics.uptime_seconds} seconds`);
console.log(`Total Executions: ${metrics.total_executions}`);
console.log(`Active Executions: ${metrics.active_executions}`);
console.log(`Error Count: ${metrics.error_count}`);

// Per-endpoint statistics
if (metrics.requests_total) {
  console.log('\nRequests by Endpoint:');
  for (const [endpoint, count] of Object.entries(metrics.requests_total)) {
    console.log(`  ${endpoint}: ${count}`);
  }
}

await 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()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Get agent metrics
const agentMetrics = await sandbox.getAgentMetrics();

console.log(`Agent Uptime: ${agentMetrics.uptime_seconds} seconds`);
console.log(`Total Executions: ${agentMetrics.total_executions}`);
console.log(`Active Executions: ${agentMetrics.active_executions}`);
console.log(`Error Count: ${agentMetrics.error_count}`);

// Per-endpoint metrics
if (agentMetrics.requests_total) {
  console.log('\nRequests by Endpoint:');
  for (const [endpoint, count] of Object.entries(agentMetrics.requests_total)) {
    console.log(`  ${endpoint}: ${count}`);
  }
}

if (agentMetrics.avg_duration_ms) {
  console.log('\nAverage Duration by Endpoint:');
  for (const [endpoint, duration] of Object.entries(agentMetrics.avg_duration_ms)) {
    console.log(`  ${endpoint}: ${duration.toFixed(2)} ms`);
  }
}

if (agentMetrics.p95_duration_ms) {
  console.log('\nP95 Duration by Endpoint:');
  for (const [endpoint, duration] of Object.entries(agentMetrics.p95_duration_ms)) {
    console.log(`  ${endpoint}: ${duration.toFixed(2)} ms`);
  }
}

await 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()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Monitor metrics every 5 seconds
for (let i = 0; i < 5; i++) {
  const metrics = await sandbox.getMetricsSnapshot();
  
  console.log(`Snapshot ${i+1}:`);
  console.log(`  Uptime: ${metrics.uptime_seconds}s`);
  console.log(`  Total Executions: ${metrics.total_executions}`);
  console.log(`  Active Executions: ${metrics.active_executions}`);
  console.log(`  Error Count: ${metrics.error_count}`);
  
  if (i < 4) {  // Don't sleep after last iteration
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

await 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()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Get baseline metrics
const baseline = await sandbox.getMetricsSnapshot();
console.log(`Baseline Executions: ${baseline.total_executions}`);
console.log(`Baseline Errors: ${baseline.error_count}`);

// Run some code
await sandbox.runCode(`
import time
for i in range(5):
    print(f"Step {i+1}")
    time.sleep(0.1)
`);

// Check metrics after execution
const after = await sandbox.getMetricsSnapshot();
console.log(`After Execution - Total: ${after.total_executions}`);
console.log(`After Execution - Errors: ${after.error_count}`);
console.log(`Executions Added: ${after.total_executions - baseline.total_executions}`);

await 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()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({
  template: 'code-interpreter'
});

// Get agent metrics
const metrics = await sandbox.getAgentMetrics();

// Calculate error rate
if (metrics.total_executions > 0) {
  const errorRate = (metrics.error_count / metrics.total_executions) * 100;
  console.log(`Error Rate: ${errorRate.toFixed(2)}%`);
} else {
  console.log('No executions yet');
}

// Find slowest endpoint
if (metrics.avg_duration_ms && Object.keys(metrics.avg_duration_ms).length > 0) {
  const slowest = Object.entries(metrics.avg_duration_ms)
    .reduce((a, b) => a[1] > b[1] ? a : b);
  console.log(`Slowest Endpoint: ${slowest[0]} (${slowest[1].toFixed(2)} ms)`);
}

await 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

Process Monitoring - Monitor running processes
SDK: sandbox.get_agent_metrics() - Python SDK method
API: GET /system - VM Agent API endpoint
CLI System Commands - System operations from CLI

Next Steps

Learn about Process Monitoring to track running processes
Explore Code Execution to execute code in sandboxes
Review Managing Sandbox State for lifecycle control

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Agent Metrics Snapshot

Agent Performance Metrics

Monitoring Agent Performance

Metrics Structure

Agent Metrics Response

Field Descriptions

Use Cases

Monitoring Execution Performance

Performance Analysis

Best Practices

API Reference

Python SDK

JavaScript SDK

API Endpoints

Next Steps

​Overview

​Agent Metrics Snapshot

​Agent Performance Metrics

​Monitoring Agent Performance

​Metrics Structure

​Agent Metrics Response

​Field Descriptions

​Use Cases

​Monitoring Execution Performance

​Performance Analysis

​Best Practices

​API Reference

​Python SDK

​JavaScript SDK

​API Endpoints

​Related

​Next Steps

Overview

Agent Metrics Snapshot

Agent Performance Metrics

Monitoring Agent Performance

Metrics Structure

Agent Metrics Response

Field Descriptions

Use Cases

Monitoring Execution Performance

Performance Analysis

Best Practices

API Reference

Python SDK

JavaScript SDK

API Endpoints

Related

Next Steps