[FLO-OBS-07] Add privacy-safe diagnostics and operator runbooks

[szmyty]

Parent: #14
Depends on: FLO-OBS-01 / #15, FLO-OBS-06 / #20

Outcome

Give operators a safe, bounded way to inspect observability health and assemble local diagnostic material for support without automatically uploading data or confusing a support bundle with run evidence.

Publish practical operational guidance for local logs, OpenTelemetry collectors, retention, troubleshooting, and privacy.

Diagnostic workflow

Define and implement the applicable suite/CLI surfaces conceptually as:

• diagnostics preview: enumerate proposed categories, exclusions, redaction policy, file counts, approximate sizes, and sensitivity warnings without creating an archive.
• diagnostics bundle --output <FILE>: create a bounded local archive only after explicit invocation.
• diagnostics inspect <FILE>: validate and summarize a bundle without executing embedded content.
• doctor observability: report configured sinks/exporters, feature availability, queue/flush health, and collector reachability without disclosing credentials.

Exact commands remain product-owned and must follow each CLI's compatibility policy.

Bundle content policy

Use an allowlist. A bundle may include:

• product and build versions;
• supported contract/schema versions;
• platform/runtime characteristics needed for reproduction;
• redacted effective observability settings with provenance;
• dependency/provider availability summaries;
• bounded, redacted operational logs and exporter diagnostics;
• metric/trace summaries or sanitized local export captures where explicitly selected;
• references to durable run artifacts by safe opaque identity, without copying private artifacts;
• bundle manifest, creation tool/version, selected categories, exclusions, redaction policy, sizes, and checksums.

Exclude by default:

• source media and document bytes;
• prompts, captions, transcripts, lyrics, and extracted content;
• environment dumps;
• credentials, tokens, cookies, authorization headers, query secrets, and exporter headers;
• complete argv or arbitrary child-process captures;
• user home paths and unnecessary absolute paths;
• unbounded logs, traces, metrics, crash dumps, or backtraces;
• durable artifacts whose inclusion was not separately authorized.

The archive is a local support artifact, not provenance, validation evidence, or proof of success.

Safety and robustness

• Preview has no write, upload, or exporter side effect.
• Bundle creation never uploads or opens network connections.
• The output path uses no-clobber behavior by default.
• Archive members use normalized safe relative names; reject traversal, symlinks, duplicate names, and expansion abuse.
• Size, file-count, per-entry, time, and memory bounds are explicit.
• Malformed UTF-8 and terminal control characters are escaped safely.
• Redaction occurs before bytes enter the archive.
• Canary values are searched in the final archive as a defense-in-depth test.
• Retention and cleanup are operator-controlled and documented.
• Panic/backtrace capture, if supported, is opt-in and sanitized.

Operational runbook

Document:

• human and JSON Lines local logging;
• log location, rotation, retention, permissions, and cleanup;
• quiet/verbosity/filter behavior;
• explicit OpenTelemetry enablement and disablement;
• collector endpoints, TLS, authentication, proxy, sampling, queue, retry, and shutdown behavior;
• a minimal local collector configuration;
• collector-unavailable and exporter-backpressure troubleshooting;
• privacy and data-residency implications;
• diagnostic preview, creation, inspection, storage, and safe sharing;
• how to correlate a suite run while treating telemetry as non-authoritative;
• rollback and support procedures.

Acceptance criteria

• Preview reports exact proposed categories and exclusions without creating or transmitting data.
• Bundle creation requires an explicit destination and performs no upload.
• Bundle schemas/manifests are versioned and reject unknown incompatible versions.
• Redaction canaries are absent from every archive member.
• Source/user content, environment dumps, credentials, full argv, and unnecessary paths are excluded by default.
• Archive paths and resource bounds withstand malformed/adversarial fixtures safely.
• Bundle inspection does not execute or trust archive contents.
• Observability doctor output exposes health without credentials or silent network enablement.
• Retention, cleanup, permissions, data residency, and safe-sharing implications are documented.
• Runbooks cover disabled, local-only, OpenTelemetry, collector-failure, and shutdown paths.
• Bundles are explicitly labeled non-authoritative and never affect workload result or resume decisions.
• Applicable independently built CLIs pass the shared bundle/privacy conformance fixtures.

Explicit non-goals

• Automatic upload, email, issue attachment, or vendor support transmission.
• General-purpose data-loss prevention.
• Copying source artifacts for convenience.
• Treating bundles as signed provenance.
• Hosted collectors, dashboards, or alerting.
• Unbounded crash/core dumps.
• CLI branding.

Roadmap-Track: FLO-OBS