---
title: 'Install Dashboards'
description: 'One-click provisioning of pre-built Yorker synthetic monitoring dashboards into self-hosted HyperDX or ClickStack Cloud.'
section: 'Guides'
canonical_url: 'https://yorkermonitoring.com/docs/guides/install-dashboards'
---

# Install Dashboards

Yorker ships 8 pre-built dashboards that provision directly into your observability platform via its Dashboard API. No manual chart creation required. Both self-hosted HyperDX and ClickStack Cloud (ClickHouse-managed HyperDX) are supported. All carry the `yorker-synthetics` tag so the platform groups them together.

## Dashboards included

| Dashboard | What it shows |
|---|---|
| **[Yorker] Synthetic Monitoring Overview** | Active monitors, total runs, avg response time, failed checks, response time by monitor, success vs failure, monitor run table, recent failed runs |
| **[Yorker] Monitor Deep Dive** | Per-monitor drill-down: avg/P95, response time trend, run status distribution, response time by location, recent failures (filterable by monitor) |
| **[Yorker] SLO & Error Budget** | Current availability, SLO target, error budget remaining, burn rate (1h/6h/24h), availability vs target, SLO summary (driven by SLOs configured in Yorker) |
| **[Yorker] Run Explorer** | Total/successful/failed runs, P95, runs-over-time by status, P50/P95/P99 latency, runs by monitor & location, raw run feed (filterable by monitor & location) |
| **[Yorker] Performance Forensics** | Per-phase decomposition: DNS / TCP / TLS / TTFB / total p95, web vitals (LCP / FCP / CLS), per-monitor phase breakdown table |
| **[Yorker] Third-Party & Dependencies** | Avg third-party request count + byte weight, byte trend, per-monitor byte weight table, shared-dependency blast radius (which third-party hosts the most monitors depend on), heavy-3p run feed |
| **[Yorker] Anomaly & AI Insights** | Anomalous run count, max + avg σ deviation, monitors with anomalies, deviation severity over time, observed vs Yorker-learned baseline, most-anomalous monitors with peak σ and recent anomalous run feed |
| **[Yorker] TLS & Certificate Health** | Min days to expiry, distinct TLS hosts, HTTPS handshake p95, days-to-expiry trend by host, per-monitor handshake latency, TLS protocol mix (flags TLS 1.0 / 1.1), renewal worklist, chain-issues search (invalid / untrusted / self-signed) |

## Prerequisites: data sources

The dashboards read from up to three **sources** in your observability platform (**Traces**, **Logs**, and **Metrics**), and the installer wires each tile to the matching one. Yorker emits all three signals for every check run, so a complete setup has all three sources defined:

| Source | Backs | Example dashboards |
|---|---|---|
| **Traces** | Per-run spans (`service.name = synthetics`, span `synthetics.check.run`) | Overview, Monitor Deep Dive, Run Explorer, Third-Party, TLS Health, Performance Forensics |
| **Logs** | Per-run log records, anomaly + SLO signals | Overview, Monitor Deep Dive, SLO & Error Budget, Anomaly & AI Insights |
| **Metrics** | Aggregated metrics (response-time percentiles, web vitals) | Performance Forensics, TLS Health |

Several dashboards read from more than one source: Overview and Monitor Deep Dive each combine Traces and Logs, Performance Forensics is mostly Metrics with one Traces tile, and TLS Health mixes Traces and Metrics. A tile fails for whichever source it needs that is missing, so a multi-source dashboard can install partially.

If a source is missing, only the tiles that use it fail; the rest of that dashboard installs. Worked example: with Logs and Metrics sources but no Traces source, the two logs-only dashboards (SLO & Error Budget, Anomaly & AI Insights) install fully, the trace-only dashboards (Run Explorer, Third-Party) fail entirely, and the mixed dashboards (Overview, Monitor Deep Dive, Performance Forensics, TLS Health) install their non-trace tiles while their trace tiles are rejected.

**To add a missing source:** in your HyperDX or ClickStack Cloud console, open the data **Sources** settings and add a source of the missing type (Trace / Log / Metric), pointing it at the matching OpenTelemetry table (`otel_traces`, `otel_logs`, or `otel_metrics` in the default ClickHouse OTel schema). Then re-run the install. It is safe to re-run, as existing dashboards are skipped.

The installer checks your sources before it does anything, so if one is missing you get a message naming it (and the dashboards that need it) rather than a partial install.

## Install via the web UI

1. Go to **Settings > Telemetry (OTLP)**
2. Under **Dashboard Provisioning**, select your deployment type (**Self-hosted** or **ClickStack Cloud**)
3. For ClickStack Cloud: enter your Organization ID, Service ID, and Cloud API key credentials
4. Click **Save Changes**, then click **Install Dashboards**

Self-hosted mode uses the same HyperDX API key already configured for telemetry. ClickStack Cloud uses ClickHouse Cloud API credentials (found in your ClickHouse Cloud console under API Keys).

## Install via the CLI

### Self-hosted HyperDX

`--hyperdx-url` is required for self-hosted: it is the HyperDX External API base, which serves on a different host/port from OTLP ingest (for example ClickStack uses OTLP `:4318`, API `:8000`) and is not derived from anything else.

```bash
yorker dashboards install \
  --hyperdx-api-key <your-key> \
  --hyperdx-url https://hyperdx.example.com
```

### ClickStack Cloud

```bash
yorker dashboards install --mode clickstack_cloud \
  --clickstack-org-id <org-uuid> \
  --clickstack-service-id <service-uuid> \
  --clickstack-api-key-id <key-id> \
  --clickstack-api-secret <key-secret>
```

All ClickStack options support environment variables (`CLICKSTACK_ORG_ID`, `CLICKSTACK_SERVICE_ID`, `CLICKSTACK_API_KEY_ID`, `CLICKSTACK_API_SECRET`).

### Options

| Flag | Description |
|---|---|
| `--mode <mode>` | `self_hosted` (default) or `clickstack_cloud` (env: `HYPERDX_MODE`) |
| `--hyperdx-api-key <key>` | HyperDX API key for self-hosted mode (env: `HYPERDX_API_KEY`) |
| `--hyperdx-url <url>` | HyperDX External API base URL, **required** for self-hosted (env: `HYPERDX_URL`) |
| `--clickstack-org-id <id>` | ClickHouse Cloud organization ID (env: `CLICKSTACK_ORG_ID`) |
| `--clickstack-service-id <id>` | ClickHouse Cloud service ID (env: `CLICKSTACK_SERVICE_ID`) |
| `--clickstack-api-key-id <id>` | ClickHouse Cloud API key ID (env: `CLICKSTACK_API_KEY_ID`) |
| `--clickstack-api-secret <secret>` | ClickHouse Cloud API key secret (env: `CLICKSTACK_API_SECRET`) |
| `--packs <list>` | Comma-separated subset: `overview`, `deep-dive`, `slo`, `events`, `performance-forensics`, `third-party`, `anomaly-insights`, `tls-health` |
| `--force` | Skip duplicate check (may create additional copies) |
| `--json` | Output results as JSON |

### Examples

```bash
# Self-hosted: install all dashboards
yorker dashboards install --hyperdx-api-key hdx_abc123 --hyperdx-url https://hyperdx.example.com

# Self-hosted: install only the overview dashboard
yorker dashboards install --hyperdx-api-key hdx_abc123 --hyperdx-url https://hyperdx.example.com --packs overview

# ClickStack Cloud: install all dashboards via env vars
export CLICKSTACK_ORG_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export CLICKSTACK_SERVICE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export CLICKSTACK_API_KEY_ID=your-key-id
export CLICKSTACK_API_SECRET=your-key-secret
yorker dashboards install --mode clickstack_cloud
```

## Idempotency

Dashboards are named with a `[Yorker]` prefix. The install command checks for existing dashboards by name and skips duplicates automatically. Use `--force` to skip this check (note: this may create additional copies rather than replacing existing ones).

## Screenshots in dashboards

The Deep Dive, Run Explorer, Performance Forensics, and Anomaly & AI Insights dashboards include search panels that surface `synthetics.screenshot.url` and other run metadata. When a browser check captures screenshots, the URL appears as a clickable link directly in the dashboard.