# diagnostics

Collecting a redacted support bundle from a run directory, and reading one back.

Every name on this page is imported from `helia_profiler`.

**API tier:** `experimental`

Generated from the `src/helia_profiler` tree `fe269596788d6ab1604cf433559e96b5f48c1d13`.

[Machine-readable model](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/diagnostics.json)

`dataclass`

One diagnostic section the collector attempted.

``available=False`` records *why* a section was skipped (missing
workspace, offline, optional tool absent, ...) rather than failing the
whole bundle — see the Concepts page ``guide/concepts/field-diagnostics``.

**API tier:** `experimental`

`classmethod`

`dataclass`

What ``hpx doctor --bundle`` should collect.

Every section beyond the always-available doctor checks and
compatibility baseline is optional and independently toggleable so a
bundle can be built entirely offline with no attached hardware.

**API tier:** `experimental`

`dataclass`

Stable envelope describing one support-bundle archive's contents.

**API tier:** `experimental`

`classmethod`

`classmethod`

Verify every declared artifact path, size, and SHA-256 digest.

Rejects absolute paths and any path that escapes *bundle_dir* so a
hostile/corrupted manifest cannot be used to read or overwrite files
outside the extracted bundle (zip-slip style attacks).

Gather every diagnostic section, redact it, and build the manifest.

Never raises for a missing optional dependency, tool, or workspace —
every section catches its own typed failures and records a skip reason
instead. Only truly unexpected internal errors propagate.

**API tier:** `experimental`

Write *collection* as a deterministic ZIP archive and return its path.

*output* names the exact archive file when it ends in ``.zip``;
otherwise it is treated as a directory (created if needed) and the
filename is derived from :func:`content_fingerprint` plus the HPX
version, so identical inputs always produce the same file name and the
same member bytes for every entry except ``manifest.json`` (only its
``generated_at`` timestamp differs run to run).

Raises :class:`~helia_profiler.errors.ReportError` (not a raw
:class:`OSError`) if the destination cannot be created or written to
(permission denied, no space left, a path component that is itself a
file, ...), so CLI callers only ever need to catch ``HpxError``.

**API tier:** `experimental`

Verify a support-bundle archive's structure, contents, and digests.

Rejects absolute member paths (POSIX, and Windows drive-letter paths in
either ``C:\...`` or ``C:/...`` form), ``..``/empty path segments,
backslashes, NUL bytes, duplicate entries, and any file extension other
than ``.json``/exactly ``nsx.lock`` — defense in depth against a
malformed or hostile archive (zip-slip, disguised binary payloads) even
though this module only ever writes archives matching that shape
itself.

**API tier:** `experimental`

---

Machine-readable: [`diagnostics.json`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/diagnostics.json) · [`diagnostics.md`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/diagnostics.md), complete and lossless.