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:
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();
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();
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 secondstotal_executions: Total number of code executions processedactive_executions: Currently running executionserror_count: Total number of errors encounteredrequests_total: Per-endpoint request countsavg_duration_ms: Average request duration by endpoint (milliseconds)p95_duration_ms: 95th percentile request duration by endpoint (milliseconds)
Use Cases
Monitor agent performance during code execution:
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();
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 snapshotsandbox.get_agent_metrics() - Get agent performance metrics (same as get_metrics_snapshot)
JavaScript SDK
sandbox.getMetricsSnapshot() - Get agent performance metrics snapshotsandbox.getAgentMetrics() - Get agent performance metrics (same as getMetricsSnapshot)
API Endpoints
- GET
/metrics/snapshot - Get agent performance metrics snapshot
Next Steps
