Skip to Content
User GuideDashboard Design

Dashboard Design

Dashboards give your team a single pane of glass for metrics, logs, incidents, and topology. This guide covers designing and building them in an enterprise-friendly way.

Where to find dashboards

  1. Dashboards in the left sidebar — List of existing dashboards; New dashboard to create one.
  2. Open any dashboard to edit (add widgets, resize, set variables and refresh).

Dashboard list — Name, Owner, Last updated, Actions

Capture from: Tenant Plane → OBSERVE → Dashboards (list view). Add screenshot as public/img/dashboard-list.png.

Creating a new dashboard

  1. Click New dashboard (or Create dashboard).
  2. Enter a name (e.g., “Production API health”) and optional description.
  3. Save. You’re taken to the canvas (empty grid).

Empty dashboard canvas — Add widget grid

Capture from: Tenant Plane → Dashboards → New dashboard. Add as public/img/dashboard-empty.png.

Adding widgets

  1. Click Add widget (or drag from a widget palette).
  2. Choose widget type, for example:
    • Time series — Line/area chart for metrics over time.
    • Bar chart — Compare values across categories (e.g., errors by service).
    • Gauge — Single value (e.g., current error rate, SLO).
    • Table — Logs, incidents, or tabular data.
    • Log stream — Live or filtered log lines.
    • Topology map — Service/CI dependency map.
    • Incident list — Active incidents (optional filters).
    • Markdown — Titles, descriptions, links.
  3. Configure data source:
    • For metrics: Select metric name, aggregation (avg, sum, max), and optional filters (service, host, tag).
    • For logs: Query (e.g., level:ERROR), time range, limit.
    • For incidents: Status, severity, service filters.
  4. Resize and position the widget on the grid (drag corners or use size controls).
  5. Save the dashboard.

Widget config panel — Type, metric/query, aggregation, filters

Capture from: Tenant Plane → Dashboards → Edit → Add widget. Add as public/img/dashboard-widget-config.png.

Using template variables

Template variables let viewers change scope (e.g., service, environment) without editing the dashboard.

  1. In dashboard settings or variables, click Add variable.
  2. Define:
    • Name — e.g., service, env.
    • Label — Shown in the UI (e.g., “Service”).
    • Type — Dropdown, multi-select, or text.
    • Data source — e.g., list of services from API, or static list (prod, staging).
  3. In each widget, reference the variable in queries (e.g., service = $service, or $env in a metric tag). When the user picks a value, widgets refresh.

Example: Add variable $service (dropdown, values from services API). In a time series widget, set metric filter service = $service. Users can switch services from the dropdown.

Dashboard with variable dropdown — Service: All | api-gateway | order-service

Capture from: Tenant Plane → Dashboards → Edit (with variables). Add as public/img/dashboard-variables.png.

Auto-refresh and time range

  1. Time range — Set the default (e.g., Last 1 hour, Last 24 hours). Users can often override per view.
  2. Auto-refresh — Set interval (e.g., 30s, 1m, 5m) so the dashboard updates without manual reload. Use sparingly on heavy dashboards.

Example: Production API health dashboard

  1. Create dashboard “Production API health.”
  2. Row 1: Time series — Request rate (metric request_count, sum by service). Add variable $service; filter by $service if not “All.”
  3. Row 2: Time series — Error rate (metric error_rate or errors/total, avg). Same $service filter.
  4. Row 3: Gauge — Current P99 latency (metric latency_p99, last value). Table — Top 5 errors (log query level:ERROR, group by message, limit 5).
  5. Row 4: Incident list — Active incidents for service = $service (or all).
  6. Set time range Last 1 hour, auto-refresh 1 minute. Save.

Example dashboard — time series, gauge, table, incident list

Capture from: Tenant Plane → Dashboards → example with sample data. Add as public/img/dashboard-example-api-health.png.

Best practices

  • One purpose per dashboard — e.g., “API health,” “Database tier,” “Incident summary.” Avoid huge catch-all dashboards.
  • Put critical metrics top-left — Most important SLO or error rate first.
  • Use variables for teams that need to switch service/env/region without cloning dashboards.
  • Name widgets clearly — e.g., “Orders API — request rate” so the intent is obvious.
  • Link to runbooks/playbooks — Add a Markdown widget with links to relevant runbooks or status pages.

Sharing and access

  • Share — Invite users or teams (if your product supports it); or share a read-only link.
  • Export — Some products support export to PDF or JSON (dashboard-as-code) for version control.
  • Default view — Set a dashboard as the default home for a role or team so they land there after login.

Next steps

Monitoring PoliciesSettings, Users & RBAC