Diagnostic Logs and Support Procedures

Diagnostic Logs and Support Procedures

When a failure occurs, structured telemetry is the fastest path to a Root Cause Analysis (RCA). StateWarden records detailed audit events at the Control Plane level and leveled diagnostic logs on every Agent.

When contacting StateWarden Support, or when performing your own internal diagnostics, relying on vague descriptions ("the backup failed") is insufficient. Use the built-in diagnostic tools described below.


1. Realm Activity and Audit Evidence (Control Plane)

The primary source of truth for the entire infrastructure is the realm's audit trail. It does not contain low-level debug output; it records actions and state changes.

  • Events & Logs (/events): Shows realm activity - login events, RBAC modifications, Backup Policy changes and executions, BMR Token generation, quota rejections, and Vigil triage decisions. Entries can be filtered by source (Dashboard, Artemis, Driad, Agent) and by severity.
  • Audit Pack (/audit-pack): Generates audit-evidence reports for the realm (e.g., for compliance audits), assembled from the recorded activity.
  • Usage: If an Administrator asks, "Why didn't the database backup run last night?", the Events & Logs page will immediately reveal if the task was rejected for exceeding the daily quota, or if a user manually executed a backup deletion.

2. Device-Level Logs (The Agent)

If the Control Plane dispatched the task successfully but the operation failed locally (e.g., a locked disk, a network timeout, a VSS fault), you must consult the Agent's internal logs.

The StateWarden Agent consists of two processes: sw-launcher (the supervisor, which manages updates and restarts the worker on crashes) and sw-agent (the worker performing backup and security tasks). Both write leveled logs.

Viewing Logs via the Dashboard

For standard errors, you do not need to SSH or RDP into the affected machine.

  1. Navigate to the Devices view.
  2. Select the affected Device to open its detailed panel.
  3. Click the Logs tab. The Agent securely streams its recent local output back to the Artemis Control Plane for easy viewing.

Accessing Raw Logs Locally

For severe failures (e.g., the Agent is completely offline and cannot stream to the Dashboard), access the raw text files on the host machine.

  • Windows: C:\ProgramData\StateWarden\logs\ (launcher.log, agent.log)
  • Linux: /var/log/statewarden/ (launcher.log, agent.log), or the systemd journal: journalctl -u statewarden --no-pager

3. Contacting Support (Ticket System)

StateWarden includes an integrated Support Ticket system for tracking issues through resolution.

  • Opening a ticket: In the Dashboard navbar, open HELP → My Tickets (/support), then click New Ticket. Provide:
    • Subject - a one-line summary.
    • Category - General, Bug Report, Feature Request, Billing, or Security.
    • Priority - Low, Normal, High, or Critical.
    • Message - a detailed description of the issue, including relevant event types or log excerpts.
  • Follow-up: Replies from the support team appear in the ticket thread; you can respond and track status changes in the same view.
  • Internal handling: Support staff work in a dedicated admin queue (/admin/support), where they can change ticket status and attach internal notes.

Attach a diagnostic bundle (Section 4) to bug reports whenever possible - it significantly shortens time to resolution.

4. Generating a Secure Support Bundle

If you escalate an issue to StateWarden Engineering, they will require technical context.

To prevent the accidental transmission of sensitive data (like Master Keys or proprietary configuration files) via insecure channels, the StateWarden CLI provides a bundling command.

  1. Open a terminal on the affected machine.
  2. Execute: sw diag bundle
  3. The Agent will collect recent log files, network configuration state, VSS writer statuses (Windows), and basic hardware telemetry.
  4. The bundle is sanitized: no cryptographic material or PII is included.
  5. It produces a compressed .zip or .tar.gz archive ready for attachment to your support ticket.

StateWarden: Resilience Engineered.

Was this article helpful?