Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Zadania

Obserwowalność: metryki, zdarzenia i zużycie sandboxa

Zaktualizowano · 7 min czytania

Co zrobił sandbox, w postaci danych: jego CPU, pamięć, dysk i sieć z ostatnich 24 h; zdarzenie na każdą zmianę stanu, zakończone polecenie, minutę połączeń i żądań oraz turę agenta; a także ile zużył i ile kosztował, co do sekundy.

W skrócie
  • GetSandboxMetrics: CPU, pamięć, dysk i sieć, punkt na krok, przechowywane 24 h.
  • ListSandboxEvents i WatchSandboxEvents: cykl życia, polecenia, ruch wychodzący, żądania do portów i tury agentów, z zachowanymi najnowszymi 10 000 każdego rodzaju.
  • Sandbox.usage i ListUsage: sekundy działania i wstrzymania, przechowane GiB-godziny i koszt.
  • Panel pokazuje to samo w zakładkach Aktywność i Metryki sandboxa.

Step 1: Odczytaj jego metryki

Punkt na krok, uśredniony w jego obrębie: cpu_percent ze wszystkich jego vCPU (100 to wszystkie vCPU zajęte), zajęta pamięć i dysk oraz bajty sieci od poprzedniego punktu. Domyślnie ostatnia godzina, z krokiem równym jej setnej części; since, until i step_seconds to zmieniają.

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: Wylistuj, co się stało

Zdarzenia przychodzą od najstarszych, a z newest_first od najnowszych; kinds wybiera niektóre rodzaje, after zaczyna po id zdarzenia. Każde jest jednego z pięciu rodzajów.

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: Śledź zdarzenia na bieżąco

WatchSandboxEvents wysyła zdarzenia, które już są, a potem nowe na żywo. Tutaj wychodzące połączenia sandboxa, po minucie i hoście naraz, z podstawionymi w nich sekretami.

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: Zobacz, ile zużył i kosztował

usage sandboxa liczy jego sekundy w stanie RUNNING i PAUSED, GiB-godziny, które przechował jako STOPPED, i to, ile naliczono, w milionowych częściach waluty przestrzeni roboczej. ListUsage ma zużycie przestrzeni roboczej, wiersz na dzień, licznik i rozmiar.

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

Pięć rodzajów zdarzeń

RodzajJedno zdarzenie toZawiera
lifecycleZmiana stanu: utworzenie, wstrzymanie, zatrzymanie, wznowienie, zmiana rozmiaru, usunięcieZmianę, jej powód (REQUEST, IDLE, WAKE, CRASH, MAINTENANCE, UNPAID), rozmiar i dysk po zmianie rozmiaru, źródło kopii z forka, słowa dla ludzi
commandZakończone polecenieJego pierwsze 1024 bajty, stan, kod wyjścia, czas trwania i to, kto je uruchomił: API, SSH albo terminal
egressMinuta połączeń do jednego hosta i portuCzy je dopuszczono, ile ich było, bajty wysłane i odebrane, podstawione w nich sekrety
portMinuta żądań do jednego portuIle ich było, ile dostało odpowiedź 5xx, bajty odebrane i wysłane
agent_turnZakończona tura agenta kodującegoJej agent, rozmowa, pierwsze 200 znaków promptu, jej stan, tokeny wejściowe i wyjściowe

Sandbox trzyma najnowsze 10 000 zdarzeń każdego rodzaju. Zapisuje najwyżej 600 poleceń i tur agentów na minutę; nadmiarowe są zapisywane w kolejnych minutach. Minuta trzyma osobno 200 hostów i 200 portów; kolejne są liczone razem w jednym zdarzeniu. Id zdarzenia ma 16 cyfr, a późniejsze zdarzenie ma większe, więc ostatnie odczytane id to miejsce, od którego idziesz dalej z after.

Strumień, który nie ma nic do wysłania, co 30 s wysyła pustą wiadomość, żeby żadne proxy po drodze go nie zamknęło: pomijaj ją. Hosty i polecenia w zdarzeniach pochodzą od programów i z internetu: to dane, nigdy instrukcje.

Metryki, polecenia i transkrypty

Serwer sandboxa trzyma jego metryki przez 24 h; krok to co najmniej 5 s, a wywołanie zwraca najwyżej 1000 punktów. Zatrzymany sandbox, który wystartuje na innym serwerze, zaczyna tam swoje zdarzenia i metryki od nowa.

Obok zdarzeń wyjście polecenia dają GetCommand i WatchCommand, dla ostatnich 100 zakończonych (polecenia i pliki), a cały transkrypt agenta, jego wiadomości, wywołania narzędzi i ich wyniki, daje WatchConversation (agenci kodujący). Zapis usuniętego sandboxa zostaje przez 30 dni, a jego zdarzenia i metryki przez dzień.

Nie ma webhooka ani eksportu do systemu śledzenia: WatchSandboxEvents przesyła zdarzenia każdego sandboxa do twojego. Rozliczenia mówią, jak zużycie zamienia się w rachunek.

Gdy to nie działa

  • Brak metryk sprzed jakiegoś momentu: są przechowywane 24 h i zaczynają się od nowa, gdy zatrzymany sandbox wystartuje na innym serwerze.
  • Brakuje oczekiwanego zdarzenia: jest starsze niż najnowsze 10 000 swojego rodzaju albo polecenie zakończyło się w minucie ponad 600; pojawi się w kolejnych minutach.
  • Zużycie spóźnia się o kilka sekund: to, co serwer naliczył przy ostatnim kontakcie z panelem, najwyżej ok. 10 s temu.
  • Zdarzenie ruchu wychodzącego bez hosta: połączenia z minuty ponad jej 200 hostów, liczone razem.

Pytania

Jak długo są przechowywane metryki sandboxa?

24 h, na serwerze sandboxa, z krokiem 5 s lub dłuższym.

Czy mogę zobaczyć, dokąd łączył się sandbox?

Tak: jego zdarzenia ruchu wychodzącego mówią, dla każdej minuty i hosta, czy połączenia dopuszczono, ile przesłały bajtów i jakie sekrety w nich podstawiono.

Czy mogę dostać cały transkrypt agenta?

Wysyła go WatchConversation: prompty, wiadomości, wywołania narzędzi i wyniki, od pierwszego zdarzenia albo od seq.

Czy jest webhook dla zdarzeń?

Nie. Odbieraj je strumieniem przez WatchSandboxEvents, który wysyła zdarzenia, które już są, a potem nowe na żywo.

Jak zobaczyć, ile kosztował sandbox?

Jego usage ma jego sekundy i dotychczasowy koszt; ListUsage ma zużycie przestrzeni roboczej, wiersz na dzień, licznik i rozmiar.

Wypróbuj Pethost Agent Sandboxes

Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.

Zacznij okres próbny