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

# Table Health Dashboard & Alerting

> Monitor per-table health checks in real time from the Data Portal, drill into failures, remediate them, and configure email alerts for check failures and recoveries.

The **Table Health Dashboard** gives you a real-time, table-centric view of your tables' operational status directly in the StarTree Cloud Data Portal. Instead of digging through the cluster-wide Pinot admin console, you get a single grid of every table you manage, a pass/fail rollup per table, and one click to drill into exactly which checks are failing and why.

Layered on top of the dashboard is **Table Health Alerting**: a per-recipient, per-check email subscription system. Instead of having to keep the dashboard open, you can subscribe yourself (or a distribution list) to email alerts whenever a check starts failing, keeps failing, or recovers — scoped as broadly as "every table, every check" or as narrowly as a single check on a single table.

<Info>
  Both the dashboard and alerting live under the **Observability** section in the Data Portal left navigation, and require Pinot Admin permissions ([`PinotAdminSystemAdmin`](/corecapabilities/security/actions)). If your account doesn't have this section enabled yet, ask your StarTree Cloud admin.
</Info>

## Key features

* **Per-table rollup:** every table you have access to, with a Passing / N Failing summary and a `Last Checked` timestamp, sortable and filterable by health status.
* **Drill-down detail:** click into a table to see every check that runs against it, with a pass/fail chip, a human-readable description, and a **More info** view of the raw diagnostic payload.
* **One-click remediation:** for checks that support it (and when you have permission), fix the underlying issue — trigger a segment rebalance or a segment reload — without leaving the page.
* **Email alerting:** subscribe any email address to failure/recovery notifications for all tables and checks, or fine-tune down to individual (table, check) pairs.
* **Mute, don't just disable:** snooze a specific failing check's alerts until it next passes, instead of permanently turning notifications off.
* **Bulk controls:** enable, disable, mute, or unmute alerts across an entire check type or an entire recipient's subscriptions in one action.

## Accessing the Table Health Dashboard

<Steps>
  <Step title="Open Data Portal">
    Log in to the StarTree Cloud Data Portal for your cluster.
  </Step>

  <Step title="Go to Observability">
    In the left navigation, click **Observability**, then **Health Dashboard**.
  </Step>

  <Step title="Review the table grid">
    You'll land on the Table Health Dashboard, showing every table in scope with its current health rollup.
  </Step>
</Steps>

## Reading the dashboard

The dashboard header shows two summary chips — **Tables** (total count) and **Failing Tables** (highlighted in red when non-zero) — plus a **Last run** indicator with a manual **Refresh** button so you don't have to wait for the next automatic evaluation cycle.

The grid itself has four columns:

| Column           | What it shows                                                                                                                                                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table Name**   | The table's display name (suffix-stripped), with an **OFFLINE** / **REALTIME** badge. Click the name to open the table's detail page.                                                                                            |
| **Workspace**    | The workspace that owns the table (useful once you have more than the default workspace).                                                                                                                                        |
| **Health**       | Either **Passing**, or **N failing / M checks** with a row of colored dots — one per check, green for pass and red for fail (hover a dot to see its check name). Tables with no checks configured show **No checks configured**. |
| **Last Checked** | Relative time since the last health-check run (for example, "12 min ago").                                                                                                                                                       |

Use the **Health** column's filter icon to narrow the grid to **Passing**, **Failing**, or **No checks** tables. If you haven't created any tables yet, the dashboard shows an empty state with a **Create table** shortcut instead of a grid.

<Note>
  If your cluster has disabled periodic health checks entirely (Pinot's `controller.cluster.healthCheck.frequencyPeriod` set to `-1`), the dashboard shows a warning banner and the grid will not update. See [Cluster Health Dashboard](/corecapabilities/cluster-operations/use-cluster-health-dashboard) for how that setting is controlled.
</Note>

## Table details page

Clicking a table name opens its detail page: an accordion list with one entry per health check that applies to that table, sorted failing-first.

Each accordion row shows:

* The check's short label and its raw check key (for example, **Segment Assignment** / `TABLE_SEGMENT_ASSIGNMENT_CHECK`).
* A one-line description of what the check verifies.
* A **passed** / **failed** status chip.
* An **Email: On/Off** control — toggles this check's email alerts *for the currently selected recipient* on this specific table (see [Alerting](#alerting-email-notifications) below).
* For failing checks with email alerts on, a **Mute/Unmute** control to snooze that specific alert.

Expanding a row (failing checks auto-expand) reveals additional diagnostic detail returned by the check — for example, how many segments need to move, or which segments are affected — plus a **View** icon for any nested field, opening the raw JSON in a read-only viewer. Where a check supports it, one or more remediation buttons appear alongside this detail.

## Remediating failing checks

Two of the table-level checks currently ship with one-click remediation, gated by RBAC permissions:

| Check                            | What it means                                                                            | Remediation actions                                                                                            |
| -------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `TABLE_SEGMENT_ASSIGNMENT_CHECK` | The table needs rebalancing — segment assignment across servers is no longer optimal.    | **Rebalance segments** (triggers a rebalance) and **Rebalance status** (shows progress of the last rebalance). |
| `TABLE_SEGMENTS_RELOAD_CHECK`    | One or more segments need to be reloaded (for example, after a config or schema change). | **Reload segments** (triggers a reload) and **Reload status** (shows progress of the last reload).             |

<Warning>
  Remediation buttons only appear when **both** are true: your account is allow-listed to remediate in this environment, **and** you have write access (`Cluster.UPDATE_CLUSTER_CONFIG`) to the table's workspace. If you don't see a **Rebalance segments** or **Reload segments** button on a failing check that supports it, ask your StarTree Cloud admin to confirm your permissions.
</Warning>

Other table-level checks (segment size, segment retention, replication factor, column count, and more) surface as pass/fail with diagnostic detail, but don't yet have a one-click fix — see [Cluster Health Dashboard](/corecapabilities/cluster-operations/use-cluster-health-dashboard) for the full check catalog shared between both dashboards. Only a subset of table-level checks is surfaced on the Table Health Dashboard by default; reach out to your StarTree Cloud team if you'd like additional checks enabled for your environment.

## Alerting: email notifications

Alerting is managed from the **Notification Settings** page — click the gear icon next to **Last run** on the dashboard, or next to the table title on any table's detail page.

### How subscriptions work

A recipient's alert coverage is resolved from two kinds of preference rows:

* A **wildcard subscription** — "every table, every check, in every workspace with tables" — created the first time you subscribe a recipient.
* **Concrete overrides** — a specific (table, check) pair for that recipient, which always takes precedence over their wildcard.

This lets you subscribe someone to everything and then carve out exceptions (for example, turn off a single noisy check on one table) without touching the rest of their subscriptions.

### Subscribing a new recipient

<Steps>
  <Step title="Open Notification Settings">
    From the dashboard or a table detail page, click the gear icon.
  </Step>

  <Step title="Click Subscribe new user">
    Enter their email address. This creates a wildcard subscription — they'll immediately start receiving alerts for every table and check across every workspace.
  </Step>

  <Step title="Fine-tune from the grid">
    Use the recipient picker to select them, then adjust individual checks or tables as needed (see below).
  </Step>
</Steps>

### Managing a recipient's preferences

Once a recipient is selected in the picker, the page shows one collapsible section per health-check type (for example, **Table Segment Assignment Check**). Each section lists every (workspace, table) pair for that check, with its current **Passing** / **Failing** status and that recipient's effective **Email** and **Muted** state.

From here you can:

* Toggle **Email** for a single table/check cell, or flip the section header's switch to enable/disable the check for every table at once.
* **Mute** or **Unmute** a single failing cell, or use the section's **Mute All / Unmute All** to snooze every currently-failing, email-enabled row in that section.
* Use the page-level bulk actions — **Enable Email for All**, **Disable Email for All**, **Mute All Failing**, **Unmute All** — to act across the recipient's entire subscription in one click.
* Click the trash icon next to the recipient picker to **remove** them entirely — this deletes their wildcard subscription and every override, unsubscribing them from all table-health alerts. This can't be undone (they'd need to be re-subscribed from scratch).

<Tip>
  Muting is a temporary snooze, not a permanent opt-out: a muted check automatically un-mutes itself the next time it passes, so you won't need to remember to turn it back on.
</Tip>

### What triggers an email

Health checks are re-evaluated on a periodic cycle (by default, roughly every 20 minutes — the same cadence as the underlying cluster health check task). For each subscribed (recipient, table, check), an alert is generated when:

* A check goes from **passing to failing** — an immediate "new failure" notification.
* A previously-failing check **recovers** — an immediate "recovery" notification.
* A check is **still failing** after its first alert — a periodic reminder (roughly once every 24 hours) instead of a fresh alert every cycle, so you aren't paged repeatedly for a known, ongoing issue.
* Nothing is sent the very first time a table/check pair is observed (so subscribing to everything doesn't immediately blast you with the current state of the world) — you'll only hear about it once something actually changes.

Each recipient gets at most one digest email per evaluation cycle per workspace, grouping **new failures**, **still failing**, and **recovered** checks into separate sections (each capped to the top affected tables, with a "+N more" note for the rest). The email links back to the Table Health Dashboard and to the specific failing table's detail page, so you can jump straight from your inbox to the fix.

<Note>
  Alerting is currently **email only**. There is no Slack, PagerDuty, or webhook channel for Table Health alerts today.
</Note>

## Permissions required

The entire Observability section — the dashboard, table detail pages, and Notification Settings — requires Pinot Admin access (the `PinotAdminSystemAdmin` action). Triggering remediation additionally requires write access to the table's workspace and an allow-listed account, as described above.

## Related

* [Cluster Health Dashboard](/corecapabilities/cluster-operations/use-cluster-health-dashboard) — the cluster-, instance-, server-, broker-, controller-, and minion-level counterpart, covering the full health check catalog. Table Health surfaces a table-scoped subset of the same checks with a friendlier, per-table workflow plus alerting.
* [RBAC Actions](/corecapabilities/security/actions) — reference for `PinotAdminSystemAdmin` and other permission actions referenced above.