npm package: @pagopa/opex-dashboard
Description: Generate operational dashboards from OpenAPI specifications
Latest version: 0.2.5

# 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

```bash
npx @pagopa/opex-dashboard generate --help
```

### Local Development

```bash
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

```yaml
# 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

```bash
# 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:

```bash
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:

```bash
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

```bash
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
# 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/`](./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`](./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
# 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:

```yaml
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

```bash
pnpm install
pnpm run build
```