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.

SupportBundleSectionclassOne diagnostic section the collector attempted.
SupportBundleOptionsclassWhat hpx doctor --bundle should collect.
SupportBundleManifestclassStable envelope describing one support-bundle archive's contents.
collect_support_bundlefunctionGather every diagnostic section, redact it, and build the manifest.
write_support_bundlefunctionWrite collection as a deterministic ZIP archive and return its path.
verify_support_bundlefunctionVerify a support-bundle archive's structure, contents, and digests.

SupportBundleSection(name: str, available: bool, reason: str | None = None) -> None

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

name: str

available: bool

reason: str | None = None

from_dict(data: dict[str, Any]) -> Self

classmethod

to_dict() -> dict[str, Any]

SupportBundleOptions(
    workspace: Path | None = None,
    config_path: Path | None = None,
    toolchain: Toolchain = Toolchain.ARM_NONE_EABI_GCC,
    transport: Transport = Transport.RTT,
    engine: EngineType = EngineType.HELIA_RT,
    include_probes: bool = True,
    include_ports: bool = True,
    raw_probe_ids: bool = False,
) -> None

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

workspace: Path | None = None

config_path: Path | None = None

toolchain: Toolchain = Toolchain.ARM_NONE_EABI_GCC

transport: Transport = Transport.RTT

engine: EngineType = EngineType.HELIA_RT

include_probes: bool = True

include_ports: bool = True

raw_probe_ids: bool = False

SupportBundleManifest(
    schema: str,
    schema_version: int,
    hpx_version: str,
    generated_at: str,
    host: dict[str, Any],
    sections: tuple[SupportBundleSection, ...],
    redaction: dict[str, Any],
    artifacts: tuple[ResultArtifact, ...],
    extra: dict[str, Any] = dict(),
) -> None

dataclass

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

API tier: experimental

schema: str

schema_version: int

hpx_version: str

generated_at: str

host: dict[str, Any]

sections: tuple[SupportBundleSection, ...]

redaction: dict[str, Any]

artifacts: tuple[ResultArtifact, ...]

extra: dict[str, Any] = field(default_factory=dict, repr=False)

section(name: str) -> SupportBundleSection | None

to_dict() -> dict[str, Any]

from_dict(data: dict[str, Any]) -> Self

classmethod

load(path: str | Path) -> Self

classmethod

verify(bundle_dir: str | Path) -> None

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).

collect_support_bundle(options: SupportBundleOptions = SupportBundleOptions()) -> SupportBundleCollection

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_support_bundle(collection: SupportBundleCollection, output: Path) -> Path

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_support_bundle(path: Path) -> SupportBundleManifest

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 · diagnostics.md, complete and lossless.