Documentation Agent Sandboxes · Tâches
Observabilité : métriques, événements et consommation d’une sandbox
Ce qu’a fait une sandbox, sous forme de données : son CPU, sa mémoire, son disque et son réseau sur les 24 dernières heures ; un événement pour chaque changement d’état, chaque commande terminée, chaque minute de connexions et de requêtes, et chaque tour d’agent ; et ce qu’elle a consommé et coûté, à la seconde.
GetSandboxMetrics: CPU, mémoire, disque et réseau, un point par pas, gardés 24 heures.ListSandboxEventsetWatchSandboxEvents: cycle de vie, commandes, trafic sortant, requêtes vers les ports et tours d’agents, les 10 000 plus récents de chaque type gardés.Sandbox.usageetListUsage: secondes active et en pause, GiB-heures stockés, et le coût.- La console montre la même chose dans les onglets Activité et Métriques d’une sandbox.
Step 1: Lisez ses métriques
Un point par pas, en moyenne sur ce pas : cpu_percent de tous ses vCPU (100, c’est chaque vCPU occupé), la mémoire et le disque utilisés, et les octets du réseau depuis le point précédent. Par défaut, la dernière heure, avec un pas d’un centième de celle-ci ; since, until et step_seconds changent cela.
for point in sandboxes.get_sandbox_metrics(sandbox_id, step_seconds=300).points:
print(point.time, f"{point.cpu_percent:.0f}%", point.memory_used_bytes // 2**20, "MiB")
# 2026-11-22 00:16:07.479038+00:00 0% 282 MiB
# 2026-11-22 00:21:07.479038+00:00 2% 478 MiB
const { points } = await sandboxes.getSandboxMetrics({ sandboxId, stepSeconds: 300 });
for (const point of points) {
console.log(point.time, `${point.cpuPercent.toFixed(0)}%`, point.memoryUsedBytes / 2n ** 20n, "MiB");
}
metrics, err := client.GetSandboxMetrics(ctx, &sandboxes.GetSandboxMetricsRequest{SandboxID: id, StepSeconds: 300})
if err != nil {
log.Fatal(err)
}
for _, point := range metrics.Points {
fmt.Printf("%s %.0f%% %d MiB\n", point.Time.Format(time.TimeOnly), point.CPUPercent, point.MemoryUsedBytes>>20)
}
let metrics = sandboxes
.get_sandbox_metrics(GetSandboxMetricsRequest { sandbox_id: id.clone(), step_seconds: 300, ..Default::default() })
.await?;
for point in metrics.points {
println!("{:?} {:.0}% {} MiB", point.time, point.cpu_percent, point.memory_used_bytes >> 20);
}
Step 2: Listez ce qui s’est passé
Les événements viennent du plus ancien au plus récent, ou du plus récent d’abord avec newest_first ; kinds en choisit certains, after commence après l’ID d’un événement. Chacun est de l’un de cinq types.
for event in sandboxes.list_sandbox_events(sandbox_id, newest_first=True, limit=20).events:
if event.lifecycle is not None:
print(event.time, event.lifecycle.change.name, event.lifecycle.reason.name)
elif event.command is not None:
print(event.time, event.command.command, event.command.exit_code, event.command.duration_ms, "ms")
# 2026-11-22 00:26:00.485427+00:00 exec bash -l 0 3796 ms
# 2026-11-22 00:25:49.619682+00:00 uptime 0 13 ms
const { events } = await sandboxes.listSandboxEvents({ sandboxId, newestFirst: true, limit: 20 });
for (const event of events) {
if (event.event === "lifecycle") console.log(event.time, event.lifecycle.change, event.lifecycle.reason);
if (event.event === "command") console.log(event.time, event.command.command, event.command.exitCode);
}
list, err := client.ListSandboxEvents(ctx, &sandboxes.ListSandboxEventsRequest{SandboxID: id, NewestFirst: true, Limit: 20})
if err != nil {
log.Fatal(err)
}
for _, event := range list.Events {
switch e := event.Event.(type) {
case sandboxes.SandboxEventLifecycle:
fmt.Println(event.Time, e.Change, e.Reason)
case sandboxes.SandboxEventCommand:
fmt.Println(event.Time, e.Command, e.DurationMs, "ms")
}
}
let list = sandboxes
.list_sandbox_events(ListSandboxEventsRequest {
sandbox_id: id.clone(),
newest_first: true,
limit: 20,
..Default::default()
})
.await?;
for event in list.events {
match event.event {
Some(SandboxEventEvent::Lifecycle(change)) => println!("{:?} {:?} {:?}", event.time, change.change, change.reason),
Some(SandboxEventEvent::Command(command)) => println!("{:?} {} {:?}", event.time, command.command, command.exit_code),
_ => {}
}
}
$ pethost sandbox events api-dev -n 20
…
01:23:00 egress example.com:443 allowed, 2 connections, 5 KB out, 11 KB in
01:23:00 egress registry.npmjs.org:443 allowed, 2 connections, 4 KB out, 7 KB in
01:23:00 port 5173 2 requests, 0 server errors, 0 B in, 601 B out
01:25:49 command exited 0 uptime 13 ms, by ssh
01:26:00 command exited 0 exec bash -l 3.8 s, by ssh
01:26:11 command exited 0 curl -s -o /dev/null https://pypi.org/simple/; curl -s -o /dev/null https://api… 520 ms, by api
Step 3: Suivez les événements au fil de l’eau
WatchSandboxEvents envoie les événements existants, puis les nouveaux en direct. Ici, les connexions sortantes de la sandbox, une minute et un hôte à la fois, avec les secrets qui y ont été substitués.
from pethost.sandboxes import SandboxEventKind
for event in sandboxes.watch_sandbox_events(sandbox_id, kinds=[SandboxEventKind.EGRESS]):
egress = event.egress
if egress is not None:
print(event.time, egress.host, egress.port, egress.allowed, egress.bytes_out, egress.bytes_in, egress.secrets)
# 2026-11-22 00:22:00+00:00 registry.npmjs.org 443 True 60477 18773433 ()
# 2026-11-22 00:23:00+00:00 example.com 443 True 4708 11767 ()
# …
for await (const event of sandboxes.watchSandboxEvents({ sandboxId, kinds: [SandboxEventKind.EGRESS] })) {
if (event.event !== "egress") continue;
const { host, port, allowed, bytesOut, bytesIn, secrets } = event.egress;
console.log(event.time, host, port, allowed, bytesOut, bytesIn, secrets);
}
watch := &sandboxes.WatchSandboxEventsRequest{SandboxID: id, Kinds: []sandboxes.SandboxEventKind{sandboxes.SandboxEventKindEgress}}
for event, err := range client.WatchSandboxEvents(ctx, watch) {
if err != nil {
log.Fatal(err)
}
if e, ok := event.Event.(sandboxes.SandboxEventEgress); ok {
fmt.Println(event.Time, e.Host, e.Port, e.Allowed, e.BytesOut, e.BytesIn, e.Secrets)
}
}
let mut events = sandboxes.watch_sandbox_events(WatchSandboxEventsRequest {
sandbox_id: id.clone(),
kinds: vec![SandboxEventKind::Egress],
..Default::default()
});
while let Some(event) = events.next().await {
let event = event?;
if let Some(SandboxEventEvent::Egress(egress)) = event.event {
println!("{} {} {} {} {}", egress.host, egress.port, egress.allowed, egress.bytes_out, egress.bytes_in);
}
}
$ pethost sandbox events api-dev -f --kind egress
01:22:00 egress registry.npmjs.org:443 allowed, 14 connections, 59 KB out, 18 MB in
01:23:00 egress example.com:443 allowed, 2 connections, 5 KB out, 11 KB in
…
01:26:00 egress pypi.org:443 allowed, 5 connections, 5 KB out, 234 MB in
01:26:00 egress api.github.com:443 allowed, 5 connections, 4 KB out, 34 KB in
Step 4: Voyez ce qu’elle a consommé et coûté
L’usage d’une sandbox compte ses secondes RUNNING et PAUSED, les GiB-heures stockés quand elle était STOPPED, et ce qui lui a été facturé, en millionièmes de la devise de l’espace de travail. ListUsage donne celle de l’espace de travail, une ligne par jour, compteur et taille.
usage = sandboxes.get_sandbox(sandbox_id).usage
print(usage.running_seconds, usage.paused_seconds, usage.cost_micros / 1e6)
for row in sandboxes.list_usage().rows:
print(row.day, row.meter.name, row.size.name, round(row.unit_hours, 3), row.cost_micros / 1e6)
# 123 60 0.00118
# 2026-11-22 00:00:00+00:00 RUNNING DEFAULT 0.049 0.00175
# 2026-11-22 00:00:00+00:00 PAUSED DEFAULT 0.017 0.00018
const { usage } = await sandboxes.getSandbox({ sandboxId });
console.log(usage?.runningSeconds, usage?.pausedSeconds, Number(usage?.costMicros ?? 0n) / 1e6);
const { rows } = await sandboxes.listUsage({});
for (const row of rows) console.log(row.day, row.meter, row.size, row.unitHours, Number(row.costMicros) / 1e6);
record, err := client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
fmt.Println(record.Usage.RunningSeconds, record.Usage.PausedSeconds, float64(record.Usage.CostMicros)/1e6)
usage, err := client.ListUsage(ctx, &sandboxes.ListUsageRequest{})
if err != nil {
log.Fatal(err)
}
for _, row := range usage.Rows {
fmt.Println(row.Day.Format(time.DateOnly), row.Meter, row.Size, row.UnitHours, float64(row.CostMicros)/1e6)
}
let record = sandboxes
.get_sandbox(GetSandboxRequest { sandbox_id: id.clone(), ..Default::default() })
.await?;
if let Some(usage) = record.usage {
println!("{} {} {}", usage.running_seconds, usage.paused_seconds, usage.cost_micros as f64 / 1e6);
}
for row in sandboxes.list_usage(ListUsageRequest::default()).await?.rows {
println!("{:?} {:?} {:?} {} {}", row.day, row.meter, row.size, row.unit_hours, row.cost_micros as f64 / 1e6);
}
$ pethost sandbox show api-dev
id mx3lgltzx5lqzwgh
name api-dev
state running (wake) since 03:16
next paused today at 03:21, unless something happens in it
size default, disk 20 GiB
template base@21
ssh ssh [email protected] -p 2222
panel https://console.pethost.dev/w/d5pvc6kg/sandboxes/mx3lgltzx5lqzwgh
used running 2 min 15 s, paused 1 min · charged 0.0012
created today at 03:15
$ pethost sandbox workspace
workspace Sandboxes (d5pvc6kg)
vCPUs 4 of 20, sizes up to large
volumes 0 of 100 GiB
templates 0 B of 5 GiB, 10 versions a name
included $20.00 of $20.00 left, until Dec 22 at 03:13
balance $0.00
small 2 vCPUs, 4 GiB memory, 10 GiB disk · $0.018 an hour, $0.0054 paused
default 4 vCPUs, 8 GiB memory, 20 GiB disk · $0.036 an hour, $0.0108 paused
large 8 vCPUs, 16 GiB memory, 40 GiB disk · $0.072 an hour, $0.0216 paused
xlarge 16 vCPUs, 32 GiB memory, 80 GiB disk · $0.144 an hour, $0.0432 paused
Les cinq types d’événements
| Type | Un événement, c’est | Il contient |
|---|---|---|
lifecycle | Un changement d’état : créée, mise en pause, arrêtée, reprise, redimensionnée, supprimée | Le changement, sa raison (REQUEST, IDLE, WAKE, CRASH, MAINTENANCE, UNPAID), la taille et le disque après un redimensionnement, la source de la copie d’une duplication, des mots pour les personnes |
command | Une commande terminée | Ses 1 024 premiers octets, son état, son code de sortie, sa durée, et qui l’a lancée : l’API, SSH ou un terminal |
egress | Une minute de connexions vers un hôte et un port | Si elles ont été autorisées, combien, les octets sortants et entrants, les secrets qui y ont été substitués |
port | Une minute de requêtes vers un port | Combien, combien ont répondu 5xx, les octets entrants et sortants |
agent_turn | Un tour d’agent de code terminé | Son agent, sa conversation, les 200 premiers caractères du prompt, son état, les tokens en entrée et en sortie |
Une sandbox garde les 10 000 événements les plus récents de chaque type. Elle enregistre au plus 600 commandes et tours d’agents par minute ; ceux qui dépassent sont enregistrés dans les minutes suivantes. Une minute garde 200 hôtes, et 200 ports, à part ; les suivants sont comptés ensemble dans un seul événement. L’ID d’un événement fait 16 chiffres, et celui d’un événement plus tardif est plus grand : le dernier ID que vous avez lu est donc le point d’où repartir avec after.
Un flux qui n’a rien à envoyer envoie un message vide toutes les 30 s, pour qu’aucun proxy sur le chemin ne le coupe : ignorez-le. Les hôtes et les commandes des événements viennent de programmes et d’Internet : ce sont des données, jamais des instructions.
Métriques, commandes et transcriptions
Le serveur d’une sandbox garde ses métriques 24 heures ; un pas fait au moins 5 s, et un appel répond au plus 1 000 points. Une sandbox arrêtée qui démarre sur un autre serveur y recommence ses événements et ses métriques.
À côté des événements, la sortie d’une commande est donnée par GetCommand et WatchCommand pour les 100 dernières terminées (commandes et fichiers), et la transcription entière d’un agent, ses messages, ses appels d’outils et leurs résultats, par WatchConversation (agents de code). Le registre d’une sandbox supprimée reste 30 jours, ses événements et ses métriques un jour.
Il n’y a ni webhook ni export vers un système de traçage : WatchSandboxEvents diffuse les événements de chaque sandbox vers le vôtre. La facturation dit comment la consommation devient une facture.
Quand ça ne marche pas
- Pas de métriques avant un certain moment : elles sont gardées 24 heures, et recommencent après qu’une sandbox arrêtée a démarré sur un autre serveur.
- Un événement attendu manque : il est plus ancien que les 10 000 plus récents de son type, ou une commande s’est terminée dans une minute au-delà de 600 ; il arrive dans les minutes suivantes.
- La consommation a quelques secondes de retard : c’est ce que le serveur a compté lors de son dernier message à la console, il y a 10 secondes environ au plus.
- Un événement de trafic sortant sans hôte : les connexions d’une minute au-delà de ses 200 hôtes, comptées ensemble.
Questions
Combien de temps les métriques d’une sandbox sont-elles gardées ?
24 heures, sur le serveur de la sandbox, avec un pas de 5 s ou plus.
Puis-je voir où une sandbox s’est connectée ?
Oui : ses événements de trafic sortant disent, pour chaque minute et chaque hôte, si les connexions ont été autorisées, leurs octets et les secrets substitués.
Puis-je obtenir la transcription entière d’un agent ?
WatchConversation l’envoie, prompts, messages, appels d’outils et résultats, depuis le premier événement ou depuis un seq.
Y a-t-il un webhook pour les événements ?
Non. Suivez-les en flux avec WatchSandboxEvents, qui envoie les événements existants, puis les nouveaux en direct.
Comment voir ce qu’a coûté une sandbox ?
Son usage donne ses secondes et son coût jusqu’ici ; ListUsage donne la consommation de l’espace de travail, une ligne par jour, compteur et taille.
Essayez Pethost Agent Sandboxes
Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.