Dashboard Configuration¶

The metrics dashboard uses a YAML-driven configuration system. All layout, metric placement, and sector definitions are managed through YAML files and JavaScript metric definitions. No code changes are needed to add new metrics or rearrange the layout.

Configuration Hierarchy¶

public/dashboard.yml                  -- Sector index (ordering, icons, palettes)
  |
  +-- public/dashboards/overview.yml  -- Sector layout (metrics, tabs, grid)
  +-- public/dashboards/consensus.yml
  +-- public/dashboards/bridges.yml
  +-- ...
  |
src/queries/*.js                      -- Metric definitions (SQL, chart type, formatting)

At startup, the frontend loads dashboard.yml, resolves each sector's source file, and merges the layout entries with metric definitions from src/queries/ to produce fully configured widgets.

Sector Index (dashboard.yml)¶

The top-level public/dashboard.yml defines the sector catalog:

Overview:
  name: Overview
  order: 1
  icon: "chart-icon"
  iconClass: "chart-line"
  source: /dashboards/overview.yml

GnosisPay:
  name: Gnosis Pay
  order: 10
  icon: "card-icon"
  iconClass: credit-card
  palette: gnosis-pay
  source: /dashboards/gnosis-pay.yml

Consensus:
  name: Consensus
  order: 20
  icon: "validator-icon"
  iconClass: "shield-check"
  source: /dashboards/consensus.yml

Sector Properties¶

Sector Layout Files¶

Each sector file in public/dashboards/ defines either a flat list of metrics or a tabbed layout.

Simple Layout (Flat Metrics)¶

metrics:
  - id: overview_total_transactions
    gridRow: 1
    gridColumn: 1 / span 2
    minHeight: 130px

  - id: overview_active_validators
    gridRow: 1
    gridColumn: 3
    minHeight: 130px

  - id: overview_daily_transactions_chart
    gridRow: 2
    gridColumn: 1 / span 3
    minHeight: 400px

Tabbed Layout¶

tabs:
  - name: Validators
    metrics:
      - id: consensus_active_validators
        gridRow: 1
        gridColumn: 1 / span 3
        minHeight: 400px

      - id: consensus_validator_deposits
        gridRow: 2
        gridColumn: 1 / span 2
        minHeight: 350px

  - name: Attestations
    metrics:
      - id: consensus_attestation_rate
        gridRow: 1
        gridColumn: 1 / span 3
        minHeight: 400px

Grid Placement Properties¶

Metric Definitions (src/queries/)¶

Each metric is defined as a JavaScript module exporting a configuration object:

// src/queries/dailyTransactions.js
const dailyTransactions = {
  id: 'daily_transactions',
  name: 'Daily Transactions',
  description: 'Total transactions per day on Gnosis Chain',
  metricDescription: 'Counts all transactions included in blocks...',
  format: 'formatNumber',
  chartType: 'line',
  color: '#00BCD4',
  query: `
    SELECT
      toDate(dt) AS date,
      txs AS value
    FROM dbt.api_execution_transactions_daily
    WHERE dt BETWEEN '{from}' AND '{to}'
    ORDER BY date
  `
};

export default dailyTransactions;

Metric Properties¶

Chart Types¶

The dashboard supports several chart types, each suited to different data visualizations:

The NumberDisplay type renders a large headline number with an optional percentage change indicator. It is typically used in the first row of a sector layout for key performance indicators.

Query Placeholders¶

SQL queries support these placeholder tokens, which are replaced at request time:

Adding a New Metric¶

1. Create the metric definition in src/queries/:

   // src/queries/newMetric.js
   const newMetric = {
     id: 'new_metric_id',
     name: 'My New Metric',
     description: 'Description of the metric',
     format: 'formatNumber',
     chartType: 'line',
     color: '#4CAF50',
     query: `
       SELECT
         toDate(dt) AS date,
         some_column AS value
       FROM dbt.api_execution_some_table
       WHERE dt BETWEEN '{from}' AND '{to}'
       ORDER BY date
     `
   };
   
   export default newMetric;
   

2. Place the metric in a sector YAML file (public/dashboards/<sector>.yml):

   metrics:
     # ... existing metrics ...
     - id: new_metric_id
       gridRow: 3
       gridColumn: 1 / span 3
       minHeight: 400px
   

3. Export the query to the API layer:

   pnpm run export-queries
   

   This script copies metric queries from src/queries/ to api/queries/ in the JSON format consumed by the serverless API.

4. Test locally:

   pnpm dev
   

5. Deploy:

   vercel --prod
   

Adding a New Sector¶

1. Create the sector layout file at public/dashboards/<new-sector>.yml:

   metrics:
     - id: first_metric
       gridRow: 1
       gridColumn: 1 / span 3
       minHeight: 400px
   

2. Register the sector in public/dashboard.yml:

   NewSector:
     name: New Sector
     order: 50
     icon: "new-icon"
     iconClass: "layers"
     source: /dashboards/new-sector.yml
   

3. Restart the development server. The new sector will appear in the sidebar navigation.

Palette System¶

Dashboards can opt into named color palettes defined in src/utils/dashboardPalettes.js. Palettes are applied at the dashboard level and affect all charts within that sector.

Precedence Rules¶

1. Metric-level colors win: If a metric defines color, colors, bandColors, lineColors, or map-specific overrides, those are used regardless of the dashboard palette.
2. Dashboard palette applies as fallback: When metric-level colors are not explicitly defined, the dashboard's palette colors are used.
3. Standard fallback: If no dashboard palette is set or the palette name is invalid, the standard palette is used.
4. Fill from standard: If a custom palette has fewer colors than the number of chart series, additional colors are drawn from the standard palette before repeating.

Defining a New Palette¶

Add a new preset to src/utils/dashboardPalettes.js:

export const PALETTES = {
  standard: ['#3366CC', '#DC3912', '#FF9900', ...],
  'gnosis-pay': ['#04795B', '#06A87D', '#08D49E', ...],
  'my-palette': ['#1A1A2E', '#16213E', '#0F3460', '#E94560'],
};

Then reference it in dashboard.yml:

MyDashboard:
  palette: my-palette
  source: /dashboards/my-dashboard.yml

Caching Configuration¶

The serverless API implements server-side caching to minimize ClickHouse query load.

Environment Variables¶

Cache Behavior by Environment¶

Manual Cache Operations¶

Force a cache refresh for a specific request:

GET /api/metrics?refreshCache=true

Check cache status:

GET /api/test

(Requires X-API-Key header)

Override Per-Request¶

You can explicitly control caching on any request:

GET /api/metrics/daily_transactions?useCached=false    # Force fresh query
GET /api/metrics/daily_transactions?useCached=true     # Use cache even in dev

Environment Variables¶

Backend (Serverless API)¶

Frontend (Vite)¶

Development¶

Local Setup¶

git clone https://github.com/gnosischain/metrics-dashboard.git
cd metrics-dashboard
pnpm install
cp .env.example .env
# Edit .env with ClickHouse credentials
pnpm dev

Mock Data Mode¶

Run without ClickHouse by enabling mock data generation:

VITE_USE_MOCK_DATA=true pnpm dev

The API will generate synthetic data for all metrics.

Deployment¶

# Install Vercel CLI
npm install -g vercel
vercel login

# Deploy to production
vercel --prod

Set environment variables in the Vercel dashboard under Settings > Environment Variables.