delouse 0.1.9

delouse will expose opinionated debugging stubs most useful for tokio based async programs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# Using `delouse`

First, edit your `Cargo.toml` to add the `delouse` crate as an optional
dependency, and add a new feature ("`debug`").

```toml
[dependencies]
...
delouse = { version = "0", optional = true }
...

[features]
...
debug = ["dep:delouse"]
...
```

Next, during the startup in your `main` or similar, put in:

```rust
...

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    | <code>curl http://localhost:7132/stacktrace/rust &#124; jq -r .stacktrace</code>  | | |
| ELF Information    | <code>curl http://localhost:7132/elf/info &#124; jq .</code>                      | Linux 🐧 | |
| Request a coredump | <code>curl http://localhost:7132/coredump</code>                                  | Linux 🐧 | Process will exit |
| Tokio Stacktrace   | <code>curl http://localhost:7132/stacktrace/tokio &#124; jq -r .stacktrace</code> | 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`:

```toml
[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.