Spring Batch Frontend Plugin for Backstage

Frontend plugin for monitoring Spring Batch job executions in Backstage. Provides a comprehensive dashboard UI for viewing job statistics, execution history, and failure analysis.

Features

• 📊 Dashboard Overview: Real-time statistics and recent execution history
• 🔍 Advanced Filtering: Filter by status, job name, date range, and Boot version
• 📈 Analytics & Trends: Visualize execution patterns over time
• ❌ Failure Analysis: Dedicated view for failed jobs with error details
• 🔄 Retry History: Track job instance retry attempts and outcomes
• 🌍 Multi-Environment Support: Switch between different environments (dev, staging, production)
• 🎨 Modern UI: Material-UI components with responsive design

Prerequisites

This frontend plugin requires the backend plugin to be installed and configured:

• @jikwan/backstage-plugin-spring-batch-dashboard-backend - REST API for Spring Batch metadata
  • See backend plugin README for setup instructions

Installation

cd packages/app
yarn add @jikwan/backstage-plugin-spring-batch-dashboard

Setup

1. Add Plugin Routes

Edit packages/app/src/App.tsx:

import {
  SpringBatchPage,
  SpringBatchExecutionDetail,
  SpringBatchFailuresPage,
  SpringBatchRetryHistoryPage,
  SpringBatchJobInstancesPage,
  SpringBatchJobExecutionsPage,
  SpringBatchStepDetail,
} from '@jikwan/backstage-plugin-spring-batch-dashboard';

// Inside your <FlatRoutes> component:
<Route path="/spring-batch-dashboard" element={<SpringBatchPage />} />
<Route path="/spring-batch-dashboard/instances" element={<JobInstancesPage />} />
<Route path="/spring-batch-dashboard/executions" element={<JobExecutionsPage />} />
<Route path="/spring-batch-dashboard/failures" element={<FailuresPage />} />
<Route
  path="/spring-batch-dashboard/instances/:instanceId/history"
  element={<RetryHistoryPage />}
/>
<Route path="/spring-batch-dashboard/executions/:id" element={<ExecutionDetail />} />
<Route path="/spring-batch-dashboard/steps/:stepId" element={<StepDetail />} />

2. Add Sidebar Navigation

Edit packages/app/src/components/Root/Root.tsx:

import DashboardIcon from '@mui/icons-material/Dashboard';
import StorageIcon from '@mui/icons-material/Storage';
import PlaylistPlayIcon from '@mui/icons-material/PlaylistPlay';
import ErrorIcon from '@mui/icons-material/Error';

// Inside your sidebar:
<SidebarItem icon={DashboardIcon} to="spring-batch-dashboard" text="Spring Batch Dashboard">
  <SidebarSubmenu title="Spring Batch Dashboard">
    <SidebarSubmenuItem
      title="Dashboard"
      to="spring-batch-dashboard"
      icon={DashboardIcon}
    />
    <SidebarSubmenuItem
      title="Job Instances"
      to="spring-batch-dashboard/instances"
      icon={StorageIcon}
    />
    <SidebarSubmenuItem
      title="Job Executions"
      to="spring-batch-dashboard/executions"
      icon={PlaylistPlayIcon}
    />
    <SidebarSubmenuItem
      title="Failures"
      to="spring-batch-dashboard/failures"
      icon={ErrorIcon}
    />
  </SidebarSubmenu>
</SidebarItem>

3. Start Backstage

yarn dev

Navigate to http://localhost:3000/spring-batch-dashboard to see the dashboard.

Available Pages

Dashboard (/spring-batch-dashboard)

Main overview page with:

• Real-time job statistics (total, running, completed, failed)
• Status breakdown chart
• Recent executions table
• Quick filters by date range

Job Instances (/spring-batch-dashboard/instances)

List of all job instances with:

• Execution counts
• Last execution status and time
• Boot version (Boot3 or Boot4)
• Click to view retry history

Job Executions (/spring-batch-dashboard/executions)

Detailed execution list with:

• Advanced filtering (status, job name, date range, Boot version)
• Pagination support
• Execution duration
• Click to view execution details

Failures (/spring-batch-dashboard/failures)

Failed job executions with:

• Error messages and exit codes
• Step-level failure details
• Retry history access
• Quick troubleshooting

Execution Detail (/spring-batch-dashboard/executions/:id)

Detailed view of a single execution:

• Job parameters
• Step execution breakdown
• Timing information
• Read/write/skip counts
• Error messages

Step Detail (/spring-batch-dashboard/steps/:stepId)

Individual step execution details:

• Step-level metrics
• Commit/rollback counts
• Skip counts (read/write/process)
• Exit codes and messages

Retry History (/spring-batch-dashboard/instances/:instanceId/history)

Track job instance retry attempts:

• All executions for a job instance
• Chronological order
• Status progression
• Identify patterns in failures

Features in Detail

Environment Switching

Switch between different environments (dev, staging, production) using the environment selector at the top of each page. Available environments are dynamically loaded from the backend configuration.

// The plugin automatically fetches available environments from:
// GET /api/spring-batch-dashboard/environments

Boot Version Filtering

Filter executions by Spring Boot version (Boot 3 or Boot 4) to separate different application versions:

• Boot 3: Spring Boot 2.x / Spring Batch 5.x
• Boot 4: Spring Boot 3.x / Spring Batch 6.x

Date Range Selection

Use the date range picker for flexible time-based filtering:

• Quick select buttons (Last 7 days, Last 30 days, etc.)
• Custom date range picker
• Auto-refresh on date change

Component Customization

Custom Environment Labels

Override default environment labels by modifying the getEnvironmentLabel function:

// In your app/src/components/springBatch/customLabels.ts
export function getEnvironmentLabel(environment: string): string {
  const labelMap: Record<string, string> = {
    dev: 'Development',
    qa: 'Quality Assurance',
    'prd-virginia': 'Production (US-East)',
    'prd-seoul': 'Production (Asia)',
  };
  return labelMap[environment] || environment.toUpperCase();
}

Theming

The plugin uses Material-UI theming and respects your Backstage theme configuration. Customize colors in packages/app/src/theme:

// Example: Custom status colors
const theme = createTheme({
  palette: {
    success: { main: '#4caf50' },
    error: { main: '#f44336' },
    warning: { main: '#ff9800' },
  },
});

API Integration

The frontend plugin communicates with the backend via the SpringBatchClient:

import { useApi } from '@backstage/core-plugin-api';
import { springBatchApiRef } from '@jikwan/backstage-plugin-spring-batch-dashboard';

function MyComponent() {
  const api = useApi(springBatchApiRef);

  // Fetch statistics
  const stats = await api.getStatistics('production');

  // Fetch executions with filters
  const executions = await api.getExecutions({
    status: 'FAILED',
    limit: 50,
    offset: 0,
  }, 'production', 'Boot3');

  // Get execution details
  const execution = await api.getExecutionDetail(123, 'production', 'Boot3');
}

Available API Methods

See the SpringBatchClient class for all available methods:

class SpringBatchClient {
  getEnvironments(): Promise<{ environments: string[]; defaultEnvironment: string; }>
  getStatistics(environment?: Environment): Promise<JobStatistics>
  getExecutions(query?: JobExecutionQuery, environment?: Environment, bootVersion?: 'Boot3' | 'Boot4'): Promise<JobExecution[]>
  getExecutionDetail(id: number, environment?: Environment, bootVersion?: 'Boot3' | 'Boot4'): Promise<JobExecution>
  getStepDetail(id: number, environment?: Environment, bootVersion?: 'Boot3' | 'Boot4'): Promise<StepExecution>
  getJobs(environment?: Environment): Promise<JobInstance[]>
  getJobInstancesWithStats(environment?: Environment): Promise<JobInstanceWithStats[]>
  getJobExecutions(name: string, limit?: number): Promise<JobExecution[]>
  getJobExecutionsWithSteps(name: string, limit?: number): Promise<JobExecution[]>
  getDailyStatistics(date: string, environment?: Environment): Promise<DailyStatistics>
  getDailyJobSummaries(date: string, environment?: Environment): Promise<DailyJobSummary[]>
  getTrendData(fromDate: string, toDate: string, environment?: Environment): Promise<DailyTrendData[]>
  getJobInstanceExecutions(jobInstanceId: number, environment?: Environment, bootVersion?: 'Boot3' | 'Boot4'): Promise<JobExecution[]>
}

Development

Running Locally

# Install dependencies
yarn install

# Build the plugin
yarn workspace @jikwan/backstage-plugin-spring-batch-dashboard build

# Start Backstage in dev mode
yarn dev

Testing

# Run tests
yarn workspace @jikwan/backstage-plugin-spring-batch-dashboard test

# Run tests in watch mode
yarn workspace @jikwan/backstage-plugin-spring-batch-dashboard test --watch

# Run linter
yarn workspace @jikwan/backstage-plugin-spring-batch-dashboard lint

Building

# Build for production
yarn workspace @jikwan/backstage-plugin-spring-batch-dashboard build

# Clean build artifacts
yarn workspace @jikwan/backstage-plugin-spring-batch-dashboard clean

Troubleshooting

No Data Displayed

Issue: Dashboard shows no data or empty tables

Solutions:

1. Verify backend plugin is installed and running
2. Check browser console for API errors
3. Verify backend API is accessible:

   curl http://localhost:7007/api/spring-batch-dashboard/environments

4. Check backend configuration in app-config.yaml
5. Ensure database contains Spring Batch metadata

Environment Not Available

Issue: Environment selector shows only default environment

Solutions:

1. Check backend app-config.yaml has multiple environments configured
2. Verify backend API returns all environments:

   curl http://localhost:7007/api/spring-batch-dashboard/environments

3. Restart Backstage after config changes

Routing Issues

Issue: Navigation doesn't work or shows 404

Solutions:

1. Verify all routes are added to App.tsx
2. Check route paths match exactly (case-sensitive)
3. Ensure react-router-dom is installed
4. Clear browser cache and hard reload

Performance Issues

Issue: Slow page loads or laggy UI

Solutions:

1. Reduce page size limit (default is 50)
2. Add database indexes on backend (see backend README)
3. Use date range filters to limit data
4. Consider backend connection pooling configuration

Architecture

┌─────────────────────────────────────┐
│     Backstage Frontend (React)      │
├─────────────────────────────────────┤
│   Spring Batch Plugin (This)        │
│   - Dashboard UI                    │
│   - Execution List                  │
│   - Failure Analysis                │
│   - Retry History                   │
│   - SpringBatchClient (API)         │
└──────────────┬──────────────────────┘
               │ REST API
               ▼
┌─────────────────────────────────────┐
│   Spring Batch Backend Plugin       │
│   - REST Endpoints                  │
│   - Database Queries                │
│   - Multi-Environment Support       │
└──────────────┬──────────────────────┘
               │ SQL Queries
               ▼
┌─────────────────────────────────────┐
│      PostgreSQL Metadata DB         │
│   (Spring Batch Schema Tables)      │
└─────────────────────────────────────┘

Related Packages

This is the frontend plugin. For the complete monitoring solution, also install:

• @jikwan/backstage-plugin-spring-batch-dashboard-backend (Backend) - README
  • REST API endpoints
  • Database connections
  • Multi-environment support
  • Analytics queries

Technology Stack

• Frontend Framework: React 18.x
• UI Library: Material-UI (MUI) 6.x
• Routing: React Router v6
• State Management: React Hooks (useState, useEffect, useMemo)
• Backstage: 1.x Plugin API
• TypeScript: 5.x

Contributing

Contributions are welcome! Please follow the standard Backstage plugin development guidelines.

License

Apache-2.0

Support

For issues and questions:

• GitHub Issues: backstage-plugins/spring-batch
• Documentation: See /docs folder for detailed guides