OpEx Dashboard

Generate standardized Operational Excellence dashboards from OpenAPI 3 specifications.

Features

• Automatic Dashboard Generation - Parses OpenAPI 3 specs to create standardized operational dashboards
• Multiple Cloud Providers - Azure (current), AWS CloudWatch, Grafana (planned)
• High Performance - Parallel rendering with deterministic ordering
• Type-Safe - Full TypeScript with Zod runtime validation

OpEx Dashboard is distributed as an npm package with two components:

• CLI tool (opex-dashboard) - Command-line interface for end users
• TypeScript library - Programmatic API for integration

Usage

npx @pagopa/opex-dashboard generate --help

Local Development

git clone https://github.com/pagopa/dx.git
cd dx/apps/opex-dashboard-ts
pnpm install
pnpm run build
pnpm run dev

Quick Start

1. Create Configuration File

# config.yaml
oa3_spec: ./openapi.yaml # or HTTP URL
name: My API Dashboard
location: West Europe
resource_type: app-gateway
data_source: /subscriptions/xxx/resourceGroups/my-rg/providers/Microsoft.Network/applicationGateways/my-gtw
action_groups:
  - /subscriptions/xxx/resourceGroups/my-rg/providers/microsoft.insights/actionGroups/my-alerts

2. Generate Dashboard

# Output to stdout
npx @pagopa/opex-dashboard generate -t azure-dashboard-raw -c config.yaml

# Save as Terraform package
npx @pagopa/opex-dashboard generate -t azure-dashboard -c config.yaml --package ./output

3. Deploy with Terraform

The deployment process depends on the configuration mode you chose:

Multi-Environment Mode

When using the multi-environment configuration (with environments section), the generated package includes separate subdirectories for each environment:

cd output/azure-dashboard
# Deploy to dev
terraform init -backend-config=env/dev/backend.tfvars
terraform apply -var-file=env/dev/terraform.tfvars

# Deploy to prod
terraform init -backend-config=env/prod/backend.tfvars
terraform apply -var-file=env/prod/terraform.tfvars

Generated structure:

output/azure-dashboard/
├── main.tf
├── variables.tf
├── dashboard.tf
└── env/
    ├── dev/
    │   ├── backend.tfvars
    │   └── terraform.tfvars
    ├── uat/
    │   ├── backend.tfvars
    │   └── terraform.tfvars
    └── prod/
        ├── backend.tfvars
        └── terraform.tfvars

Flat Mode

When using flat configuration (with prefix and env_short directly under terraform), all files are generated in the root directory:

cd output/azure-dashboard
terraform init -backend-config=backend.tfvars
terraform apply -var-file=terraform.tfvars

Generated structure:

output/azure-dashboard/
├── main.tf
├── variables.tf
├── dashboard.tf
├── backend.tfvars
└── terraform.tfvars

Use flat mode when:

• Deploying to a single environment
• Managing infrastructure for a specific environment in a separate repository
• You don't need environment-specific subdirectories

Use multi-environment mode when:

• Managing multiple environments (dev/uat/prod) in the same repository
• You want organized environment-specific configurations in subdirectories

Dashboard Components

For each endpoint in the OpenAPI spec, the dashboard includes:

Graphs

1. Availability: HTTP success rate (status codes < 500)
2. Response Codes: Segmentation of all HTTP status codes (1XX, 2XX, 3XX, 4XX, 5XX)
3. Response Time: 95th percentile response time

Alarms

1. Availability Alarm: Triggers when availability drops below threshold (default: 99%)
2. Response Time Alarm: Triggers when response time exceeds threshold (default: 1 second)

Configurable Parameters

For each alarm, you can configure:

• Timespan (Default: 5m) - The aggregation window
• Evaluation Frequency (Default: 10 minutes) - How often to evaluate the rule
• Time Window (Default: 20 minutes) - Data fetch window (must be ≥ evaluation frequency)
• Event Occurrences (Default: 1) - Number of events needed to trigger alert

NOTE: Maximum event occurrences = time window ÷ timespan. For example, with a 30m window and 5m timespan, max is 6 events.

Usage

CLI Commands

opex-dashboard generate [options]

Options:
  -t, --template-type <type>    Template type: azure-dashboard or azure-dashboard-raw (required)
  -c, --config <path>           Path to YAML config file, use - for stdin (required)
  --package [path]              Save as package in directory (default: current dir)
  -h, --help                    Display help
  -V, --version                 Display version

Configuration

Create a YAML configuration file:

# yaml-language-server: $schema=./config.schema.json
# Required fields
oa3_spec: string # Path or URL to OpenAPI 3 specification
name: string # Dashboard name
location: string # Azure region (e.g., "West Europe")
data_source: string # Azure resource ID
action_groups: string[] # Array of Azure Action Group IDs

# Optional fields (with defaults)
resource_type: app-gateway | api-management # Default: app-gateway
resource_group: string # Default: dashboards (Azure resource group for dashboard and alerts)
timespan: string # Default: 5m
evaluation_frequency: integer # Default: 10 (minutes)
evaluation_time_window: integer # Default: 20 (minutes)
event_occurrences: integer # Default: 1
availability_threshold`: float # Default: 0.99 (99%)
response_time_threshold: float # Default: 1.0 second

# When generating Terraform packages (using `--package` option),
# you can optionally configure environment-specific settings.
# Two configuration modes are supported:

# 1. Multi-environment mode (with subdirectories):
terraform:
  environments:
    dev:
      prefix: string # Max 6 chars (required)
      env_short: string # Max 1 char: 'd', 'u', 'p' (required)
      backend: # Optional backend state configuration
        resource_group_name: string
        storage_account_name: string
        container_name: string
        key: string
    uat: # Similar to dev
    prod: # Similar to dev

# 2. Flat mode (single environment, no subdirectories):
terraform:
  prefix: string # Max 6 chars (required)
  env_short: string # Max 1 char: 'd', 'u', 'p' (required)
  backend: # Optional backend state configuration
    resource_group_name: string
    storage_account_name: string
    container_name: string
    key: string

See examples/ directory for complete configuration samples.

JSON Schema Validation

A JSON Schema is automatically generated from the TypeScript types and included at config.schema.json. This enables IDE autocomplete and validation for your configuration files.

To enable schema validation in VS Code and other compatible editors, add this comment at the top of your YAML configuration file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/pagopa/dx/refs/heads/main/apps/opex-dashboard-ts/config.schema.json

The schema is:

• Automatically generated during build from Zod schemas using pnpm run build
• Synchronized with TypeScript types - any changes to configuration structure are reflected immediately
• Versioned - matches the package version for compatibility tracking
• Distributed with the npm package for programmatic access

CI/CD Integration

Using the GitHub Workflow from Another Repository

You can use the reusable workflow to automate dashboard generation in your own repository. Create a .github/workflows/generate-dashboard.yml file in your repo:

name: Generate Dashboard

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  generate:
    uses: pagopa/dx/.github/workflows/generate.yml@main
    with:
      # mandatory inputs:
      config_path: ./config/dashboard-config.yaml
      output_dir: ./generated
      # optional inputs with defaults:
      pr_title: "Update operational dashboard"
      pr_body: "Automated update of dashboard terraform from OpenAPI spec"
      base_branch: main

This workflow will:

1. Generate the dashboard using your configuration
2. Commit changes to a new branch
3. Create a pull request for review

Workflow Inputs

• config_path (required): Path to your YAML configuration file
• output_dir (required): Directory to save generated files
• template_type (optional): Template type (azure-dashboard or azure-dashboard-raw, default: azure-dashboard)
• pr_title (optional): Title for the generated pull request
• pr_body (optional): Description for the generated pull request
• base_branch (optional): Base branch for the pull request (default: main)

Development

Setup

pnpm install
pnpm run build