An escript to inject, at runtime, instrumentation into a remote BEAM (Erlang) virtual machine using vmstats and StatsD. A VM instrumented in this way will output stats to a StatsD server, until restarted.
Erlang.
brew install erlang
Scheduler Wall clock statistics are disabled by default due to instability issues on certain Erlang versions. See the upstream docs
The most excellent getopt library provides cli help.
~$ ./vmstats_probe
Vmstats Probe :: Adding statsd to your beam since 2015
Usage: ./vmstats_probe [<node>] [-l [<lolcat>]] [-c <cookie>]
[--statsd-ip [<statsd>]] [-s [<names>]]
[-p [<port>]]
[-w [<wall>]]
<node> Remote erlang VM node name
-l, --lolz Print erlang lolcat [default: false]
-c, --cookie Provide a cookie, if needed, to connect to remote node
--statsd-ip the IP address of StatsD UDP server. See the docs for inet:parse_address/1 for more. [default: 127.0.0.1]
-s, --shortnames Use short node names [default: false]
-p, --statsd-port StatsD UDP port number [default: 8125]
-w, --enable-wall Enable Scheduler Wall-Clock Statistics - warning, may cause instability [default: false]
Examples:
Long Names:
./vmstats_probe --statsd-ip "10.199.103.168" [email protected]
Starting net_kernel, using longnames...
Started net_kernel, connecting to [email protected]...
Connected successfully! Loading modules...
Remote loading completed! Starting statistics applications...
Remote application start completed, output was:
[ok,ok,ok,ok,ok,ok,ok,ok,ok,ok]
Short Names:
./vmstats_probe --statsd-ip "127.0.0.1" -s target@`hostname -s`
Starting net_kernel, using shortnames...
Started net_kernel, connecting to target@BRADS_MACBOOK...
Connected successfully! Loading modules...
Remote loading completed! Starting statistics applications...
Remote application start completed, output was:
[ok,ok,ok,ok,ok,ok,ok,ok,ok,ok]
Error Message if unable to connect to remote node with longnames:
./vmstats_probe --statsd-ip "127.0.0.1" [email protected]
Starting net_kernel, using longnames...
Started net_kernel, connecting to [email protected]...
Node name "'[email protected]'" not reachable.
Ensure the remote node's host name is reachable from this host using DNS, and check that the remote epmd service is available from this host using telnet.
Error Message if unable to connect to remote node with shortnames:
./vmstats_probe --statsd-ip "127.0.0.1" -s target
Starting net_kernel, using shortnames...
Started net_kernel, connecting to target...
Node name "target" not reachable.
Ensure the remote node is using short names, and has "@BRADS_MACBOOK" at the end.
For the StatsD IP address, use a string parseable by the inet erlang library.
./vmstats_probe --statsd-ip "{127,0,0,1} bad arg." -s target@`hostname -s`
Unable to parse StatsD IP address config.
At this time, you don't - you must restart the remote VM. The change to add the code to the VM isn't persisted to disk, so a restart will wipe it clean. It will be possible to add remote uninstallation functionality in a later release.
rebar get-deps clean compile escriptize && ./vmstats_probe
This script was (manually) tested on:
- Erlang R15B01, platform: Darwin
- Erlang R15B03, platform: Darwin
- Erlang R16B03-1, platform: Darwin
- Erlang 17.4, platform: Darwin
I would expect mixing different runtime versions and platforms for the escript itself and the remote target of the escript will get bad results, but you never know. Of course, YMMV.
Fred Herbert -> creator of epic awesome Erlang libraries recon and vmstats
Etsy -> creator of StatsD