diff --git a/docs/tracing.md b/docs/tracing.md new file mode 100644 index 000000000000..51627d1a665d --- /dev/null +++ b/docs/tracing.md @@ -0,0 +1,32 @@ +# Tracing + +Instrumentation based tracing is implemented with [`log`](https://github.com/rust-lang/log) and [`log_instrument`](https://github.com/JonathanWoollett-Light/log-instrument), outputing a `Trace` level log entering and exiting every function. + +It is disabled by default at compile-time to remove any impact it would have on the release builds. + +To enable it you need to remove `"max_level_debug"` from the features for `log` under [`../src/vmm/Cargo.toml`](../src/vmm/Cargo.toml): + +```diff +- log = { version = "0.4.17", features = ["std", "serde", "max_level_debug"] } ++ log = { version = "0.4.17", features = ["std", "serde"] } +``` + +This will result in a signficant increase in the binary size and a signficant regression in performance. + +You can filter by module and file this can be done like: + +```bash +curl -X PUT --unix-socket "${API_SOCKET}" \ + --data "{ + \"log_path\": \"${LOGFILE}\", + # Instrumentation logs are `Trace` level, at runtime the level must be set to `Trace` to see them. + \"level\": \"Trace\", + \"show_level\": true, + \"show_log_origin\": true, + # Only outputs logs from `src/firecracker/src/api_server_adapter.rs`. + \"file\": \"src/firecracker/src/api_server_adapter.rs\", + }" \ + "http://localhost/logger" +``` + +This can mitigate most of the performance regression. \ No newline at end of file