delouse
| Crates.io | delouse |
| lib.rs | delouse |
| version | |
| source | src |
| created_at | 2024-02-02 20:12:13.88391+00 |
| updated_at | 2025-02-24 17:20:02.594606+00 |
| description | delouse will expose opinionated debugging stubs most useful for tokio based async programs |
| homepage | |
| repository | https://github.com/kittycad/delouse |
| max_upload_size | |
| id | 1124691 |
| Cargo.toml error: | TOML parse error at line 18, column 1 | 18 | autolib = false | ^^^^^^^ unknown field `autolib`, expected one of `name`, `version`, `edition`, `authors`, `description`, `readme`, `license`, `repository`, `homepage`, `documentation`, `build`, `resolver`, `links`, `default-run`, `default_dash_run`, `rust-version`, `rust_dash_version`, `rust_version`, `license-file`, `license_dash_file`, `license_file`, `licenseFile`, `license_capital_file`, `forced-target`, `forced_dash_target`, `autobins`, `autotests`, `autoexamples`, `autobenches`, `publish`, `metadata`, `keywords`, `categories`, `exclude`, `include` |
| size | 0 |
crate-owners (github:kittycad:crate-owners)
documentation
README
Using delouse
First, edit your Cargo.toml to add the delouse crate as an optional
dependency, and add a new feature ("debug").
[dependencies]
...
delouse = { version = "0", optional = true }
...
[features]
...
debug = ["dep:delouse"]
...
Next, during the startup in your main or similar, put in:
...
async fn main() -> Result<()> {
#[cfg(feature = "debug")]
{
delouse::init().unwrap();
}
...
}
...
Running your program
When building with cargo build or running with cargo run, add an additional
--features debug flag to enable delouse.
Using delouse
By default, and due to no toggles existing yet, delouse will bind to
127.0.0.1:7132. The interface is OpenAPI/JSON based, so you can shave
that yak how you'd like, but I tend to just use cURL. Here's some commands
for bad days:
| What | Command | Platform Restrictions | Notes |
|---|---|---|---|
| Rust Stacktrace | curl http://localhost:7132/stacktrace/rust | jq -r .stacktrace |
||
| ELF Information | curl http://localhost:7132/elf/info | jq . |
Linux 🐧 | |
| Request a coredump | curl http://localhost:7132/coredump |
Linux 🐧 | Process will exit |
| Tokio Stacktrace | curl http://localhost:7132/stacktrace/tokio | jq -r .stacktrace |
Linux 🐧, tokio_unstable |
This endpoint is very flaky. If this locks up tokio's runtime, this will panic the process with the stacktrace. |
tokio specific notes
A lot of the surface we need is unstable. The following table is a list
of endpoints and required cfg directives.
| Endpoint | cfgs |
|---|---|
stacktrace/tokio |
tokio_unstable, tokio_taskdump |
In the author's very humble opinion, the following .cargo/config.toml
settings are encouraged, in the absense of overriding convictions or
specific engineering restrictions when running with tokio:
[build]
rustflags = ["--cfg", "tokio_unstable"]
[target.x86_64-unknown-linux-gnu]
rustflags = ["--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]
If this is not possible, delouse will gracefully degrade and not
serve any endpoints which can not be run.