Project: Firecracker (Runtime / Container Runtime)
File: metrics.md

For the metrics capability, Firecracker uses a single Metrics system. This system can be configured either by: a) sending a `PUT` API Request to the `/metrics` path: or b) using the `--metrics-path` CLI option. Note the metrics configuration is not part of the guest configuration and is not restored from a snapshot. In order to configure the Metrics, first you have to create the resource that will be used for storing the metrics: ```bash mkfifo metrics.fifo touch metrics.file ``` When launching Firecracker, use the CLI option to set the metrics file. ```bash ./firecracker --metrics-path metrics.fifo ``` You can configure the Metrics system by sending the following API command: ```bash curl --unix-socket /tmp/firecracker.socket -i \ -X PUT "http://localhost/metrics" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d "{ \"metrics_path\": \"metrics.fifo\" }" ``` Details about this configuration can be found in the . The metrics are written to the `metrics_path` in JSON format. The metrics get flushed in two ways: without user intervention every 60 seconds; upon user demand, by issuing a `FlushMetrics` request. You can find how to use this request in the . If the path provided is a named pipe, you can use the script below to read from it: ```shell metrics=metrics.fifo while true do if read line <$metrics; then echo $line fi done echo "Reader exiting" ``` Otherwise, if the path points to a normal file, you can simply do: ```shell script cat metrics.file ``` The metrics emitted by Firecracker are in JSON

Below are the keys present in each metrics json object emitted by Firecracker: ``` "api_server" "balloon" "block" "deprecated_api" "entropy" "getapirequests" "i8042" "latencies_us" "logger" "mmds" "net" "patchapirequests" "putapirequests" "rtc" "seccomp" "signals" "uart" "vcpu" "vhostuserblock" "vmm" "vsock" ``` Below table explains where Firecracker metrics are defined : | Metrics key | Device | Additional comments | | -- | -- | - | | balloon | | Represent metrics for the Balloon device. | | block | | Represent aggregate metrics for Virtio Block device. | | block\{blockdriveid} | | Represent Virtio Block device metrics for the endpoint `"/drives/{driveid}"` e.g. `"block_rootfs":` represent metrics for the endpoint `"/drives/rootfs"` | | i8042 | | Represent Metrics specific to the i8042 device. | | net | | Represent aggregate metrics for Virtio Net device. | | net\{ifaceid} | | Represent Virtio Net device metrics for the endpoint `"/network-interfaces/{ifaceid}"` e.g. `neteth0` represent metrics for the endpoint `"/network-interfaces/eth0"` | | rtc | | Represent Metrics specific to the RTC device. `Note`: this is emitted only on `aarch64`. | | uart | | Represent Metrics specific to the serial device. | | vhostuser\{dev}\{devid} | | Represent Vhost-user device metrics for the device `dev` and device id `devid`. e.g. `"vhostuserblockrootfs":` represent metrics for vhost-user block device having the endpoint `"/drives/rootfs"` | | vsock | | Represent Metrics specific to the vsock device. | | entropy | | Represent Metrics specific to the entropy device. | | "apiserver"<br>"deprecatedapi"<br>"getapirequests"<br>"latenciesus"<br>"logger"<br>"mmds"<br>"patchapirequests"<br>"putapi_requests"<br>"seccomp"<br>"signals"<br>"vcpu"<br>"vmm" | | Rest of the metrics are defined in the same file metrics.rs. | Note: Firecracker emits all the above metrics regardless of the presense of that component i.e. even if `vsock` device is not attached to the Microvm, Firecracker will still emit the Vsock metrics with key as `vsock` and value of all metrics defined in `VsockDeviceMetrics` as `0`. Units for Firecracker metrics are embedded in their name.<br/> Below pseudo code should be to extract units from Firecracker metrics name:<br/> Note: An example of fullkey for below logic is `"vcpu.exitioinagg.min_us"` ``` if substring "bytes" or "bytescount" is present in any subkey of fullkey Unit is "Bytes" else substring "ms" is present in any subkey of fullkey Unit is "Milliseconds" else substring "us" is present in any subkey of fullkey Unit is "Microseconds" else Unit is "Count" ```