feat(cli): add coder stat command (#8005)

docs/cli.md

@@ -49,6 +49,7 @@ Coder — A tool for provisioning self-hosted development environments with Terr
 | [<code>speedtest</code>](./cli/speedtest.md)           | Run upload and download tests from your machine to a workspace         |
 | [<code>ssh</code>](./cli/ssh.md)                       | Start a shell into a workspace                                         |
 | [<code>start</code>](./cli/start.md)                   | Start a workspace                                                      |
+| [<code>stat</code>](./cli/stat.md)                     | Show resource usage for the current workspace.                         |
 | [<code>state</code>](./cli/state.md)                   | Manually manage Terraform state to fix broken workspaces               |
 | [<code>stop</code>](./cli/stop.md)                     | Stop a workspace                                                       |
 | [<code>templates</code>](./cli/templates.md)           | Manage templates                                                       |

docs/cli/stat.md

@@ -0,0 +1,39 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+
+# stat
+
+Show resource usage for the current workspace.
+
+## Usage
+
+```console
+coder stat [flags]
+```
+
+## Subcommands
+
+| Name                                | Purpose                          |
+| ----------------------------------- | -------------------------------- |
+| [<code>cpu</code>](./stat_cpu.md)   | Show CPU usage, in cores.        |
+| [<code>disk</code>](./stat_disk.md) | Show disk usage, in gigabytes.   |
+| [<code>mem</code>](./stat_mem.md)   | Show memory usage, in gigabytes. |
+
+## Options
+
+### -c, --column
+
+|         |                                                                            |
+| ------- | -------------------------------------------------------------------------- |
+| Type    | <code>string-array</code>                                                  |
+| Default | <code>host_cpu,host_memory,home_disk,container_cpu,container_memory</code> |
+
+Columns to display in table output. Available columns: host cpu, host memory, home disk, container cpu, container memory.
+
+### -o, --output
+
+|         |                     |
+| ------- | ------------------- |
+| Type    | <code>string</code> |
+| Default | <code>table</code>  |
+
+Output format. Available formats: table, json.

docs/cli/stat_cpu.md

@@ -0,0 +1,38 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+
+# stat cpu
+
+Show CPU usage, in cores.
+
+## Usage
+
+```console
+coder stat cpu [flags]
+```
+
+## Options
+
+### --host
+
+|      |                   |
+| ---- | ----------------- |
+| Type | <code>bool</code> |
+
+Force host CPU measurement.
+
+### -o, --output
+
+|         |                     |
+| ------- | ------------------- |
+| Type    | <code>string</code> |
+| Default | <code>text</code>   |
+
+Output format. Available formats: text, json.
+
+### --prefix
+
+|      |                     |
+| ---- | ------------------- |
+| Type | <code>string</code> |
+
+Unit prefix.

docs/cli/stat_disk.md

@@ -0,0 +1,31 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+
+# stat disk
+
+Show disk usage, in gigabytes.
+
+## Usage
+
+```console
+coder stat disk [flags]
+```
+
+## Options
+
+### -o, --output
+
+|         |                     |
+| ------- | ------------------- |
+| Type    | <code>string</code> |
+| Default | <code>text</code>   |
+
+Output format. Available formats: text, json.
+
+### --path
+
+|         |                     |
+| ------- | ------------------- |
+| Type    | <code>string</code> |
+| Default | <code>/</code>      |
+
+Path for which to check disk usage.

docs/cli/stat_mem.md

@@ -0,0 +1,30 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+
+# stat mem
+
+Show memory usage, in gigabytes.
+
+## Usage
+
+```console
+coder stat mem [flags]
+```
+
+## Options
+
+### --host
+
+|      |                   |
+| ---- | ----------------- |
+| Type | <code>bool</code> |
+
+Force host memory measurement.
+
+### -o, --output
+
+|         |                     |
+| ------- | ------------------- |
+| Type    | <code>string</code> |
+| Default | <code>text</code>   |
+
+Output format. Available formats: text, json.

docs/manifest.json

@@ -703,6 +703,26 @@
           "description": "Start a workspace",
           "path": "cli/start.md"
         },
+        {
+          "title": "stat",
+          "description": "Show resource usage for the current workspace.",
+          "path": "cli/stat.md"
+        },
+        {
+          "title": "stat cpu",
+          "description": "Show CPU usage, in cores.",
+          "path": "cli/stat_cpu.md"
+        },
+        {
+          "title": "stat disk",
+          "description": "Show disk usage, in gigabytes.",
+          "path": "cli/stat_disk.md"
+        },
+        {
+          "title": "stat mem",
+          "description": "Show memory usage, in gigabytes.",
+          "path": "cli/stat_mem.md"
+        },
         {
           "title": "state",
           "description": "Manually manage Terraform state to fix broken workspaces",

docs/templates/agent-metadata.md

@@ -16,6 +16,10 @@ See the [Terraform reference](https://registry.terraform.io/providers/coder/code
 All of these examples use [heredoc strings](https://developer.hashicorp.com/terraform/language/expressions/strings#heredoc-strings) for the script declaration. With heredoc strings, you
 can script without messy escape codes, just as if you were working in your terminal.
 
+Some of the below examples use the [`coder stat`](../cli/stat.md) command.
+This is useful for determining CPU/memory usage inside a container, which
+can be tricky otherwise.
+
 Here's a standard set of metadata snippets for Linux agents:
 
 ```hcl
@@ -25,10 +29,38 @@ resource "coder_agent" "main" {
   metadata {
     display_name = "CPU Usage"
     key  = "cpu"
+    # Uses the coder stat command to get container CPU usage.
+    script = "coder stat cpu"
+    interval = 1
+    timeout = 1
+  }
+
+  metadata {
+    display_name = "Memory Usage"
+    key  = "mem"
+    # Uses the coder stat command to get container memory usage in GiB.
+    script = "coder stat mem --prefix Gi"
+    interval = 1
+    timeout = 1
+  }
+
+  metadata {
+    display_name = "CPU Usage (Host)"
+    key  = "cpu_host"
     # calculates CPU usage by summing the "us", "sy" and "id" columns of
-    # vmstat.
+    # top.
     script = <<EOT
-        top -bn1 | awk 'FNR==3 {printf "%2.0f%%", $2+$3+$4}'
+    top -bn1 | awk 'FNR==3 {printf "%2.0f%%", $2+$3+$4}'
+    EOT
+    interval = 1
+    timeout = 1
+  }
+
+    metadata {
+    display_name = "Memory Usage (Host)"
+    key  = "mem_host"
+    script = <<EOT
+    free | awk '/^Mem/ { printf("%.0f%%", $4/$2 * 100.0) }'
     EOT
     interval = 1
     timeout = 1
@@ -42,16 +74,6 @@ resource "coder_agent" "main" {
     timeout = 1
   }
 
-  metadata {
-    display_name = "Memory Usage"
-    key  = "mem"
-    script = <<EOT
-    free | awk '/^Mem/ { printf("%.0f%%", $4/$2 * 100.0) }'
-    EOT
-    interval = 1
-    timeout = 1
-  }
-
   metadata {
     display_name = "Load Average"
     key  = "load"