# jackin-diagnostics (https://jackin.tailrocks.com/reference/crates/jackin-diagnostics/)



{/* GENERATED from crates/jackin-diagnostics/README.md — edit the README, not this file */}

Host observability substrate: structured JSONL run diagnostics, the debug-mode flag, the `debug_log!` macro, redaction/secret-scrubbing, build-log capture, and the run/summary/screen/terminal reporting helpers. The two-tier telemetry (`clog!` compact always-on, `cdebug!` firehose on `JACKIN_DEBUG=1`) is rooted here.

Terminal-ownership guards are re-exported from `jackin_tui::ownership`.

## What this crate owns [#what-this-crate-owns]

* Structured run diagnostics (`run`, `summary`, `observability`) and the debug-mode substrate (`debug_log_adapter` installing the `jackin-core` `debug_log!` sink, plus `logging`).
* Secret scrubbing (`secret_scrub`, `redact`) so logs/telemetry never leak credentials.
* Build-log capture (`build_log`), operator notices (`operator_notice`), and screen/terminal reporting (`screen`, `terminal`).

## Architecture tier and allowed dependencies [#architecture-tier-and-allowed-dependencies]

**L2 infrastructure.** Allowed workspace dependencies: `jackin-core`, `jackin-tui` (terminal-ownership guard re-exports). Diagnostic code must not start calling presentation helpers beyond the guard re-exports.

## Structure [#structure]

| Module                                                                                                                                                                                              | Owns                                                  | Tests                                                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| <RepoFile path="crates/jackin-diagnostics/src/lib.rs">`lib.rs`</RepoFile>                                                                                                                           | crate root, re-exports                                | —                                                                                             |
| <RepoFile path="crates/jackin-diagnostics/src/run.rs">`run.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/run.rs">`run/`</RepoFile>                                                 | structured run diagnostics                            | <RepoFile path="crates/jackin-diagnostics/src/run/tests.rs">`tests.rs`</RepoFile>             |
| <RepoFile path="crates/jackin-diagnostics/src/summary.rs">`summary.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/summary.rs">`summary/`</RepoFile>                                 | run summary                                           | <RepoFile path="crates/jackin-diagnostics/src/summary/tests.rs">`tests.rs`</RepoFile>         |
| <RepoFile path="crates/jackin-diagnostics/src/operation.rs">`operation.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/operation.rs">`operation/`</RepoFile>                         | typed operation facade                                | <RepoFile path="crates/jackin-diagnostics/src/operation/tests.rs">`tests.rs`</RepoFile>       |
| <RepoFile path="crates/jackin-diagnostics/src/metrics.rs">`metrics.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/metrics.rs">`metrics/`</RepoFile>                                 | hot-path metric instruments                           | <RepoFile path="crates/jackin-diagnostics/src/metrics/tests.rs">`tests.rs`</RepoFile>         |
| <RepoFile path="crates/jackin-diagnostics/src/observability.rs">`observability.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/observability.rs">`observability/`</RepoFile>         | OTLP tier                                             | <RepoFile path="crates/jackin-diagnostics/src/observability/tests.rs">`tests.rs`</RepoFile>   |
| <RepoFile path="crates/jackin-diagnostics/src/debug_log_adapter.rs">`debug_log_adapter.rs`</RepoFile>                                                                                               | host sink install for `jackin-core::debug_log!`       | —                                                                                             |
| <RepoFile path="crates/jackin-diagnostics/src/logging.rs">`logging.rs`</RepoFile>                                                                                                                   | logging init                                          | —                                                                                             |
| <RepoFile path="crates/jackin-diagnostics/src/secret_scrub.rs">`secret_scrub.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/secret_scrub.rs">`secret_scrub/`</RepoFile>             | secret scrubbing                                      | <RepoFile path="crates/jackin-diagnostics/src/secret_scrub/tests.rs">`tests.rs`</RepoFile>    |
| <RepoFile path="crates/jackin-diagnostics/src/redact.rs">`redact.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/redact.rs">`redact/`</RepoFile>                                     | redaction                                             | <RepoFile path="crates/jackin-diagnostics/src/redact/tests.rs">`tests.rs`</RepoFile>          |
| <RepoFile path="crates/jackin-diagnostics/src/build_log.rs">`build_log.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/build_log.rs">`build_log/`</RepoFile>                         | build-log capture                                     | <RepoFile path="crates/jackin-diagnostics/src/build_log/tests.rs">`tests.rs`</RepoFile>       |
| <RepoFile path="crates/jackin-diagnostics/src/operator_notice.rs">`operator_notice.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/operator_notice.rs">`operator_notice/`</RepoFile> | operator notices                                      | <RepoFile path="crates/jackin-diagnostics/src/operator_notice/tests.rs">`tests.rs`</RepoFile> |
| <RepoFile path="crates/jackin-diagnostics/src/screen.rs">`screen.rs`</RepoFile> · <RepoFile path="crates/jackin-diagnostics/src/screen.rs">`screen/`</RepoFile>                                     | screen reporting                                      | <RepoFile path="crates/jackin-diagnostics/src/screen/tests.rs">`tests.rs`</RepoFile>          |
| <RepoFile path="crates/jackin-diagnostics/src/terminal.rs">`terminal.rs`</RepoFile>                                                                                                                 | terminal reporting                                    | —                                                                                             |
| <RepoFile path="crates/jackin-diagnostics/src/tests.rs">`tests.rs`</RepoFile>                                                                                                                       | crate integration and telemetry-conformance scenarios | —                                                                                             |

## Public API [#public-api]

Typed operation facade: `operation_span` / `operation_log` / `operation_error` / `operation_metric` (and `enter_operation` RAII guard). Names from the semconv registry.

`debug_log!`/`clog!`/`cdebug!`, the run-diagnostics writer, redaction helpers, and the debug-mode flag — consumed by nearly every crate. Two-tier telemetry contract is documented in <RepoFile path="ENGINEERING.md">ENGINEERING.md</RepoFile>.

## How to verify [#how-to-verify]

```sh
cargo nextest run -p jackin-diagnostics
cargo clippy -p jackin-diagnostics --all-targets -- -D warnings
cargo bench --bench summarize_jsonl -p jackin-diagnostics -- --quick
```