Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

Observabilité : métriques, événements et consommation d’une sandbox

Mis à jour le · 8 min de lecture

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.

En bref
  • GetSandboxMetrics : CPU, mémoire, disque et réseau, un point par pas, gardés 24 heures.
  • ListSandboxEvents et WatchSandboxEvents : 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.usage et ListUsage : 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.

Python
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
TypeScript
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");
}
Go
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)
}
Rust
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.

Python
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
TypeScript
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);
}
Go
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")
	}
}
Rust
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),
        _ => {}
    }
}
CLI
$ 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.

Python
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 ()
# …
TypeScript
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);
}
Go
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)
	}
}
Rust
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);
    }
}
CLI
$ 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.

Python
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
TypeScript
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);
Go
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)
}
Rust
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);
}
CLI
$ 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

TypeUn événement, c’estIl contient
lifecycleUn changement d’état : créée, mise en pause, arrêtée, reprise, redimensionnée, suppriméeLe 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
commandUne commande terminéeSes 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
egressUne minute de connexions vers un hôte et un portSi elles ont été autorisées, combien, les octets sortants et entrants, les secrets qui y ont été substitués
portUne minute de requêtes vers un portCombien, combien ont répondu 5xx, les octets entrants et sortants
agent_turnUn 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.

Démarrer l’essai gratuit