> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# System Metrics

> Get agent performance metrics including uptime, execution counts, and error rates. Monitor CPU, memory, and disk usage in HopX sandboxes to optimize performance and troubleshoot issues. Learn how to retrieve system metrics, track resource usage over time, and use metrics for capacity planning. Includes Python and JavaScript SDK examples and REST API endpoints.

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

<Note>
  Both `get_metrics_snapshot()` and `get_agent_metrics()` return agent performance metrics. They provide the same data structure.
</Note>

## Agent Metrics Snapshot

Get a snapshot of current agent performance metrics:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    ```
  </Tab>
</Tabs>

## Agent Performance Metrics

Get detailed agent performance metrics:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    ```
  </Tab>
</Tabs>

## Monitoring Agent Performance

Monitor agent metrics over time to track performance:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    ```
  </Tab>
</Tabs>

## Metrics Structure

### Agent Metrics Response

Both `get_metrics_snapshot()` and `get_agent_metrics()` return the same structure:

```json theme={null}
{
  "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:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    ```
  </Tab>
</Tabs>

### Performance Analysis

Analyze agent performance to identify bottlenecks:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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();
    ```
  </Tab>
</Tabs>

## Best Practices

<Tip>
  **Monitor metrics before and after operations** to track execution performance and identify bottlenecks or error patterns.
</Tip>

<Tip>
  **Use agent metrics** to identify frequently used endpoints and optimize your code patterns accordingly.
</Tip>

<Warning>
  **Metrics are snapshots**, not continuous monitoring. For real-time streaming metrics, use the [monitoring endpoint](/core-concepts/observability/monitoring) with SSE.
</Warning>

<Tip>
  **Check agent version** before using agent metrics. Use `sandbox.get_agent_info()` to verify v3.1.0+ support.
</Tip>

## 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

## Related

* **[Process Monitoring](/core-concepts/observability/processes)** - Monitor running processes
* **SDK**: [sandbox.get\_agent\_metrics()](/sdk/python/sandbox#get_agent_metrics) - Python SDK method
* **API**: [GET /system](/api/vm-agent/get-system-metrics) - VM Agent API endpoint
* [CLI System Commands](/cli/commands/system) - System operations from CLI

## Next Steps

* Learn about [Process Monitoring](/core-concepts/observability/processes) to track running processes
* Explore [Code Execution](/core-concepts/code-execution/synchronous) to execute code in sandboxes
* Review [Managing Sandbox State](/core-concepts/sandboxes/managing-state) for lifecycle control