Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Observability: Metriken, Events und Verbrauch einer Sandbox

Aktualisiert · 8 Min. Lesezeit

Was eine Sandbox getan hat, als Daten: ihre CPU, ihr RAM, ihre Disk und ihr Netzwerk über die letzten 24 Stunden; ein Event für jeden Zustandswechsel, jeden beendeten Befehl, jede Minute mit Verbindungen und Requests und jeden Turn eines Agenten; und was sie verbraucht und gekostet hat, sekundengenau.

Kurz gesagt
  • GetSandboxMetrics: CPU, RAM, Disk und Netzwerk, ein Punkt pro Schritt, 24 Stunden aufbewahrt.
  • ListSandboxEvents und WatchSandboxEvents: Lebenszyklus, Befehle, Egress, Port-Requests und Turns von Agenten, die neuesten 10.000 jeder Art aufbewahrt.
  • Sandbox.usage und ListUsage: Sekunden laufend und pausiert, gespeicherte GiB-Stunden und die Kosten.
  • Die Konsole zeigt dasselbe in den Tabs „Aktivität“ und „Metriken“ einer Sandbox.

Step 1: Metriken lesen

Ein Punkt pro Schritt, darüber gemittelt: cpu_percent aller ihrer vCPUs (100 heißt, jede vCPU ist ausgelastet), belegter RAM und belegte Disk und die Bytes des Netzwerks seit dem vorigen Punkt. Standardmäßig die letzte Stunde, in Schritten von einem Hundertstel davon; since, until und step_seconds ändern das.

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: Auflisten, was passiert ist

Events kommen das älteste zuerst, oder mit newest_first das neueste zuerst; kinds wählt einige aus, after beginnt nach der ID eines Events. Jedes hält eine von fünf Arten.

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: Events folgen, wie sie kommen

WatchSandboxEvents schickt die vorhandenen Events, dann die neuen live. Hier die Verbindungen der Sandbox nach außen, eine Minute und ein Host auf einmal, mit den Secrets, die in sie eingesetzt wurden.

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: Sehen, was sie verbraucht und gekostet hat

Der usage einer Sandbox zählt ihre Sekunden RUNNING und PAUSED, die GiB-Stunden, die sie STOPPED gespeichert hat, und was ihr berechnet wurde, in Millionsteln der Währung des Workspace. ListUsage hat den des Workspace, eine Zeile pro Tag, Zähler und Größe.

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

Die fünf Arten von Events

ArtEin Event istEs hält
lifecycleEin Zustandswechsel: erstellt, pausiert, gestoppt, fortgesetzt, Größe geändert, gelöschtDen Wechsel, seinen Grund (REQUEST, IDLE, WAKE, CRASH, MAINTENANCE, UNPAID), Größe und Disk nach einer Größenänderung, die Quelle der Kopie eines Forks, Worte für Menschen
commandEin Befehl, der geendet hatSeine ersten 1.024 Bytes, Zustand, Exit-Code, Dauer und wer ihn gestartet hat: die API, SSH oder ein Terminal
egressEine Minute mit Verbindungen zu einem Host und PortOb sie erlaubt waren, wie viele, Bytes hinaus und herein, die Secrets, die in sie eingesetzt wurden
portEine Minute mit Requests an einen PortWie viele, wie viele mit 5xx beantwortet wurden, Bytes herein und hinaus
agent_turnEin Turn eines Coding-Agenten, der geendet hatSeinen Agenten, seine Unterhaltung, die ersten 200 Zeichen des Prompts, seinen Zustand, Tokens herein und hinaus

Eine Sandbox behält die neuesten 10.000 Events jeder Art. Sie zeichnet höchstens 600 Befehle und Turns pro Minute auf; die darüber hinaus werden in den folgenden Minuten aufgezeichnet. Eine Minute hält 200 Hosts und 200 Ports getrennt; alle weiteren werden in einem Event zusammen gezählt. Die ID eines Events hat 16 Ziffern, und die eines späteren ist größer, also ist die zuletzt gelesene ID der Punkt, an dem du mit after weitermachst.

Ein Stream, der nichts zu schicken hat, schickt alle 30 s eine leere Nachricht, damit kein Proxy unterwegs ihn beendet: Überspring sie. Hosts und Befehle in Events kommen von Programmen und aus dem Internet: Daten, nie Anweisungen.

Metriken, Befehle und Transkripte

Der Server einer Sandbox bewahrt ihre Metriken 24 Stunden auf; ein Schritt ist mindestens 5 s, und ein Aufruf antwortet mit höchstens 1.000 Punkten. Eine gestoppte Sandbox, die auf einem anderen Server startet, beginnt ihre Events und Metriken dort neu.

Neben den Events gehört die Ausgabe eines Befehls zu GetCommand und WatchCommand, für die letzten 100, die geendet haben (Befehle und Dateien), und das ganze Transkript eines Agenten, seine Nachrichten, Tool-Aufrufe und ihre Ergebnisse, zu WatchConversation (Coding-Agenten). Der Eintrag einer gelöschten Sandbox bleibt 30 Tage, ihre Events und Metriken einen Tag.

Es gibt keinen Webhook und keinen Export in ein Tracing-System: WatchSandboxEvents streamt die Events jeder Sandbox in deins. Abrechnung sagt, wie aus Verbrauch eine Rechnung wird.

Wenn es nicht funktioniert

  • Keine Metriken vor einem Zeitpunkt: Sie werden 24 Stunden aufbewahrt und beginnen neu, nachdem eine gestoppte Sandbox auf einem anderen Server gestartet ist.
  • Ein erwartetes Event fehlt: Es ist älter als die neuesten 10.000 seiner Art, oder ein Befehl endete in einer Minute nach den ersten 600; es kommt in den folgenden Minuten.
  • Der Verbrauch hinkt ein paar Sekunden hinterher: Er ist, was der Server bei seiner letzten Meldung an das Panel gezählt hat, höchstens etwa 10 Sekunden her.
  • Ein Egress-Event ohne Host: die Verbindungen einer Minute über ihre 200 Hosts hinaus, zusammen gezählt.

Fragen

Wie lange werden die Metriken einer Sandbox aufbewahrt?

24 Stunden, auf dem Server der Sandbox, in Schritten von 5 s oder mehr.

Kann ich sehen, wohin sich eine Sandbox verbunden hat?

Ja: Die Egress-Events sagen für jede Minute und jeden Host, ob die Verbindungen erlaubt waren, ihre Bytes und die eingesetzten Secrets.

Bekomme ich das ganze Transkript eines Agenten?

WatchConversation schickt es, Prompts, Nachrichten, Tool-Aufrufe und Ergebnisse, ab dem ersten Event oder ab einer seq.

Gibt es einen Webhook für Events?

Nein. Streame sie mit WatchSandboxEvents, das die vorhandenen Events schickt, dann die neuen live.

Wie sehe ich, was eine Sandbox gekostet hat?

Der usage einer Sandbox hat ihre Sekunden und ihre bisherigen Kosten; ListUsage hat den des Workspace, eine Zeile pro Tag, Zähler und Größe.

Pethost Agent Sandboxes ausprobieren

Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.

Testphase starten