Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/api-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

Based on the resource OpenAPI document from `../platform` at `f20ded3`, plus its dashboard
auth integrations. The `query` filter on `GET /v1/sandboxes` and the `name` and `status`
filters on `GET /v1/images` come from platform `2396647`.
filters on `GET /v1/images` come from platform `2396647`. `GET /v1/sandboxes/{id}/usage`
comes from platform `d3b6c77`.
Every resource operation has a named command. `adapt api METHOD PATH`
also exposes same-origin JSON requests for less common account operations.

Expand All @@ -20,6 +21,7 @@ one from the CLI, or reuse the UUID supplied with `--idempotency-key`.
| `POST /v1/sandboxes` | `sandbox create` |
| `GET /v1/sandboxes` | `sandbox list [--query TEXT]` |
| `GET /v1/sandboxes/{id}` | `sandbox get ID` |
| `GET /v1/sandboxes/{id}/usage` | `sandbox usage ID [--hours 1\|24]` |
| `DELETE /v1/sandboxes/{id}` | `sandbox delete ID` |
| `POST /v1/sandboxes/{id}/start` | `sandbox start ID` |
| `POST /v1/sandboxes/{id}/stop` | `sandbox stop ID` |
Expand Down
17 changes: 16 additions & 1 deletion docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ For example, use `adapt org members ls` or `adapt sandbox ls --all`.
| `org` | `list`, `use`, `current`, `create`, `update`, `delete` |
| `org members` | `list`, `role`, `remove` |
| `org invitations` | `list`, `create`, `cancel`, `accept`, `reject` |
| `sandbox` | `list`, `get`, `create`, `sh`, `start`, `stop`, `delete`, `wait` |
| `sandbox` | `list`, `get`, `usage`, `create`, `sh`, `start`, `stop`, `delete`, `wait` |
| `exec` | Run a command in a sandbox |
| `execs` | `get`, `cancel`, `logs`, `attach` |
| `files` | `put`, `get` |
Expand Down Expand Up @@ -230,6 +230,21 @@ The `--env` and `--label` options merge entries with the JSON data.
The `--no-expiry` option sets `ttlSeconds` to null.
The `--run-image` option runs the image's ENTRYPOINT/CMD at startup.

### Sandbox usage

```sh
adapt sandbox usage SANDBOX_ID
adapt sandbox usage SANDBOX_ID --hours 24
```

Shows measured CPU and resident memory for the last hour (default) or 24 hours.
`CPU OBSERVED` and `MEMORY OBSERVED` show the measured time covered by their respective totals.
Each can be shorter than the requested window, and memory coverage can differ from CPU coverage.
For example, one hour of CPU data and six minutes of memory data show `1h of 1h` and `6m of 1h`, respectively.
A dash means nothing was measured, not zero usage.
A note under the table counts intervals that Platform estimated from allocated resources instead of measuring.
Use `--json` for the exact Platform totals and chart points.

### Executions in an existing sandbox

```sh
Expand Down
1 change: 1 addition & 0 deletions skills/adapt/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ adapt images list --name IMAGE_NAME --status ready --all --json
adapt sandbox sh --image ubuntu:24.04 -- uname -a
adapt sandbox sh --image-id IMAGE_ID --cpu 2 --memory 2048 -- /bin/sh -lc 'echo hello; uname -a'
adapt sandbox create --image-id IMAGE_ID --wait
adapt sandbox usage SANDBOX_ID --hours 24 --json
adapt exec SANDBOX_ID --cwd /app -- /bin/sh -lc 'npm test'
```

Expand Down
8 changes: 8 additions & 0 deletions src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,14 @@ pub enum SandboxCommand {
/// Full sandbox UUID or an unambiguous ID prefix
id: ResourceRef,
},
/// Show measured CPU and resident memory over the last hour or day
Usage {
/// Full sandbox UUID or an unambiguous ID prefix
id: ResourceRef,
/// Measurement window in hours
#[arg(long, default_value = "1", value_parser = ["1", "24"])]
hours: String,
},
Create(SandboxCreate),
/// Run a login shell or command in a temporary sandbox, then delete it
#[command(
Expand Down
174 changes: 174 additions & 0 deletions src/commands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,7 @@ pub async fn run(cli: Cli) -> Result<u8> {
},
Command::Sandbox(SandboxCommand::Sh(args)) => return shell::run(&api, args, cli.json).await,
Command::Sandbox(SandboxCommand::List(args)) => return list_sandboxes(&api, args, cli.json).await,
Command::Sandbox(SandboxCommand::Usage { id, hours }) => return sandbox_usage(&api, id, hours, cli.json).await,
Command::Sandbox(command) => sandbox(&api, command).await?,
Command::Exec(args) => return execute(&api, args, cli.json).await,
Command::Execs(command) => match command {
Expand Down Expand Up @@ -364,6 +365,94 @@ async fn sandbox(api: &Api, command: SandboxCommand) -> Result<Value> {
}
}
SandboxCommand::Sh(_) => unreachable!("Interactive shell is dispatched separately"),
SandboxCommand::Usage { .. } => unreachable!("Sandbox usage is dispatched separately"),
}
}

async fn sandbox_usage(api: &Api, id: input::ResourceRef, hours: String, json: bool) -> Result<u8> {
let path = format!("/v1/sandboxes/{id}/usage");
let usage = api
.json(
Method::GET,
&path,
None,
&[("hours".into(), hours.clone())],
None,
)
.await?;
if output::tables(json) {
write_usage(&mut io::stdout().lock(), &usage, &hours)?;
} else {
output::print(&usage, json)?;
}
Ok(0)
}

const USAGE_COLUMNS: [&str; 7] = [
"status",
"cpu observed",
"cpu",
"avg cpu",
"memory observed",
"memory",
"avg memory",
];

/// Writes one table row, then a note when the totals include migrated allocation
/// estimates, which would otherwise look the same as measurements.
fn write_usage(out: &mut impl Write, usage: &Value, hours: &str) -> io::Result<()> {
output::table(out, &USAGE_COLUMNS, &[usage_row(usage, hours)])?;
match usage["totals"]["estimatedIntervals"].as_u64() {
None | Some(0) => Ok(()),
Some(n) => {
let plural = if n == 1 { "" } else { "s" };
writeln!(
out,
"\nIncludes {n} interval{plural} estimated from allocated resources, not measured."
)
}
}
}

/// Converts exact usage totals to readable units. Values without any observed
/// time are null (shown as —), because zero coverage is not evidence of idling.
fn usage_row(usage: &Value, hours: &str) -> Value {
let totals = &usage["totals"];
let exact = |key: &str| {
totals[key]
.as_str()
.and_then(|text| text.parse::<f64>().ok())
.unwrap_or(0.0)
};
let (cpu, ram) = (exact("cpuNanoseconds"), exact("residentByteMilliseconds"));
let observed = totals["observedMs"].as_f64().unwrap_or(0.0);
let ram_observed = totals["memoryObservedMs"].as_f64().unwrap_or(0.0);
let gib = f64::from(1u32 << 30);
json!({
"status": usage["status"],
"cpu observed": format!("{} of {hours}h", duration(observed)),
"cpu": (observed > 0.0).then(|| format!("{:.2} CPU-h", cpu / 3.6e12)),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Distinguish allocation estimates from measured utilization

Must fix: Platform includes estimated intervals in totals. estimatedIntervals>0 renders identically to measurements, misrepresenting migrated allocations as utilization. Label estimated/mixed results and add a regression test.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Distinguish allocation estimates from measured utilization

Must fix: After allocation migration, estimatedIntervals>0 can enter the 24-hour window. Ignoring it presents reserved capacity as measured utilization. Label estimated/mixed totals and add a regression test.

"avg cpu": (observed > 0.0).then(|| format!("{:.2} vCPU", cpu / (observed * 1e6))),
"memory observed": format!("{} of {hours}h", duration(ram_observed)),
"memory": (ram_observed > 0.0).then(|| format!("{:.2} GiB-h", ram / (gib * 3.6e6))),
"avg memory": (ram_observed > 0.0).then(|| {
let bytes = ram / ram_observed;
if bytes < gib {
format!("{:.0} MiB", bytes / f64::from(1u32 << 20))
} else {
format!("{:.1} GiB", bytes / gib)
}
}),
})
}

fn duration(ms: f64) -> String {
let seconds = (ms / 1000.0) as u64;
match (seconds / 3600, seconds % 3600 / 60) {
(0, 0) => format!("{seconds}s"),
(0, minutes) => format!("{minutes}m"),
(hours, 0) => format!("{hours}h"),
(hours, minutes) => format!("{hours}h {minutes}m"),
}
}

Expand Down Expand Up @@ -911,3 +1000,88 @@ async fn invitations(api: &Api, command: InvitationCommand) -> Result<Value> {
InvitationCommand::Reject { id } => api.post("/v1/auth/organization/reject-invitation", &json!({"invitationId":id.to_string()})).await,
}
}

#[cfg(test)]
mod tests {
use super::*;

fn render(usage: Value, hours: &str) -> String {
let mut out = Vec::new();
write_usage(&mut out, &usage, hours).unwrap();
String::from_utf8(out).unwrap()
}

#[test]
fn usage_converts_exact_totals_to_readable_units() {
let usage = json!({"status":"complete","totals":{
"cpuNanoseconds":"27007200000000",
"residentByteMilliseconds":"43138651521024000",
"observedMs":22320000,
"memoryObservedMs":22320000
}});
assert_eq!(
render(usage, "24"),
concat!(
"STATUS CPU OBSERVED CPU AVG CPU MEMORY OBSERVED MEMORY AVG MEMORY\n",
"complete 6h 12m of 24h 7.50 CPU-h 1.21 vCPU 6h 12m of 24h 11.16 GiB-h 1.8 GiB \n",
)
);
}

#[test]
fn usage_flags_allocation_estimates_under_the_table() {
let usage = |estimated: u64| {
json!({"status":"complete","totals":{
"cpuNanoseconds":"3600000000000","residentByteMilliseconds":"0",
"observedMs":3600000,"memoryObservedMs":0,"estimatedIntervals":estimated
}})
};
let note = "\nIncludes 3 intervals estimated from allocated resources, not measured.\n";
assert!(render(usage(3), "24").ends_with(note));
assert!(
render(usage(1), "24").ends_with(
"Includes 1 interval estimated from allocated resources, not measured.\n"
)
);
assert_eq!(render(usage(0), "24").lines().count(), 2);
}

#[test]
fn usage_shows_memory_coverage_separately_from_cpu() {
let usage = json!({"status":"complete","totals":{
"cpuNanoseconds":"3600000000000",
"residentByteMilliseconds":"386547056640000",
"observedMs":3600000,
"memoryObservedMs":360000
}});
assert_eq!(
render(usage, "1"),
concat!(
"STATUS CPU OBSERVED CPU AVG CPU MEMORY OBSERVED MEMORY AVG MEMORY\n",
"complete 1h of 1h 1.00 CPU-h 1.00 vCPU 6m of 1h 0.10 GiB-h 1.0 GiB \n",
)
);
}

#[test]
fn usage_without_observations_shows_dashes_instead_of_zero() {
let empty = json!({"status":"pending","totals":{
"cpuNanoseconds":"0","residentByteMilliseconds":"0","observedMs":0,"memoryObservedMs":0
}});
assert_eq!(
render(empty, "1").lines().nth(1),
Some("pending 0s of 1h — — 0s of 1h — — ")
);
// CPU can be observed while memory sampling is still unavailable.
let no_memory = json!({"status":"incomplete","totals":{
"cpuNanoseconds":"1513600000000","residentByteMilliseconds":"0",
"observedMs":3520000,"memoryObservedMs":0
}});
assert_eq!(
render(no_memory, "1").lines().nth(1),
Some(
"incomplete 58m of 1h 0.42 CPU-h 0.43 vCPU 0s of 1h — — "
)
);
}
}
2 changes: 2 additions & 0 deletions tests/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ mod retries;
mod sandbox_list;
mod sandbox_prefixes;
mod sandbox_sh;
mod sandbox_usage;

#[test]
fn help_and_argument_validation() {
Expand All @@ -25,6 +26,7 @@ fn help_and_argument_validation() {
vec!["sandbox", "create", "--image", "alpine", "--image-id", ID],
vec!["exec", ID],
vec!["volumes", "quota", ID],
vec!["sandbox", "usage", ID, "--hours", "6"],
vec!["endpoints", "bind", ID, ID, "--port", "0"],
] {
assert_eq!(
Expand Down
49 changes: 49 additions & 0 deletions tests/sandbox_usage/mod.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
use crate::support::*;
use serde_json::json;

#[test]
fn usage_sends_the_window_and_passes_json_through() {
let usage = json!({"status":"live","totals":{
"cpuNanoseconds":"1513600000000",
"residentByteMilliseconds":"386547056640000",
"observedMs":3600000,
"memoryObservedMs":360000
},"points":[]});
let server = Server::start(vec![
step(
"GET",
format!("/v1/sandboxes/{ID}/usage?hours=1"),
None,
usage.clone(),
),
step(
"GET",
format!("/v1/sandboxes/{ID}/usage?hours=24"),
None,
usage.clone(),
),
]);
let dir = tempfile::tempdir().unwrap();
for args in [
vec!["sandbox", "usage", ID],
vec!["sandbox", "usage", ID, "--hours", "24", "--json"],
] {
assert_eq!(success(&run(dir.path(), &server.url, &args)), usage);
}
server.finish();
}

#[test]
fn usage_of_an_unknown_sandbox_reports_the_api_error() {
let server = Server::start(vec![Box::new(|_| {
Reply::json(
404,
json!({"error":{"code":"NOT_FOUND","message":"Sandbox not found."}}),
)
})]);
let dir = tempfile::tempdir().unwrap();
let output = run(dir.path(), &server.url, &["sandbox", "usage", ID]);
assert!(!output.status.success());
assert!(String::from_utf8_lossy(&output.stderr).contains("404 NOT_FOUND: Sandbox not found."));
server.finish();
}
Loading