103 lines
3.4 KiB
Markdown
103 lines
3.4 KiB
Markdown
# Diagnostics Internals
|
|
|
|
Diagnostics internals live in `internal/core/diagnostics`. Operator-facing run
|
|
behavior is documented in [Operations](../operations.md).
|
|
|
|
## Purpose
|
|
|
|
Diagnostics provide local inspection artifacts for a run without becoming the
|
|
durable output contract. Durable user output is produced by output modules and
|
|
written by the CLI.
|
|
|
|
Diagnostics must not expose secrets.
|
|
|
|
## Run Directory
|
|
|
|
`NewRunDirectory(workDir, retention)` creates:
|
|
|
|
```text
|
|
<workDir>/run-<unix-nanoseconds>/
|
|
```
|
|
|
|
If `workDir` is empty, it defaults to `/tmp/notarius`. Empty retention defaults
|
|
to `auto`.
|
|
|
|
The CLI passes the effective diagnostics root from workspace configuration.
|
|
When `workspace.directory` is set and diagnostics are enabled, that root is
|
|
`<workspace.directory>/diagnostics`. The legacy diagnostics work directory and
|
|
`--diagnostics-dir` still pass a diagnostics-only root to this constructor.
|
|
|
|
The writer makes the work directory if needed, then attempts to create a unique
|
|
run directory. It retries run ID creation a bounded number of times if a
|
|
collision occurs.
|
|
|
|
## Artifact Writers
|
|
|
|
Implemented artifact names:
|
|
|
|
- `invocation.json`
|
|
- `effective-config.json`
|
|
- `resolved-pipeline.json`
|
|
- `resolved-references.json`
|
|
- `checkpoint-events.json`
|
|
- `source-document.json`
|
|
- `run-manifest.json`
|
|
- `run-report.json`
|
|
- `warnings.json`
|
|
- `error.log`
|
|
|
|
JSON artifacts are encoded with indentation and a trailing newline. Writes are
|
|
atomic through a temporary file in the target directory followed by rename.
|
|
|
|
Artifact names must be single relative file names. Absolute paths, path
|
|
separators, and names resolving outside the run directory are rejected.
|
|
|
|
## Redacted Effective Config
|
|
|
|
Diagnostics writers accept payloads that implement
|
|
`RedactedDiagnosticsPayload`. `internal/core/config` uses this to redact API
|
|
keys in effective config diagnostics while preserving resolved pipeline context.
|
|
|
|
The redaction path clones config data before replacing secret values.
|
|
|
|
## Retention
|
|
|
|
Retention is decided by `ShouldRetainRunDirectory`.
|
|
|
|
- Failed runs are always retained.
|
|
- `always` retains successful runs.
|
|
- `never` removes successful runs.
|
|
- `auto` retains successful runs only when warnings exist.
|
|
- Unknown retention values are treated as retain by the retention decision, but
|
|
config validation rejects unsupported values before normal runs.
|
|
|
|
`ApplyRetention` removes only the specific run directory.
|
|
|
|
## CLI Failure Behavior
|
|
|
|
When diagnostics are enabled, the CLI creates the diagnostics run directory
|
|
after config loading and before pipeline resolution. Failures before that point
|
|
do not have diagnostics.
|
|
|
|
When workspace diagnostics are explicitly disabled, the CLI does not create a
|
|
diagnostics run directory and skips diagnostics artifact writes. Failures are
|
|
still printed to stderr.
|
|
|
|
After diagnostics creation, run failures call `WriteErrorLog` and apply
|
|
retention with `RunSucceeded: false`, so the run directory remains available.
|
|
|
|
When the pipeline returns a partial manifest on failure, the CLI writes that
|
|
manifest before logging the failure.
|
|
|
|
## Invariants
|
|
|
|
- Diagnostics paths must be narrow and run-directory scoped.
|
|
- Writes should be atomic where practical.
|
|
- Secrets must be redacted.
|
|
- Diagnostics write failures are command failures because they can hide the
|
|
information needed for recovery.
|
|
- Durable output file contracts belong to output modules and integration docs,
|
|
not to diagnostics.
|
|
- Checkpoint and debug workspace files are separate framework-owned artifacts,
|
|
not diagnostics artifacts.
|