Metrics

Vibengine provides real-time metrics for monitoring sandbox resource usage. You can track CPU utilization, memory consumption, and disk usage to understand how your sandbox workloads perform and when they need more resources.

Getting Sandbox Metrics

Use the getMetrics() method to retrieve a snapshot of current resource usage.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Run some work
await sandbox.commands.run('dd if=/dev/urandom of=/tmp/data bs=1M count=100')

// Get current metrics
const metrics = await sandbox.getMetrics()

console.log(`CPU Usage:    ${metrics.cpuPercent.toFixed(1)}%`)
console.log(`Memory Used:  ${(metrics.memoryUsedMiB).toFixed(1)} MiB`)
console.log(`Memory Total: ${(metrics.memoryTotalMiB).toFixed(1)} MiB`)
console.log(`Disk Used:    ${(metrics.diskUsedMiB).toFixed(1)} MiB`)
console.log(`Disk Total:   ${(metrics.diskTotalMiB).toFixed(1)} MiB`)

from vibengine import Sandbox

sandbox = Sandbox.create()

# Run some work
sandbox.commands.run("dd if=/dev/urandom of=/tmp/data bs=1M count=100")

# Get current metrics
metrics = sandbox.get_metrics()

print(f"CPU Usage:    {metrics.cpu_percent:.1f}%")
print(f"Memory Used:  {metrics.memory_used_mib:.1f} MiB")
print(f"Memory Total: {metrics.memory_total_mib:.1f} MiB")
print(f"Disk Used:    {metrics.disk_used_mib:.1f} MiB")
print(f"Disk Total:   {metrics.disk_total_mib:.1f} MiB")

Available Metrics

Metric	Description
`cpuPercent` / `cpu_percent`	Current CPU utilization as a percentage (0-100+)
`memoryUsedMiB` / `memory_used_mib`	Memory currently in use (MiB)
`memoryTotalMiB` / `memory_total_mib`	Total memory available to the sandbox (MiB)
`diskUsedMiB` / `disk_used_mib`	Disk space currently in use (MiB)
`diskTotalMiB` / `disk_total_mib`	Total disk space available (MiB)

CPU percentage can exceed 100% on multi-core sandboxes. For example, a 4-core sandbox at full utilization would report approximately 400%.

Polling for Metrics

To monitor resource usage over time, poll metrics at regular intervals.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Start a CPU-intensive task in the background
await sandbox.commands.run(
  'python3 -c "import hashlib; [hashlib.sha256(str(i).encode()) for i in range(10_000_000)]"',
  { background: true }
)

// Poll metrics every 2 seconds
const interval = setInterval(async () => {
  try {
    const metrics = await sandbox.getMetrics()
    const timestamp = new Date().toISOString()
    console.log(
      `[${timestamp}] CPU: ${metrics.cpuPercent.toFixed(1)}% | ` +
      `Memory: ${metrics.memoryUsedMiB.toFixed(0)}/${metrics.memoryTotalMiB.toFixed(0)} MiB | ` +
      `Disk: ${metrics.diskUsedMiB.toFixed(0)}/${metrics.diskTotalMiB.toFixed(0)} MiB`
    )
  } catch {
    clearInterval(interval)
  }
}, 2000)

// Stop after 20 seconds
setTimeout(() => clearInterval(interval), 20_000)

import time
from vibengine import Sandbox

sandbox = Sandbox.create()

# Start a CPU-intensive task in the background
sandbox.commands.run(
    'python3 -c "import hashlib; [hashlib.sha256(str(i).encode()) for i in range(10_000_000)]"',
    background=True,
)

# Poll metrics every 2 seconds
for _ in range(10):
    metrics = sandbox.get_metrics()
    print(
        f"CPU: {metrics.cpu_percent:.1f}% | "
        f"Memory: {metrics.memory_used_mib:.0f}/{metrics.memory_total_mib:.0f} MiB | "
        f"Disk: {metrics.disk_used_mib:.0f}/{metrics.disk_total_mib:.0f} MiB"
    )
    time.sleep(2)

Monitoring Memory Usage

Track memory to detect leaks or ensure your workload fits within the sandbox limits.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

// Check initial memory
const before = await sandbox.getMetrics()
console.log(`Memory before: ${before.memoryUsedMiB.toFixed(1)} MiB`)

// Load a large dataset
await sandbox.commands.run(
  'python3 -c "data = list(range(10_000_000)); print(len(data))"'
)

// Check memory after
const after = await sandbox.getMetrics()
console.log(`Memory after: ${after.memoryUsedMiB.toFixed(1)} MiB`)
console.log(`Memory delta: ${(after.memoryUsedMiB - before.memoryUsedMiB).toFixed(1)} MiB`)

from vibengine import Sandbox

sandbox = Sandbox.create()

# Check initial memory
before = sandbox.get_metrics()
print(f"Memory before: {before.memory_used_mib:.1f} MiB")

# Load a large dataset
sandbox.commands.run(
    'python3 -c "data = list(range(10_000_000)); print(len(data))"'
)

# Check memory after
after = sandbox.get_metrics()
print(f"Memory after: {after.memory_used_mib:.1f} MiB")
print(f"Memory delta: {after.memory_used_mib - before.memory_used_mib:.1f} MiB")

Monitoring Disk Usage

Track disk usage to avoid running out of space during file-heavy operations.

import { Sandbox } from 'vibengine'

const sandbox = await Sandbox.create()

const metrics = await sandbox.getMetrics()
const usedPercent = (metrics.diskUsedMiB / metrics.diskTotalMiB * 100).toFixed(1)

console.log(`Disk: ${metrics.diskUsedMiB.toFixed(0)} / ${metrics.diskTotalMiB.toFixed(0)} MiB (${usedPercent}%)`)

if (metrics.diskUsedMiB / metrics.diskTotalMiB > 0.9) {
  console.warn('Warning: Disk usage is above 90%!')
}

from vibengine import Sandbox

sandbox = Sandbox.create()

metrics = sandbox.get_metrics()
used_percent = metrics.disk_used_mib / metrics.disk_total_mib * 100

print(f"Disk: {metrics.disk_used_mib:.0f} / {metrics.disk_total_mib:.0f} MiB ({used_percent:.1f}%)")

if used_percent > 90:
    print("Warning: Disk usage is above 90%!")

If a sandbox runs out of disk space, file writes and package installations will fail. Monitor disk usage when working with large files or installing many packages.

Sandbox Lifecycle — manage timeouts based on resource usage
Execute Commands — run workloads and monitor their impact
Persistence — save state before sandbox resources are reclaimed

Metrics

Metrics

Getting Sandbox Metrics

Available Metrics

Polling for Metrics

Monitoring Memory Usage

Monitoring Disk Usage

Use Cases

Auto-Scaling Decisions

Cost Optimization

Debugging Performance

Next Steps

On this page