pounce-observability 0.11.0

Observability for POUNCE (pounce#71): tracing subscriber install, tiger/rust themed text formatter, and the per-iteration collector layer that feeds the JSON solve report from the `pounce::iteration` event.
Documentation 
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

# pounce-observability

Observability wiring for POUNCE (pounce#71): the `tracing` subscriber
install and the bridge between the structured per-iteration event and
the JSON solve report.

This crate is kept separate from the leaf `pounce-common` (which holds
the pure color palette) because the collector depends on both
`pounce_nlp::solve_statistics::IterRecord` and `tracing-subscriber`.

## Two output channels, one event

Each Newton iteration emits a single structured `tracing` event at the
`pounce::iteration` target ([`ITER_TARGET`]) carrying `iter`, `mu`,
`alpha_primal`, … The human terminal never sees this event — its visual
form is the colored fixed-width iteration table printed directly by
`pounce-algorithm`, so the text console layer filters
`pounce::iteration` out. Machines get it two ways:

- `POUNCE_LOG_FORMAT=json` → the JSON layer prints it to stderr;
- the `IterCollectorLayer` rebuilds an `IterRecord` from the event
  fields and appends it to the active `IterCaptureGuard` slot, which
  the application drains into the solve report.

The collector skips events nested inside a `restoration` span, so the
report captures only the outer solve's iterations (including
`'R'`-marked outer iters) and not the restoration sub-solve's inner IPM
iterations — matching the pre-tracing behavior exactly.

## Surface

- `init_subscriber()` — install the global subscriber for a normal
  run. Idempotent (`try_init`), so multiple frontends or repeated
  Python imports are safe. Reads `RUST_LOG` (filtering, default
  `info`), `POUNCE_LOG_FORMAT` (`text` | `json`), and
  `NO_COLOR` / `CLICOLOR_FORCE` (color policy). Also bridges the `log`
  crate into `tracing` so transitive `log::*` call sites obey
  `RUST_LOG`.
- `init_for_tests()` — same layers, for test setup.
- `IterCaptureGuard::start()` / `.finish()` — per-solve capture slot;
  `finish` returns the collected `Vec<IterRecord>`.
- `IterCollectorLayer` — the `tracing-subscriber` layer that reconstructs
  iteration records from `pounce::iteration` events.
- `iteration_event_wanted()` — whether the per-iteration event should be
  emitted at all (true when JSON logging is on or a capture is active).
- `ITER_TARGET` / `RESTORATION_SPAN` — the target and span-name constants.

## Environment variables

| Variable | Effect |
|---|---|
| `RUST_LOG` | Verbosity / per-target filtering (default `info`). |
| `POUNCE_LOG_FORMAT` | `text` (default) or `json` (structured stderr sink). |
| `NO_COLOR` / `CLICOLOR_FORCE` | Disable / force colored output. |

## License

EPL-2.0.