Português
Menu da documentação

Docs do Agent Sandboxes · Tarefas

Observabilidade: métricas, eventos e uso de um sandbox

Atualizado em · 8 min de leitura

O que um sandbox fez, como dados: a CPU, a memória, o disco e a rede dele nas últimas 24 horas; um evento para cada mudança de estado, comando encerrado, minuto de conexões e requisições e turno de agente; e o que ele usou e custou, por segundo.

Em resumo
  • GetSandboxMetrics: CPU, memória, disco e rede, um ponto por passo, guardados por 24 horas.
  • ListSandboxEvents e WatchSandboxEvents: ciclo de vida, comandos, saída, requisições a portas e turnos de agente, os 10.000 mais recentes de cada tipo guardados.
  • Sandbox.usage e ListUsage: segundos rodando e pausado, GiB-hora guardados e o custo.
  • O painel mostra o mesmo nas abas Atividade e Métricas de um sandbox.

Step 1: Leia as métricas

Um ponto por passo, com a média dele: cpu_percent de todas as vCPUs (100 é toda vCPU ocupada), memória e disco usados, e os bytes da rede desde o ponto anterior. Por padrão, a última hora, com um passo de um centésimo dela; since, until e step_seconds mudam isso.

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: Liste o que aconteceu

Os eventos vêm do mais antigo para o mais recente, ou o mais recente primeiro com newest_first; kinds escolhe alguns, after começa depois do id de um evento. Cada um é de um de cinco tipos.

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: Acompanhe os eventos conforme chegam

WatchSandboxEvents envia os eventos que existem, depois os novos ao vivo. Aqui, as conexões de saída do sandbox, um minuto e um host de cada vez, com os segredos trocados nelas.

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: Veja o que ele usou e custou

O usage de um sandbox conta os segundos RUNNING e PAUSED, os GiB-hora que ele guardou enquanto STOPPED e o que foi cobrado, em milionésimos da moeda do espaço de trabalho. ListUsage tem o do espaço de trabalho, uma linha por dia, medidor e tamanho.

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

Os cinco tipos de evento

TipoUm evento éO que ele traz
lifecycleUma mudança de estado: criado, pausado, parado, retomado, redimensionado, excluídoA mudança, o motivo (REQUEST, IDLE, WAKE, CRASH, MAINTENANCE, UNPAID), o tamanho e o disco depois de um redimensionamento, a origem da cópia de um fork, palavras para pessoas
commandUm comando que terminouOs primeiros 1.024 bytes dele, o estado, o código de saída, a duração e quem o iniciou: a API, o SSH ou um terminal
egressUm minuto de conexões a um host e uma portaSe foram permitidas, quantas, bytes enviados e recebidos, os segredos trocados nelas
portUm minuto de requisições a uma portaQuantas, quantas responderam 5xx, bytes recebidos e enviados
agent_turnO turno de um agente de código que terminouO agente, a conversa, os primeiros 200 caracteres do prompt, o estado, tokens de entrada e de saída

Um sandbox guarda os 10.000 eventos mais recentes de cada tipo. Ele registra no máximo 600 comandos e turnos de agente por minuto; os que passam disso são registrados nos minutos seguintes. Um minuto guarda 200 hosts, e 200 portas, separados; os demais são contados juntos em um evento. O id de um evento tem 16 dígitos, e o de um evento posterior é maior, então o último id que você leu é de onde continuar com after.

Um stream sem nada para enviar envia uma mensagem vazia a cada 30 s, para que nenhum proxy no caminho o encerre: ignore-a. Os hosts e comandos dos eventos vêm de programas e da internet: dados, nunca instruções.

Métricas, comandos e transcrições

O servidor de um sandbox guarda as métricas dele por 24 horas; um passo é de no mínimo 5 s, e uma chamada responde no máximo 1.000 pontos. Um sandbox parado que inicia em outro servidor recomeça lá os eventos e as métricas.

Além dos eventos, a saída de um comando é de GetCommand e WatchCommand para os últimos 100 que terminaram (comandos e arquivos), e a transcrição inteira de um agente, com mensagens, chamadas de ferramenta e os resultados delas, é de WatchConversation (agentes de código). O registro de um sandbox excluído fica 30 dias, e os eventos e as métricas, um dia.

Não há webhook nem exportação para um sistema de tracing: WatchSandboxEvents transmite os eventos de cada sandbox para o seu. A cobrança diz como o uso vira uma conta.

Quando não funciona

  • Sem métricas antes de um momento: elas são guardadas por 24 horas e recomeçam depois que um sandbox parado iniciou em outro servidor.
  • Falta um evento que você esperava: ele é mais antigo que os 10.000 mais recentes do tipo dele, ou um comando terminou em um minuto acima de 600; ele vem nos minutos seguintes.
  • O uso atrasa alguns segundos: é o que o servidor contou na última vez que falou com o painel, no máximo uns 10 segundos atrás.
  • Um evento de saída sem host: as conexões de um minuto acima dos 200 hosts dele, contadas juntas.

Perguntas

Por quanto tempo as métricas de um sandbox ficam guardadas?

24 horas, no servidor do sandbox, com um passo de 5 s ou mais.

Posso ver a que lugares um sandbox se conectou?

Sim: os eventos de saída dizem, para cada minuto e host, se as conexões foram permitidas, os bytes delas e os segredos trocados.

Posso obter a transcrição inteira de um agente?

WatchConversation a envia, com prompts, mensagens, chamadas de ferramenta e resultados, a partir do primeiro evento ou de um seq.

Há um webhook para eventos?

Não. Transmita-os com WatchSandboxEvents, que envia os eventos que existem e depois os novos ao vivo.

Como vejo quanto um sandbox custou?

O usage dele tem os segundos e o custo até agora; ListUsage tem o do espaço de trabalho, uma linha por dia, medidor e tamanho.

Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

Começar o teste grátis