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

# Grafana dashboards

> Reach Grafana from the Data Portal, find the dashboard for what you are investigating, read the Pinot panels, and build your own charts on your cluster's metrics and logs.

Grafana is the metrics and log surface for your StarTree Cloud cluster. It is where you see a signal over time — the last hour, the last week, before and after a change — as opposed to the current-state views in the Data Portal. It reads only your own cluster's data.

## Getting there

<Steps>
  <Step title="Open it from the Data Portal">
    In the Data Portal left navigation, go to **Monitoring** → **Grafana Dashboard**. It opens in a new tab.
  </Step>

  <Step title="Sign in with the same identity provider">
    Grafana uses the same single sign-on as the Data Portal, so in most cases you land already authenticated. If you are prompted, sign in with the same credentials you use for StarTree Cloud.
  </Step>
</Steps>

<Note>
  Each cluster environment has its own Grafana. If you have more than one environment, there is no combined view across them, and a dashboard link from one environment will not resolve against another — always follow the link from the Data Portal you are working in.
</Note>

## Panels embedded in the Data Portal

You do not always have to leave the Data Portal. The task views embed Grafana panels directly, scoped to the work you are looking at:

| Where                                           | What it shows                                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| A **task plan's Observability** tab             | Minion task progress for that plan, alongside the affected table's segment count and total document count |
| A **task plan's Logs** tab                      | Minion task progress panels for the plan's generation                                                     |
| A **submitted task** or **subtask** detail view | The minion progress panel for that specific task or subtask                                               |

Embedded panels carry a **Refresh** and a **Reconnect to Grafana** action, and a time-range selector on the task-plan views. For anything beyond that — a wider window, a different query, a table-level view — go to the dashboards directly.

<Info>
  Embedded panels need a live Grafana session in the same browser. When one is not detected you will see a **Sign in to Grafana** prompt — click it, complete sign-in in the tab that opens, and return; the panels mount shortly afterwards. Panel embedding is enabled per environment, so on some environments the panels link out to Grafana rather than rendering inline.
</Info>

## Dashboard catalogue

Dashboards are organized into folders. Use the search icon or **Dashboards** in the Grafana navigation to list them.

### Pinot

The core set. Most investigations start here.

| Dashboard                                                       | Use it for                                                                                                                                                                                                |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pinot Servers**                                               | The busiest dashboard: query rate and latency per table and per server, docs and entries scanned, segment counts, real-time consumption, CPU and heap. Start here for both query and ingestion questions. |
| **Pinot Server Ingestion**                                      | Real-time ingestion in detail — consumption rate, ingestion delay and offset lag per partition, consumption exceptions, rows with errors.                                                                 |
| **Pinot - Broker** (listed as *Pinot - Broker - Parameterized*) | Broker-side query volume, latency, error breakdown by cause, and routing exceptions.                                                                                                                      |
| **Pinot Controllers**                                           | Controller health, leadership, segment state convergence, ZooKeeper znode sizes.                                                                                                                          |
| **Pinot Minions**                                               | Minion pod resource use and availability.                                                                                                                                                                 |
| **Pinot Minion Tasks**                                          | Task and subtask counts by type and state, error rates, wait and run times.                                                                                                                               |
| **Minion Task Progress**                                        | Progress of a specific task generation — the dashboard behind the task-plan panels in the Data Portal.                                                                                                    |
| **Pinot Upsert**                                                | Primary-key counts, document-to-key ratio, upsert metadata memory, off-heap upsert internals.                                                                                                             |
| **Pinot MultiStage Engine**                                     | Multi-stage query volume, latency, serialization and deserialization cost, data exchanged between stages.                                                                                                 |
| **Pinot System Table**                                          | The query-log pipeline, built over `system_query_log`.                                                                                                                                                    |
| **Table Rebalance**                                             | Segment movement during a rebalance — use it to confirm a rebalance is progressing rather than stalled.                                                                                                   |
| **Pinot ZooKeeper**                                             | Quorum, leadership, request latency, znode counts.                                                                                                                                                        |
| **Pinot - Proxy**                                               | Request volume and latency through the query proxy, including gRPC.                                                                                                                                       |

### Logging

Log search for your cluster's components. Covered in detail in [Accessing logs](/corecapabilities/observability/access-logs).

| Dashboard                             | Use it for                                                                                     |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Logging / Common**                  | Historical log search across any component, filtered by log group, application, pod, and level |
| **Logging / Application Logs**        | Pinot and StarTree application logs                                                            |
| **Logging / Query Stats**             | Query log lines with latency, rows, and the query text                                         |
| **Logging / Slow Queries Drilldown**  | Slowest queries over a window, drillable by request ID                                         |
| **Logging / Table Queries**           | Query activity for one table                                                                   |
| **Logging / Kubernetes Events**       | OOM kills, failed liveness checks, evictions                                                   |
| **Logging / Tool & K8s Cluster Logs** | Supporting component logs                                                                      |

### Capacity and resources

| Dashboard                      | Use it for                                                                                                      |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Total Provisioned Capacity** | What your environment is provisioned for, against what it is using. The one to open before asking for a resize. |
| **JVM**                        | Heap, garbage collection, and thread state per component.                                                       |

Other folders cover the infrastructure your environment runs on. They are useful for one specific question — confirming that a component was restarted or killed for memory rather than crashing on its own — and [Troubleshooting resource pressure](/corecapabilities/cluster-operations/troubleshooting) covers when that matters. Otherwise, start from the Pinot dashboards, which are the ones expressed in terms of tables, queries, and segments.

## Reading the Pinot dashboards

Three things to do before drawing conclusions from a panel:

<Steps>
  <Step title="Set the template variables">
    Most Pinot dashboards have selectors at the top — table, server, partition, task type. A panel with no table selected is showing you either everything summed together or nothing. Table names carry their type suffix, so `orders_REALTIME` and `orders_OFFLINE` are separate entries for a hybrid table.
  </Step>

  <Step title="Widen the time range past the incident">
    The default range is short. Widen to at least several times the duration of what you are investigating — a latency step change is only visible if the window contains both sides of it. When comparing against an upgrade or config change, put the change roughly in the middle.
  </Step>

  <Step title="Check whether a flat line is zero or absent">
    A metric with no recorded value is absent rather than zero, so an empty panel can mean "this never happened" — a task type that has not run, a table never queried. Confirm against a related panel that you know should have data before treating emptiness as a finding.
  </Step>
</Steps>

## Building your own charts

You have full access to query your cluster's metrics, and creating dashboards is the normal way to track something specific to your workload.

<Steps>
  <Step title="Start from a panel that nearly works">
    Open the panel menu on any built-in panel and choose **Explore**. You get its query with the correct metric name, labels, and aggregation already in place — far quicker and less error-prone than composing one from scratch.
  </Step>

  <Step title="Adjust the query">
    See the [metrics reference](/corecapabilities/observability/metrics-reference) for the naming convention, the available suffixes, and the label set. The most common mistake is aggregating across the wrong label — check what labels the series actually carries before adding a `sum by`.
  </Step>

  <Step title="Save into your own folder">
    Create a new dashboard rather than editing a built-in one, and save it in a folder of your own.
  </Step>
</Steps>

<Warning>
  **Do not edit the built-in dashboards.** StarTree maintains them, so an edit you make in place can be replaced without warning when they are updated. Duplicate the dashboard instead (**Dashboard settings** → **Save as**), put the copy in your own folder, and edit that.
</Warning>

## Retention and limits

Metrics and logs are retained for a bounded window — long enough for post-incident analysis, not long enough for capacity planning across quarters. If you need a trend over a longer period than Grafana holds, export the panel data (**Panel** → **Inspect** → **Data**) while it is still in range, or ask your StarTree team what the retention is for your environment.

For log retention specifically, see [Accessing logs](/corecapabilities/observability/access-logs#retention).

## If you cannot get in

| Symptom                                                           | Likely cause                                                                                                                                                     |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sign-in loops or is rejected                                      | Your account may not yet have access to this environment's Grafana. Ask your StarTree Cloud admin.                                                               |
| Grafana loads but dashboards are missing                          | You are on a different environment's Grafana. Go back to the Data Portal you were working in and follow its **Grafana Dashboard** link.                          |
| Panels in the Data Portal show a sign-in prompt that never clears | The Grafana session was not established. Open Grafana directly in another tab, confirm you are signed in, then reload the Data Portal page.                      |
| A dashboard exists but every panel is empty                       | Either the time range predates the environment, or nothing has published those metrics yet. Try the **Pinot Servers** dashboard over the last hour as a control. |

## Related

* [Metrics reference](/corecapabilities/observability/metrics-reference) — metric names, suffixes, and labels
* [Accessing logs](/corecapabilities/observability/access-logs) — the Logging dashboards and the log APIs
* [Troubleshooting: start here](/corecapabilities/observability/troubleshooting) — symptom-first diagnostic guides
* [Table Health Dashboard](/corecapabilities/observability/table-health-and-alerting) — current-state checks in the Data Portal