|
| 1 | +# Agent metadata |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +You can show live operational metrics to workspace users with agent metadata. It |
| 6 | +is the dynamic complement of [resource metadata](./resource-metadata.md). |
| 7 | + |
| 8 | +You specify agent metadata in the |
| 9 | +[`coder_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent). |
| 10 | + |
| 11 | +## Examples |
| 12 | + |
| 13 | +All of these examples use |
| 14 | +[heredoc strings](https://developer.hashicorp.com/terraform/language/expressions/strings#heredoc-strings) |
| 15 | +for the script declaration. With heredoc strings, you can script without messy |
| 16 | +escape codes, just as if you were working in your terminal. |
| 17 | + |
| 18 | +Some of the examples use the [`coder stat`](../../../reference/cli/stat.md) command. This is |
| 19 | +useful for determining CPU and memory usage of the VM or container that the |
| 20 | +workspace is running in, which is more accurate than resource usage about the |
| 21 | +workspace's host. |
| 22 | + |
| 23 | +Here's a standard set of metadata snippets for Linux agents: |
| 24 | + |
| 25 | +```hcl |
| 26 | +resource "coder_agent" "main" { |
| 27 | + os = "linux" |
| 28 | + ... |
| 29 | + metadata { |
| 30 | + display_name = "CPU Usage" |
| 31 | + key = "cpu" |
| 32 | + # Uses the coder stat command to get container CPU usage. |
| 33 | + script = "coder stat cpu" |
| 34 | + interval = 1 |
| 35 | + timeout = 1 |
| 36 | + } |
| 37 | +
|
| 38 | + metadata { |
| 39 | + display_name = "Memory Usage" |
| 40 | + key = "mem" |
| 41 | + # Uses the coder stat command to get container memory usage in GiB. |
| 42 | + script = "coder stat mem --prefix Gi" |
| 43 | + interval = 1 |
| 44 | + timeout = 1 |
| 45 | + } |
| 46 | +
|
| 47 | + metadata { |
| 48 | + display_name = "CPU Usage (Host)" |
| 49 | + key = "cpu_host" |
| 50 | + # calculates CPU usage by summing the "us", "sy" and "id" columns of |
| 51 | + # top. |
| 52 | + script = <<EOT |
| 53 | + top -bn1 | awk 'FNR==3 {printf "%2.0f%%", $2+$3+$4}' |
| 54 | + EOT |
| 55 | + interval = 1 |
| 56 | + timeout = 1 |
| 57 | + } |
| 58 | +
|
| 59 | + metadata { |
| 60 | + display_name = "Memory Usage (Host)" |
| 61 | + key = "mem_host" |
| 62 | + script = <<EOT |
| 63 | + free | awk '/^Mem/ { printf("%.0f%%", $4/$2 * 100.0) }' |
| 64 | + EOT |
| 65 | + interval = 1 |
| 66 | + timeout = 1 |
| 67 | + } |
| 68 | +
|
| 69 | + metadata { |
| 70 | + display_name = "Disk Usage" |
| 71 | + key = "disk" |
| 72 | + script = "df -h | awk '$6 ~ /^\\/$/ { print $5 }'" |
| 73 | + interval = 1 |
| 74 | + timeout = 1 |
| 75 | + } |
| 76 | +
|
| 77 | + metadata { |
| 78 | + display_name = "Load Average" |
| 79 | + key = "load" |
| 80 | + script = <<EOT |
| 81 | + awk '{print $1,$2,$3}' /proc/loadavg |
| 82 | + EOT |
| 83 | + interval = 1 |
| 84 | + timeout = 1 |
| 85 | + } |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +## Useful utilities |
| 90 | + |
| 91 | +You can also show agent metadata for information about the workspace's host. |
| 92 | + |
| 93 | +[top](https://manpages.ubuntu.com/manpages/jammy/en/man1/top.1.html) is |
| 94 | +available in most Linux distributions and provides virtual memory, CPU and IO |
| 95 | +statistics. Running `top` produces output that looks like: |
| 96 | + |
| 97 | +```text |
| 98 | +%Cpu(s): 65.8 us, 4.4 sy, 0.0 ni, 29.3 id, 0.3 wa, 0.0 hi, 0.2 si, 0.0 st |
| 99 | +MiB Mem : 16009.0 total, 493.7 free, 4624.8 used, 10890.5 buff/cache |
| 100 | +MiB Swap: 0.0 total, 0.0 free, 0.0 used. 11021.3 avail Mem |
| 101 | +``` |
| 102 | + |
| 103 | +[vmstat](https://manpages.ubuntu.com/manpages/jammy/en/man8/vmstat.8.html) is |
| 104 | +available in most Linux distributions and provides virtual memory, CPU and IO |
| 105 | +statistics. Running `vmstat` produces output that looks like: |
| 106 | + |
| 107 | +```text |
| 108 | +procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu----- |
| 109 | +r b swpd free buff cache si so bi bo in cs us sy id wa st |
| 110 | +0 0 19580 4781680 12133692 217646944 0 2 4 32 1 0 1 1 98 0 0 |
| 111 | +``` |
| 112 | + |
| 113 | +[dstat](https://manpages.ubuntu.com/manpages/jammy/man1/dstat.1.html) is |
| 114 | +considerably more parseable than `vmstat` but often not included in base images. |
| 115 | +It is easily installed by most package managers under the name `dstat`. The |
| 116 | +output of running `dstat 1 1` looks like: |
| 117 | + |
| 118 | +```text |
| 119 | +--total-cpu-usage-- -dsk/total- -net/total- ---paging-- ---system-- |
| 120 | +usr sys idl wai stl| read writ| recv send| in out | int csw |
| 121 | +1 1 98 0 0|3422k 25M| 0 0 | 153k 904k| 123k 174k |
| 122 | +``` |
| 123 | + |
| 124 | +## Managing the database load |
| 125 | + |
| 126 | +Agent metadata can generate a significant write load and overwhelm your Coder |
| 127 | +database if you're not careful. The approximate writes per second can be |
| 128 | +calculated using the formula: |
| 129 | + |
| 130 | +```text |
| 131 | +(metadata_count * num_running_agents * 2) / metadata_avg_interval |
| 132 | +``` |
| 133 | + |
| 134 | +For example, let's say you have |
| 135 | + |
| 136 | +- 10 running agents |
| 137 | +- each with 6 metadata snippets |
| 138 | +- with an average interval of 4 seconds |
| 139 | + |
| 140 | +You can expect `(10 * 6 * 2) / 4`, or 30 writes per second. |
| 141 | + |
| 142 | +One of the writes is to the `UNLOGGED` `workspace_agent_metadata` table and the |
| 143 | +other to the `NOTIFY` query that enables live stats streaming in the UI. |
| 144 | + |
| 145 | +## Next Steps |
| 146 | + |
| 147 | +- [Resource metadata](./resource-metadata.md) |
| 148 | +- [Parameters](./parameters.md) |
0 commit comments