> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring Backup Jobs

> Track running backup and restore tasks, view job history, read verification reports, and inspect bandwidth usage in Ironcore Backup Solution.

## Overview

Every backup, restore, sync, and verification action in Ironcore Backup Solution
runs as a tracked task with a unique identifier (UPID). Tasks expose live progress,
structured logs, exit status, and final transferred bytes. As a project member you
monitor tasks for your project; administrators see tasks across the whole platform.

This page covers the Task Browser, common monitoring queries, and how to interpret
the dashboards.

<Note>
  **Prerequisites**

  * An active Polystack account with project membership
  * At least one backup, restore, or verification job has executed
</Note>

***

## Dashboard Overview

The **Backup Solution > Dashboard** page is the primary monitoring view.

<CardGroup cols={2}>
  <Card title="Datastore Usage" icon="database" color="#bf9667">
    Used bytes, deduplication ratio, free space, and projected fill date based
    on recent growth.
  </Card>

  <Card title="Running Tasks" icon="activity" color="#bf9667">
    All active backup, restore, sync, and verify operations with progress
    indicators that auto-refresh every 5 seconds.
  </Card>

  <Card title="Job Calendar" icon="calendar" color="#bf9667">
    Upcoming and past scheduled jobs visualised in a calendar. Click any cell to
    open the matching task log.
  </Card>

  <Card title="Recent Failures" icon="alert-triangle" color="#bf9667">
    The five most recent failures across all task types, with one-click access
    to logs and remediation tips.
  </Card>
</CardGroup>

***

## Task Browser

The **Tasks** page lists every operation with filterable columns.

| Column              | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| **Time**            | Start timestamp                                              |
| **End**             | Completion timestamp or *running*                            |
| **User**            | User or API token that triggered the task                    |
| **Type**            | `backup`, `restore`, `sync`, `verify`, `gc`, `prune`, `tape` |
| **Source / Target** | Workload, datastore, or remote site                          |
| **Status**          | `OK`, `FAILED`, `WARNING`, `running`                         |
| **Bytes**           | Bytes transferred or processed                               |
| **UPID**            | Unique task ID for log retrieval                             |

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open Tasks" icon="external-link">
        Navigate to **Backup Solution** > **Tasks**.
      </Step>

      <Step title="Filter the view" icon="filter">
        Filter by **Type**, **Status**, **Time range**, or **User**. Combine
        filters to drill down — for example, show all failed sync tasks in the
        last 24 hours.
      </Step>

      <Step title="Open a task" icon="search">
        Click the task row to open the detail panel. The panel shows
        per-stage progress, transferred bytes, errors, and the streaming log.
      </Step>

      <Step title="Download log" icon="download">
        Click **Download Log** to save the full task log as a text file for
        offline review or attaching to support tickets.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="List recent tasks" theme={null}
    ironcore-backup task list --since "1h ago"
    ```

    ```bash title="Filter by type and status" theme={null}
    ironcore-backup task list --type backup --status FAILED --since "24h ago"
    ```

    ```bash title="Follow a task in real time" theme={null}
    ironcore-backup task log --upid <upid> --follow
    ```

    ```bash title="Download a completed task log" theme={null}
    ironcore-backup task log --upid <upid> > task.log
    ```
  </Tab>
</Tabs>

***

## Task States

```mermaid theme={null}
stateDiagram-v2
    [*] --> queued
    queued --> running: Worker picks up task
    running --> ok: Task completes
    running --> warning: Completed with non-fatal issues
    running --> failed: Task errored
    queued --> cancelled: Operator cancels
    running --> cancelled: Operator cancels
```

| State       | Meaning                                                                   |
| ----------- | ------------------------------------------------------------------------- |
| `queued`    | Waiting for a worker slot                                                 |
| `running`   | Actively executing                                                        |
| `ok`        | Completed without errors                                                  |
| `warning`   | Completed but with non-fatal issues (for example, a skipped exclude path) |
| `failed`    | Errored out                                                               |
| `cancelled` | Stopped by operator before completion                                     |

***

## Verification Reports

Verification jobs produce structured reports per snapshot.

| Result      | Meaning                                                                                   |
| ----------- | ----------------------------------------------------------------------------------------- |
| **OK**      | Every chunk matched its SHA-256 fingerprint                                               |
| **CORRUPT** | At least one chunk failed the SHA-256 check — manifest references unreadable data         |
| **MISSING** | A referenced chunk is absent from the datastore                                           |
| **STALE**   | The snapshot is past the configured `keep-verified` window and is due for re-verification |

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    Open a snapshot in **Snapshots**. The **Verification** tab shows the last
    result, the verifier (which job), and the duration. Click **Verify now** to
    trigger a one-shot pass.
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Show verification status" theme={null}
    ironcore-backup snapshot show ibs-primary:vm/12345/2026-05-21T00:00:00Z --verify
    ```

    ```bash title="Trigger one-shot verification" theme={null}
    ironcore-backup verify start ibs-primary:vm/12345/2026-05-21T00:00:00Z
    ```
  </Tab>
</Tabs>

<Warning>
  Any **CORRUPT** or **MISSING** result requires immediate attention. Do not
  rely on a snapshot with a non-OK verification result for recovery — restore
  from a verified earlier snapshot instead and trigger a fresh full backup.
</Warning>

***

## Bandwidth and Throughput

The **Statistics** panel exposes per-job and per-datastore throughput.

| Metric                                | Description                                                |
| ------------------------------------- | ---------------------------------------------------------- |
| **Effective transfer rate**           | Bytes per second of actual chunk transfer to the datastore |
| **Source read rate**                  | Bytes per second read from the workload                    |
| **Deduplication hit rate**            | Percentage of chunks already present in the datastore      |
| **Compression ratio**                 | Average post-Zstandard size against raw size               |
| **Pre-encrypt size vs. on-disk size** | Combined effect of deduplication and compression           |

A healthy production backup typically reports a deduplication hit rate above
70 percent for daily incrementals, with compression ratios between 2x and 4x for
mixed workloads.

***

## Email and Webhook Notifications

Project-scoped notification groups can be attached to backup jobs. Successful
runs, warnings, and failures dispatch to the notification group as defined by
your administrator. The same events surface in the in-Dashboard notification
inbox.

For per-event control, see [Notifications](/services/ironcore-backup/admin-guide/notifications).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Task appears stuck in `queued`" icon="hourglass">
    A worker slot is unavailable, or the scheduler is paused. Check **Backup
    Solution > Workers** for queue depth and worker health. Contact your
    administrator if no workers are online.
  </Accordion>

  <Accordion title="Task ended `WARNING` — what does that mean?" icon="alert-triangle">
    Non-fatal issues such as a skipped exclude path, a missing optional source,
    or partial deduplication failure. The task log lists each warning with the
    affected path.
  </Accordion>

  <Accordion title="Per-snapshot verification has stayed `STALE` for weeks" icon="clock">
    The platform-wide verification job is not running. Contact your
    administrator to start a verification schedule.
  </Accordion>

  <Accordion title="Bandwidth dropped suddenly" icon="gauge">
    A bandwidth limit may have been applied to the sync job or the datastore.
    Confirm with your administrator. If unintentional, raise or remove the
    limit.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Troubleshooting" icon="wrench" href="/services/ironcore-backup/user-guide/troubleshooting" color="#bf9667">
    Resolve failed backups and restores
  </Card>

  <Card title="Notifications" icon="bell" href="/services/ironcore-backup/admin-guide/notifications" color="#bf9667">
    Configure email and webhook delivery channels (administrator)
  </Card>

  <Card title="Verification and Validation" icon="check" href="/services/ironcore-backup/admin-guide/verification-validation" color="#bf9667">
    Schedule integrity verification and recovery drills
  </Card>

  <Card title="Backup Jobs" icon="calendar" href="/services/ironcore-backup/user-guide/backup-jobs" color="#bf9667">
    Set up scheduled jobs for recurring protection
  </Card>
</CardGroup>