zhongwei/gh-openshift-eng-ai-helpers-plugins-component-health
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:45:43 +08:00
commit 77cb91c246
25 changed files with 7424 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

383
commands/analyze.md Normal file
View File

@@ -0,0 +1,383 @@
---
description: Analyze and grade component health based on regression and JIRA bug metrics
argument-hint: <release> [--components comp1 comp2 ...] [--project JIRAPROJECT]
---
## Name
component-health:analyze
## Synopsis
```
/component-health:analyze <release> [--components comp1 comp2 ...] [--project JIRAPROJECT]
```
## Description
The `component-health:analyze` command provides comprehensive component health analysis for a specified OpenShift release by **automatically combining** regression management metrics with JIRA bug backlog data.
**CRITICAL**: This command REQUIRES and AUTOMATICALLY fetches BOTH data sources:
1. Regression data (via summarize-regressions)
2. JIRA bug data (via summarize-jiras)
The analysis is INCOMPLETE without both data sources. Both are fetched automatically without user prompting.
The command evaluates component health based on:
1. **Regression Management** (ALWAYS fetched automatically): How well components are managing test regressions
- Triage coverage (% of regressions triaged to JIRA bugs)
- Triage timeliness (average time from detection to triage)
- Resolution speed (average time from detection to closure)
2. **Bug Backlog Health** (ALWAYS fetched automatically): Current state of open bugs for components
- Open bug counts by component
- Bug age distribution
- Bug priority breakdown
- Recent bug flow (opened vs closed in last 30 days)
This command is useful for:
- **Grading overall component health** using multiple quality metrics
- **Identifying components** that need help with regression or bug management
- **Tracking quality trends** across releases
- **Generating comprehensive quality scorecards** for stakeholders
- **Prioritizing engineering investment** based on data-driven insights
Grading is subjective and not meant to be a critique of team performance. This is intended to help identify where help is needed and track progress as we improve our quality practices.
## Implementation
**CRITICAL WORKFLOW**: The analyze command MUST execute steps 3 and 4 (fetch regression data AND fetch JIRA data) automatically without waiting for user prompting. Both data sources are required for a complete analysis.
1. **Parse Arguments**: Extract release version and optional filters from arguments
- Release format: "X.Y" (e.g., "4.17", "4.21")
- Optional filters:
- `--components`: Space-separated list of component search strings (fuzzy match)
- `--project`: JIRA project key (default: "OCPBUGS")
2. **Resolve Component Names**: Use fuzzy matching to find actual component names
- Run list_components.py to get all available components:
```bash
python3 plugins/component-health/skills/list-components/list_components.py --release <release>
```
- If `--components` was provided:
- For each search string, find all components containing that string (case-insensitive)
- Combine all matches into a single list
- Remove duplicates
- If no matches found for a search string, warn the user and show available components
- If `--components` was NOT provided:
- Use all available components from the list
3. **Fetch Regression Summary**: REQUIRED - Always call the summarize-regressions command
**IMPORTANT**: This step is REQUIRED for the analyze command. Regression data must ALWAYS be fetched automatically without user prompting. The analyze command combines both regression and bug metrics - it is incomplete without both data sources.
- **ALWAYS execute this step** - do not skip or wait for user to request it
- Execute: `/component-health:summarize-regressions <release> [--components ...]`
- Pass resolved component names
- Extract regression metrics:
- Total regressions, triage percentages, timing metrics
- Per-component breakdowns
- Open vs closed regression counts
- Note development window dates for context
- If regression API is unreachable, inform the user and note this in the report but continue with bug-only analysis
4. **Fetch JIRA Bug Summary**: REQUIRED - Always call the summarize-jiras command
**IMPORTANT**: This step is REQUIRED for the analyze command. JIRA bug data must ALWAYS be fetched automatically without user prompting. The analyze command combines both regression and bug metrics - it is incomplete without both data sources.
- **ALWAYS execute this step** - do not skip or wait for user to request it
- For each resolved component name:
- Execute: `/component-health:summarize-jiras --project <project> --component "<component>" --limit 1000`
- Note: Must iterate over components because JIRA queries can be too large otherwise
- Aggregate bug metrics across all components:
- Total open bugs by component
- Bug age distribution
- Opened vs closed in last 30 days
- Priority breakdowns
- If JIRA authentication is not configured, inform the user and provide setup instructions
- If JIRA queries fail, note this in the report but continue with regression-only analysis
5. **Calculate Combined Health Grades**: REQUIRED - Analyze BOTH regression and bug data
**IMPORTANT**: This step requires data from BOTH step 3 (regressions) AND step 4 (JIRA bugs). Do not perform analysis with only one data source unless the other failed to fetch.
**For each component, grade based on:**
a. **Regression Health** (from step 3: summarize-regressions):
- Triage Coverage: % of regressions triaged
- 90-100%: Excellent ✅
- 70-89%: Good ⚠️
- 50-69%: Needs Improvement ⚠️
- <50%: Poor ❌
- Triage Timeliness: Average hours to triage
- <24 hours: Excellent ✅
- 24-72 hours: Good ⚠️
- 72-168 hours (1 week): Needs Improvement ⚠️
- >168 hours: Poor ❌
- Resolution Speed: Average hours to close
- <168 hours (1 week): Excellent ✅
- 168-336 hours (1-2 weeks): Good ⚠️
- 336-720 hours (2-4 weeks): Needs Improvement ⚠️
- >720 hours (4+ weeks): Poor ❌
b. **Bug Backlog Health** (from step 4: summarize-jiras):
- Open Bug Count: Total open bugs
- Component-relative thresholds (compare across components)
- Bug Age: Average/maximum age of open bugs
- <30 days average: Excellent ✅
- 30-90 days: Good ⚠️
- 90-180 days: Needs Improvement ⚠️
- >180 days: Poor ❌
- Bug Flow: Opened vs closed in last 30 days
- More closed than opened: Positive trend ✅
- Equal: Stable ⚠️
- More opened than closed: Growing backlog ❌
c. **Combined Health Score**: Weighted average of regression and bug health
- Weight regression health more heavily (e.g., 60%) as it's more actionable
- Bug backlog provides context (40%)
6. **Display Overall Health Report**: Present comprehensive analysis combining BOTH data sources
**IMPORTANT**: The report MUST include BOTH regression metrics AND JIRA bug metrics. Do not present regression-only analysis unless JIRA data fetch failed.
- Show which components were matched (if fuzzy search was used)
- Inform user that both regression and bug data were analyzed
**Section 1: Overall Release Health**
- Release version and development window
- Overall regression metrics (from summarize-regressions):
- Total regressions, triage %, timing metrics
- Overall bug metrics (from summarize-jiras):
- Total open bugs, opened/closed last 30 days, priority breakdown
- High-level combined health grade
**Section 2: Per-Component Health Scorecard**
- Ranked table of components from best to worst combined health
- Key metrics per component (BOTH regression AND bug data):
- Regression triage coverage
- Average triage time
- Average resolution time
- Open bug count (from JIRA)
- Bug age metrics (from JIRA)
- Bug flow (opened vs closed, from JIRA)
- Combined health grade
- Visual indicators (✅ ⚠️ ❌) for quick assessment
**Section 3: Components Needing Attention**
- Prioritized list of components with specific issues from BOTH sources
- Actionable recommendations for each component:
- "X open untriaged regressions need triage" (only OPEN, not closed)
- "High bug backlog: X open bugs (Y older than 90 days)" (from JIRA)
- "Growing bug backlog: +X net bugs in last 30 days" (from JIRA)
- "Slow regression triage: X hours average"
- Context for each issue
7. **Offer HTML Report Generation** (AFTER displaying the text report):
- Ask the user if they would like an interactive HTML report
- If yes, generate an HTML report combining both data sources
- Use template from: `plugins/component-health/skills/analyze-regressions/report_template.html`
- Enhance template to include bug backlog metrics
- Save report to: `.work/component-health-{release}/health-report.html`
- Open the report in the user's default browser
- Display the file path to the user
8. **Error Handling**: Handle common error scenarios
- Network connectivity issues
- Invalid release format
- Missing regression or JIRA data
- API errors
- No matches for component filter
- JIRA authentication issues
## Return Value
The command outputs a **Comprehensive Component Health Report**:
### Overall Health Grade
From combined regression and bug data:
- **Release**: OpenShift version and development window
- **Regression Metrics**:
- Total regressions: X (Y% triaged)
- Average triage time: X hours
- Average resolution time: X hours
- Open vs closed breakdown
- **Bug Backlog Metrics**:
- Total open bugs: X across all components
- Bugs opened/closed in last 30 days
- Priority distribution
- **Overall Health**: Combined grade (Excellent/Good/Needs Improvement/Poor)
### Per-Component Health Scorecard
Ranked table combining both metrics:
| Component | Regression Triage | Triage Time | Resolution Time | Open Bugs | Bug Age | Health Grade |
|-----------|-------------------|-------------|-----------------|-----------|---------|--------------|
| kube-apiserver | 100.0% | 58 hrs | 144 hrs | 15 | 45d avg | ✅ Excellent |
| etcd | 95.0% | 84 hrs | 192 hrs | 8 | 30d avg | ✅ Good |
| Monitoring | 86.7% | 68 hrs | 156 hrs | 23 | 120d avg | ⚠️ Needs Improvement |
### Components Needing Attention
Prioritized list with actionable items:
```
1. Monitoring (Needs Improvement):
- 1 open untriaged regression (needs triage)
- High bug backlog: 23 open bugs (8 older than 90 days)
- Growing backlog: +5 net bugs in last 30 days
- Recommendation: Focus on triaging open regression and addressing oldest bugs
2. Example-Component (Poor):
- 5 open untriaged regressions (urgent triage needed)
- Slow triage response: 120 hours average
- Very high bug backlog: 45 open bugs (15 older than 180 days)
- Recommendation: Immediate triage sprint needed; consider bug backlog cleanup initiative
```
**IMPORTANT**: When listing untriaged regressions:
- **Only list OPEN untriaged regressions** - these are actionable
- **Do NOT recommend triaging closed regressions** - tooling doesn't support retroactive triage
- Calculate actionable count as: `open.total - open.triaged`
### Additional Sections
If requested:
- Detailed regression metrics by component
- Detailed bug breakdowns by status and priority
- Links to Sippy dashboards for regression analysis
- Links to JIRA queries for bug investigation
- Trends compared to previous releases (if available)
## Examples
1. **Analyze overall component health for a release**:
```
/component-health:analyze 4.17
```
Automatically fetches and analyzes BOTH data sources for release 4.17:
- Regression management metrics (via summarize-regressions)
- JIRA bug backlog metrics (via summarize-jiras)
- Combined health grades based on both sources
- Prioritized recommendations using both regression and bug data
2. **Analyze specific components (exact match)**:
```
/component-health:analyze 4.21 --components Monitoring Etcd
```
Automatically fetches BOTH regression and bug data for Monitoring and Etcd:
- Compares combined health between the two components
- Shows regression metrics AND bug backlog for each
- Identifies which component needs more attention
- Provides targeted recommendations based on both data sources
3. **Analyze by fuzzy search**:
```
/component-health:analyze 4.21 --components network
```
Automatically fetches BOTH data sources for all components containing "network":
- Finds all networking components (e.g., "Networking / ovn-kubernetes", "Networking / DNS", etc.)
- Compares combined health across all networking components
- Shows regression metrics AND bug backlog for each
- Identifies networking-related quality issues from both sources
- Provides targeted recommendations
4. **Analyze with custom JIRA project**:
```
/component-health:analyze 4.21 --project OCPSTRAT
```
Analyzes health using bugs from OCPSTRAT project instead of default OCPBUGS.
5. **In-development release analysis**:
```
/component-health:analyze 4.21
```
Automatically fetches BOTH data sources for an in-development release:
- Shows current regression management state
- Shows current bug backlog state
- Tracks bug flow trends (opened vs closed)
- Identifies areas to focus on before GA based on both regression and bug metrics
## Arguments
- `$1` (required): Release version
- Format: "X.Y" (e.g., "4.17", "4.21")
- Must be a valid OpenShift release number
- `$2+` (optional): Filter flags
- `--components <search1> [search2 ...]`: Filter by component names using fuzzy search
- Space-separated list of component search strings
- Case-insensitive substring matching
- Each search string matches all components containing that substring
- If no components provided, all components are analyzed
- Applied to both regression and bug queries
- Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
- Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
- `--project <PROJECT>`: JIRA project key
- Default: "OCPBUGS"
- Use alternative project if component bugs are tracked elsewhere
- Examples: "OCPSTRAT", "OCPQE"
## Prerequisites
1. **Python 3**: Required to run the underlying data fetching scripts
- Check: `which python3`
- Version: 3.6 or later
2. **JIRA Authentication**: Environment variables must be configured for bug data
- `JIRA_URL`: Your JIRA instance URL
- `JIRA_PERSONAL_TOKEN`: Your JIRA bearer token or personal access token
- See `/component-health:summarize-jiras` for setup instructions
3. **Network Access**: Must be able to reach both component health API and JIRA
- Ensure HTTPS requests can be made to both services
- Check firewall and VPN settings if needed
## Notes
- **CRITICAL**: This command AUTOMATICALLY fetches data from TWO sources:
1. Regression API (via `/component-health:summarize-regressions`)
2. JIRA API (via `/component-health:summarize-jiras`)
- Both data sources are REQUIRED and fetched automatically without user prompting
- The analysis is incomplete without both regression and bug data
- Health grades are subjective and intended as guidance, not criticism
- Recommendations focus on actionable items (open untriaged regressions, not closed)
- Infrastructure regressions are automatically filtered from regression counts
- JIRA queries default to open bugs + bugs closed in last 30 days
- HTML reports provide interactive visualizations combining both data sources
- If one data source fails, the command continues with the available data and notes the failure
- For detailed regression data only, use `/component-health:list-regressions`
- For detailed JIRA data only, use `/component-health:list-jiras`
- This command provides the most comprehensive view by combining both sources
## See Also
- Related Command: `/component-health:summarize-regressions` (regression metrics)
- Related Command: `/component-health:summarize-jiras` (bug backlog metrics)
- Related Command: `/component-health:list-regressions` (raw regression data)
- Related Command: `/component-health:list-jiras` (raw JIRA data)
- Skill Documentation: `plugins/component-health/skills/analyze-regressions/SKILL.md`
- Script: `plugins/component-health/skills/list-regressions/list_regressions.py`
- Script: `plugins/component-health/skills/summarize-jiras/summarize_jiras.py`

147
commands/list-components.md Normal file
View File

@@ -0,0 +1,147 @@
---
description: List all components tracked in Sippy for a release
argument-hint: <release>
---
## Name
component-health:list-components
## Synopsis
```
/component-health:list-components <release>
```
## Description
The `component-health:list-components` command fetches and displays all component names tracked in the Sippy component readiness system for a specified OpenShift release.
This command is useful for:
- Discovering available components for a release
- Validating component names before analysis
- Understanding which teams/components are tracked
- Generating component lists for reports
- Finding exact component names for use in other commands
## Implementation
1. **Verify Prerequisites**: Check that Python 3 is installed
- Run: `python3 --version`
- Verify version 3.6 or later is available
2. **Parse Arguments**: Extract release version from arguments
- Release format: "X.Y" (e.g., "4.17", "4.21")
3. **Execute Python Script**: Run the list_components.py script
- Script location: `plugins/component-health/skills/list-components/list_components.py`
- Pass release as `--release` argument
- The script automatically appends "-main" suffix to construct the view
- Capture JSON output from stdout
4. **Parse Output**: Process the JSON response
- Extract component count and component list
- Components are returned alphabetically sorted and unique
5. **Present Results**: Display components in a readable format
- Show total count
- Display components in a numbered or bulleted list
- Optionally group by category (e.g., Networking, Storage, etc.)
6. **Error Handling**: Handle common error scenarios
- Network connectivity issues
- Invalid release format
- API errors (400, 404, 500, etc.)
- Empty results
## Return Value
The command outputs a **Component List** with the following information:
### Component Summary
- **Release**: The release version queried
- **View**: The constructed view parameter (release + "-main")
- **Total Components**: Count of unique components found
### Component List
An alphabetically sorted list of all components, for example:
```
1. Bare Metal Hardware Provisioning
2. Build
3. Cloud Compute / Cloud Controller Manager
4. Cluster Version Operator
5. Etcd
6. HyperShift
7. Image Registry
8. Installer / openshift-installer
9. kube-apiserver
10. Machine Config Operator
11. Management Console
12. Monitoring
13. Networking / ovn-kubernetes
14. OLM
15. Storage
...
```
## Examples
1. **List all components for release 4.21**:
```
/component-health:list-components 4.21
```
Displays all components tracked in Sippy for release 4.21.
2. **List components for release 4.20**:
```
/component-health:list-components 4.20
```
Displays all components for the 4.20 release.
## Arguments
- `$1` (required): Release version
- Format: "X.Y" (e.g., "4.17", "4.21")
- Must be a valid OpenShift release number
## Prerequisites
1. **Python 3**: Required to run the data fetching script
- Check: `which python3`
- Version: 3.6 or later
2. **Network Access**: Must be able to reach the Sippy API
- Ensure HTTPS requests can be made to `sippy.dptools.openshift.org`
## Notes
- The script automatically appends "-main" to the release version
- Component names are case-sensitive
- Component names are returned in alphabetical order
- Some components use hierarchical names with "/" separator (e.g., "Networking / ovn-kubernetes")
- The script has a 30-second timeout for HTTP requests
- Component names returned can be used directly in other component-health commands
## See Also
- Skill Documentation: `plugins/component-health/skills/list-components/SKILL.md`
- Script: `plugins/component-health/skills/list-components/list_components.py`
- Related Command: `/component-health:list-regressions` (for regression data)
- Related Command: `/component-health:summarize-jiras` (for bug data)
- Related Command: `/component-health:analyze` (for health analysis)

335
commands/list-jiras.md Normal file
View File

@@ -0,0 +1,335 @@
---
description: Query and list raw JIRA bug data for a specific project
argument-hint: <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]
---
## Name
component-health:list-jiras
## Synopsis
```
/component-health:list-jiras <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]
```
## Description
The `component-health:list-jiras` command queries JIRA bugs for a specified project and returns raw issue data. It fetches JIRA issues with all their fields and metadata without performing any summarization or aggregation.
By default, the command includes:
- All currently open bugs
- Bugs closed in the last 30 days (to track recent closure activity)
This command is useful for:
- Fetching raw JIRA issue data for further processing
- Accessing complete issue details including all fields
- Building custom analysis workflows
- Providing data to other commands (like `summarize-jiras`)
- Exporting JIRA data for offline analysis
## Implementation
1. **Verify Prerequisites**: Check that Python 3 is installed
- Run: `python3 --version`
- Verify version 3.6 or later is available
2. **Verify Environment Variables**: Ensure JIRA authentication is configured
- Check that the following environment variables are set:
- `JIRA_URL`: Base URL for JIRA instance (e.g., "https://issues.redhat.com")
- `JIRA_PERSONAL_TOKEN`: Your JIRA bearer token or personal access token
- Verify with:
```bash
echo "JIRA_URL: ${JIRA_URL}"
echo "JIRA_PERSONAL_TOKEN: ${JIRA_PERSONAL_TOKEN:+***set***}"
```
- If missing, guide the user to set them:
```bash
export JIRA_URL="https://issues.redhat.com"
export JIRA_PERSONAL_TOKEN="your-token-here"
```
3. **Parse Arguments**: Extract project key and optional filters from arguments
- Project key: Required first argument (e.g., "OCPBUGS", "OCPSTRAT")
- Optional filters:
- `--component`: Space-separated list of component search strings (fuzzy match)
- `--status`: Space-separated list of status values
- `--include-closed`: Flag to include closed bugs
- `--limit`: Maximum number of issues to fetch per component (default: 1000, max: 1000)
4. **Resolve Component Names** (if component filter provided): Use fuzzy matching to find actual component names
- Extract release from context or ask user for release version
- Run list_components.py to get all available components:
```bash
python3 plugins/component-health/skills/list-components/list_components.py --release <release>
```
- For each search string in `--component`:
- Find all components containing that string (case-insensitive)
- Combine all matches into a single list
- Remove duplicates
- If no matches found for a search string, warn the user and show available components
5. **Execute Python Script**: Run the list_jiras.py script for each component
- Script location: `plugins/component-health/skills/list-jiras/list_jiras.py`
- **Important**: Iterate over each resolved component separately to avoid overly large queries
- For each component:
- Build command with project, single component, and other filters
- Execute: `python3 list_jiras.py --project <project> --component "<component>" [other args]`
- Capture JSON output from stdout
- Aggregate results from all components into a combined response
6. **Parse Output**: Process the aggregated JSON response
- Extract metadata:
- `project`: Project key queried
- `total_count`: Total matching issues in JIRA
- `fetched_count`: Number of issues actually fetched
- `query`: JQL query that was executed
- `filters`: Applied filters
- Extract raw issues array:
- `issues`: Array of complete JIRA issue objects with all fields
7. **Present Results**: Display or store the raw JIRA data
- Show which components were matched (if fuzzy search was used)
- The command returns the aggregated JSON response with metadata and raw issues from all components
- Inform the user about total count vs fetched count per component
- The raw issue data can be passed to other commands for analysis
- Suggest using `/component-health:summarize-jiras` for summary statistics
- Highlight any truncation (if fetched_count < total_count for any component)
- Suggest increasing --limit if results are truncated
8. **Error Handling**: Handle common error scenarios
- Network connectivity issues
- Invalid JIRA credentials
- Invalid project key
- HTTP errors (401, 404, 500, etc.)
- Rate limiting (429)
## Return Value
The command outputs **raw JIRA issue data** in JSON format with the following structure:
### Metadata
- **project**: JIRA project key that was queried
- **total_count**: Total number of matching issues in JIRA
- **fetched_count**: Number of issues actually fetched (may be less than total if limited)
- **query**: JQL query that was executed (includes filters)
- **filters**: Object containing applied filters:
- `components`: List of component filters or null
- `statuses`: List of status filters or null
- `include_closed`: Boolean indicating if closed bugs were included
- `limit`: Maximum number of issues fetched
### Issues Array
- **issues**: Array of raw JIRA issue objects, each containing:
- `key`: Issue key (e.g., "OCPBUGS-12345")
- `fields`: Object containing all issue fields:
- `summary`: Issue title/summary
- `status`: Status object with name and ID
- `priority`: Priority object with name and ID
- `components`: Array of component objects
- `assignee`: Assignee object with user details
- `created`: Creation timestamp
- `updated`: Last updated timestamp
- `resolutiondate`: Resolution timestamp (if closed)
- `versions`: Affects Version/s array
- `fixVersions`: Fix Version/s array
- `customfield_12319940`: Target Version (custom field)
- And other JIRA fields as applicable
### Additional Information
- **note**: (Optional) If results are truncated, includes a note suggesting to increase the limit
- **component_queries**: (Optional) When multiple components are queried, this array shows the individual query executed for each component. Each entry contains:
- `component`: The component name
- `query`: The JQL query executed for this component
- `total_count`: Total matching issues for this component
- `fetched_count`: Number of issues fetched for this component
### Example Output Structure
```json
{
"project": "OCPBUGS",
"total_count": 1500,
"fetched_count": 100,
"query": "project = OCPBUGS AND (status != Closed OR (status = Closed AND resolved >= \"2025-10-11\"))",
"filters": {
"components": null,
"statuses": null,
"include_closed": false,
"limit": 100
},
"component_queries": [
{
"component": "kube-apiserver",
"query": "project = OCPBUGS AND component = \"kube-apiserver\" AND ...",
"total_count": 800,
"fetched_count": 50
},
{
"component": "kube-controller-manager",
"query": "project = OCPBUGS AND component = \"kube-controller-manager\" AND ...",
"total_count": 700,
"fetched_count": 50
}
],
"issues": [
{
"key": "OCPBUGS-12345",
"fields": {
"summary": "Bug title here",
"status": {"name": "New", "id": "1"},
"priority": {"name": "Major", "id": "3"},
"components": [{"name": "kube-apiserver"}],
"created": "2025-11-01T10:30:00.000+0000",
...
}
},
...
],
"note": "Showing first 100 of 1500 total results. Increase --limit for more data."
}
```
## Examples
1. **List all open bugs for a project**:
```
/component-health:list-jiras OCPBUGS
```
Fetches all open bugs in the OCPBUGS project (up to default limit of 1000) and returns raw issue data.
2. **Filter by specific component (exact match)**:
```
/component-health:list-jiras OCPBUGS --component "kube-apiserver"
```
Returns raw data for bugs in the kube-apiserver component only.
3. **Filter by fuzzy search**:
```
/component-health:list-jiras OCPBUGS --component network
```
Finds all components containing "network" (case-insensitive) and returns bugs for all matches (e.g., "Networking / ovn-kubernetes", "Networking / DNS", etc.).
Makes separate JIRA queries for each component and aggregates results.
4. **Filter by multiple search strings**:
```
/component-health:list-jiras OCPBUGS --component etcd kube-
```
Finds all components containing "etcd" OR "kube-" and returns combined bug data.
Iterates over each component separately to avoid overly large queries.
5. **Include closed bugs**:
```
/component-health:list-jiras OCPBUGS --include-closed --limit 500
```
Returns both open and closed bugs, fetching up to 500 issues per component.
6. **Filter by status**:
```
/component-health:list-jiras OCPBUGS --status New "In Progress" Verified
```
Returns only bugs in New, In Progress, or Verified status.
7. **Combine fuzzy search with other filters**:
```
/component-health:list-jiras OCPBUGS --component network --status New Assigned --limit 200
```
Returns bugs for all networking components that are in New or Assigned status.
## Arguments
- `$1` (required): JIRA project key
- Format: Project key in uppercase (e.g., "OCPBUGS", "OCPSTRAT")
- Must be a valid JIRA project you have access to
- `$2+` (optional): Filter flags
- `--component <search1> [search2 ...]`: Filter by component names using fuzzy search
- Space-separated list of component search strings
- Case-insensitive substring matching
- Each search string matches all components containing that substring
- Makes separate JIRA queries for each matched component to avoid overly large results
- Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
- Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
- Note: Requires release context (inferred from recent commands or specified by user)
- `--status <status1> [status2 ...]`: Filter by status values
- Space-separated list of status names
- Examples: `New`, `"In Progress"`, `Verified`, `Modified`, `ON_QA`
- `--include-closed`: Include closed bugs in results
- By default, only open bugs are returned
- When specified, closed bugs are included
- `--limit <N>`: Maximum number of issues to fetch per component
- Default: 1000
- Range: 1-1000
- When using component filters, this limit applies to each component separately
- Higher values provide more accurate statistics but slower performance
## Prerequisites
1. **Python 3**: Required to run the data fetching script
- Check: `which python3`
- Version: 3.6 or later
2. **JIRA Authentication**: Environment variables must be configured
- `JIRA_URL`: Your JIRA instance URL
- `JIRA_PERSONAL_TOKEN`: Your JIRA bearer token or personal access token
How to get a JIRA token:
- Navigate to JIRA → Profile → Personal Access Tokens
- Generate a new token with appropriate permissions
- Export it as an environment variable
3. **Network Access**: Must be able to reach your JIRA instance
- Ensure HTTPS requests can be made to JIRA_URL
- Check firewall and VPN settings if needed
## Notes
- The script uses Python's standard library only (no external dependencies)
- Output is JSON format for easy parsing and further processing
- Diagnostic messages are written to stderr, data to stdout
- The script has a 30-second timeout for HTTP requests
- For large projects, consider using component filters to reduce query size
- The returned data includes ALL JIRA fields for each issue, providing complete information
- If you need summary statistics, use `/component-health:summarize-jiras` instead
- If results show truncation, increase the --limit parameter to fetch more issues
## See Also
- Skill Documentation: `plugins/component-health/skills/list-jiras/SKILL.md`
- Script: `plugins/component-health/skills/list-jiras/list_jiras.py`
- Related Command: `/component-health:summarize-jiras` (for summary statistics)
- Related Command: `/component-health:analyze`

342
commands/list-regressions.md Normal file
View File

@@ -0,0 +1,342 @@
---
description: Fetch and list raw regression data for OpenShift releases
argument-hint: <release> [--components comp1 comp2 ...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
---
## Name
component-health:list-regressions
## Synopsis
```
/component-health:list-regressions <release> [--components comp1 comp2 ...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
```
## Description
The `component-health:list-regressions` command fetches regression data for a specified OpenShift release and returns raw regression details without performing any summarization or analysis. It provides complete regression information including test names, timestamps, triages, and metadata.
This command is useful for:
- Fetching raw regression data for further processing
- Accessing complete regression details for specific components
- Building custom analysis workflows
- Providing data to other commands (like `summarize-regressions` and `analyze`)
- Exporting regression data for offline analysis
- Investigating specific test failures across releases
## Implementation
1. **Verify Prerequisites**: Check that Python 3 is installed
- Run: `python3 --version`
- Verify version 3.6 or later is available
2. **Parse Arguments**: Extract release version and optional filters from arguments
- Release format: "X.Y" (e.g., "4.17", "4.21")
- Optional filters:
- `--components`: Space-separated list of component search strings (fuzzy match)
- `--start`: Start date for filtering (YYYY-MM-DD)
- `--end`: End date for filtering (YYYY-MM-DD)
- `--short`: Exclude regression arrays from output (only summaries)
3. **Resolve Component Names**: Use fuzzy matching to find actual component names
- Run list_components.py to get all available components:
```bash
python3 plugins/component-health/skills/list-components/list_components.py --release <release>
```
- If `--components` was provided:
- For each search string, find all components containing that string (case-insensitive)
- Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
- Combine all matches into a single list
- Remove duplicates
- If no matches found for a search string, warn the user and show available components
- If `--components` was NOT provided:
- Use all available components from the list
4. **Fetch Release Dates** (if date filtering needed): Run the get_release_dates.py script
- Script location: `plugins/component-health/skills/get-release-dates/get_release_dates.py`
- Pass release as `--release` argument
- Extract `development_start` and `ga` dates from JSON output
- Use these dates for `--start` and `--end` parameters if not explicitly provided
5. **Execute Python Script**: Run the list_regressions.py script
- Script location: `plugins/component-health/skills/list-regressions/list_regressions.py`
- Pass release as `--release` argument
- Pass resolved component names as `--components` argument
- Pass `--start` date if filtering by start date
- Pass `--end` date if filtering by end date
- Capture JSON output from stdout
6. **Parse Output**: Process the JSON response
- The script outputs JSON with the following structure:
- `summary`: Overall statistics (total, triaged, percentages, timing metrics)
- `components`: Dictionary mapping component names to regression data
- Each component has:
- `summary`: Component-specific statistics
- `open`: Array of open regression objects
- `closed`: Array of closed regression objects
- **Note**: When using `--short` flag, regression arrays are excluded (only summaries)
7. **Present Results**: Display or store the raw regression data
- Show which components were matched (if fuzzy search was used)
- The command returns the complete JSON response with metadata and raw regressions
- Inform the user about overall counts from the summary
- The raw regression data can be passed to other commands for analysis
- Suggest using `/component-health:summarize-regressions` for summary statistics
- Suggest using `/component-health:analyze` for health grading
8. **Error Handling**: Handle common error scenarios
- Network connectivity issues
- Invalid release format
- API errors (404, 500, etc.)
- Empty results
- No matches for component filter
## Return Value
The command outputs **raw regression data** in JSON format with the following structure:
### Overall Summary
- `summary.total`: Total number of regressions
- `summary.triaged`: Total number of regressions triaged to JIRA bugs
- `summary.triage_percentage`: Percentage of regressions that have been triaged
- `summary.filtered_suspected_infra_regressions`: Count of infrastructure regressions filtered
- `summary.time_to_triage_hrs_avg`: Average hours from opened to first triage
- `summary.time_to_triage_hrs_max`: Maximum hours from opened to first triage
- `summary.time_to_close_hrs_avg`: Average hours from opened to closed (closed only)
- `summary.time_to_close_hrs_max`: Maximum hours from opened to closed (closed only)
- `summary.open`: Summary statistics for open regressions
- `total`: Number of open regressions
- `triaged`: Number of open regressions triaged
- `triage_percentage`: Percentage of open regressions triaged
- `time_to_triage_hrs_avg`, `time_to_triage_hrs_max`: Triage timing metrics
- `open_hrs_avg`, `open_hrs_max`: How long regressions have been open
- `summary.closed`: Summary statistics for closed regressions
- `total`: Number of closed regressions
- `triaged`: Number of closed regressions triaged
- `triage_percentage`: Percentage of closed regressions triaged
- `time_to_triage_hrs_avg`, `time_to_triage_hrs_max`: Triage timing metrics
- `time_to_close_hrs_avg`, `time_to_close_hrs_max`: Time to close metrics
- `time_triaged_closed_hrs_avg`, `time_triaged_closed_hrs_max`: Time from triage to close
### Per-Component Data
- `components`: Dictionary mapping component names to objects containing:
- `summary`: Component-specific statistics (same structure as overall summary)
- `open`: Array of open regression objects
- `closed`: Array of closed regression objects
### Regression Object Structure
Each regression object (in `components.*.open` or `components.*.closed` arrays) contains:
- `id`: Unique regression identifier
- `view`: Release view (e.g., "4.21-main")
- `release`: Release version
- `base_release`: Base release for comparison
- `component`: Component name
- `capability`: Test capability/area
- `test_name`: Full test name
- `variants`: Array of test variants where regression occurred
- `opened`: Timestamp when regression was first detected
- `closed`: Timestamp when regression was closed (null if still open)
- `triages`: Array of triage objects (JIRA bugs linked to this regression)
- Each triage has `jira_key`, `created_at`, `url` fields
- `last_failure`: Timestamp of most recent test failure
- `max_failures`: Maximum number of failures detected
### Example Output Structure
```json
{
"summary": {
"total": 62,
"triaged": 59,
"triage_percentage": 95.2,
"filtered_suspected_infra_regressions": 8,
"time_to_triage_hrs_avg": 68,
"time_to_triage_hrs_max": 240,
"time_to_close_hrs_avg": 168,
"time_to_close_hrs_max": 480,
"open": { "total": 2, "triaged": 1, ... },
"closed": { "total": 60, "triaged": 58, ... }
},
"components": {
"Monitoring": {
"summary": {
"total": 15,
"triaged": 13,
"triage_percentage": 86.7,
...
},
"open": [
{
"id": 12894,
"component": "Monitoring",
"test_name": "[sig-instrumentation] Prometheus ...",
"opened": "2025-10-15T10:30:00Z",
"closed": null,
"triages": [],
...
}
],
"closed": [...]
},
"etcd": {
"summary": { "total": 20, "triaged": 19, ... },
"open": [],
"closed": [...]
}
}
}
```
**Note**: When using `--short` flag, the `open` and `closed` arrays are excluded from component objects to reduce response size.
## Examples
1. **List all regressions for a release**:
```
/component-health:list-regressions 4.17
```
Fetches all regression data for release 4.17, including all components.
2. **Filter by specific component (exact match)**:
```
/component-health:list-regressions 4.21 --components Monitoring
```
Returns regression data for only the Monitoring component.
3. **Filter by fuzzy search**:
```
/component-health:list-regressions 4.21 --components network
```
Finds all components containing "network" (case-insensitive):
- Networking / ovn-kubernetes
- Networking / DNS
- Networking / router
- Networking / cluster-network-operator
- ... and returns regression data for all matches
4. **Filter by multiple search strings**:
```
/component-health:list-regressions 4.21 --components etcd kube-
```
Finds all components containing "etcd" OR "kube-":
- Etcd
- kube-apiserver
- kube-controller-manager
- kube-scheduler
- kube-storage-version-migrator
5. **Filter by development window** (GA'd release):
```
/component-health:list-regressions 4.17 --start 2024-05-17 --end 2024-10-29
```
Fetches regressions within the development window:
- Excludes regressions closed before 2024-05-17
- Excludes regressions opened after 2024-10-29
6. **Filter for in-development release**:
```
/component-health:list-regressions 4.21 --start 2025-09-02
```
Fetches regressions for an in-development release:
- Excludes regressions closed before development started
- No end date (release still in development)
7. **Combine fuzzy component search and date filters**:
```
/component-health:list-regressions 4.21 --components network --start 2025-09-02
```
Returns regressions for all networking components from the development window.
## Arguments
- `$1` (required): Release version
- Format: "X.Y" (e.g., "4.17", "4.21")
- Must be a valid OpenShift release number
- `$2+` (optional): Filter flags
- `--components <search1> [search2 ...]`: Filter by component names using fuzzy search
- Space-separated list of component search strings
- Case-insensitive substring matching
- Each search string matches all components containing that substring
- If no components provided, all components are analyzed
- Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
- Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
- `--start <YYYY-MM-DD>`: Filter regressions by start date
- Excludes regressions closed before this date
- Typically the development_start date from release metadata
- `--end <YYYY-MM-DD>`: Filter regressions by end date
- Excludes regressions opened after this date
- Typically the GA date for released versions
- Omit for in-development releases
- `--short`: Exclude regression arrays from output
- Only include summary statistics
- Significantly reduces response size for large datasets
- Use when you only need counts and metrics, not individual regressions
## Prerequisites
1. **Python 3**: Required to run the data fetching script
- Check: `which python3`
- Version: 3.6 or later
2. **Network Access**: Must be able to reach the component health API
- Ensure HTTPS requests can be made
- Check firewall and VPN settings if needed
3. **API Configuration**: The API endpoint must be configured in the script
- Location: `plugins/component-health/skills/list-regressions/list_regressions.py`
- The script should have the correct API base URL
## Notes
- The script uses Python's standard library only (no external dependencies)
- Output is JSON format for easy parsing and further processing
- Diagnostic messages are written to stderr, data to stdout
- The script has a 30-second timeout for HTTP requests
- For large result sets, consider using component filters or the `--short` flag
- Date filtering helps focus on relevant regressions within the development window
- Infrastructure regressions (closed quickly on high-volume days) are automatically filtered
- The returned data includes complete regression information, not summaries
- If you need summary statistics, use `/component-health:summarize-regressions` instead
- If you need health grading, use `/component-health:analyze` instead
## See Also
- Skill Documentation: `plugins/component-health/skills/list-regressions/SKILL.md`
- Script: `plugins/component-health/skills/list-regressions/list_regressions.py`
- Related Command: `/component-health:summarize-regressions` (for summary statistics)
- Related Command: `/component-health:analyze` (for health grading and analysis)
- Related Skill: `get-release-dates` (for fetching development window dates)

302
commands/summarize-jiras.md Normal file
View File

@@ -0,0 +1,302 @@
---
description: Query and summarize JIRA bugs for a specific project with counts by component
argument-hint: --project <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]
---
## Name
component-health:summarize-jiras
## Synopsis
```
/component-health:summarize-jiras --project <project> [--component comp1 comp2 ...] [--status status1 status2 ...] [--include-closed] [--limit N]
```
## Description
The `component-health:summarize-jiras` command queries JIRA bugs for a specified project and generates summary statistics. It leverages the `list-jiras` command to fetch raw JIRA data and then calculates counts by status, priority, and component to help understand the bug backlog at a glance.
By default, the command includes:
- All currently open bugs
- Bugs closed in the last 30 days (to track recent closure activity)
This command is useful for:
- Getting a quick count of open bugs in a JIRA project
- Analyzing bug distribution by status, priority, or component
- Tracking recent bug flow (opened vs closed in last 30 days)
- Generating summary reports for bug backlog
- Monitoring bug velocity and closure rates by component
- Comparing bug counts across different components
## Implementation
1. **Verify Prerequisites**: Check that Python 3 is installed
- Run: `python3 --version`
- Verify version 3.6 or later is available
2. **Verify Environment Variables**: Ensure JIRA authentication is configured
- Check that the following environment variables are set:
- `JIRA_URL`: Base URL for JIRA instance (e.g., "https://issues.redhat.com")
- `JIRA_PERSONAL_TOKEN`: Your JIRA bearer token or personal access token
- Verify with:
```bash
echo "JIRA_URL: ${JIRA_URL}"
echo "JIRA_PERSONAL_TOKEN: ${JIRA_PERSONAL_TOKEN:+***set***}"
```
- If missing, guide the user to set them:
```bash
export JIRA_URL="https://issues.redhat.com"
export JIRA_PERSONAL_TOKEN="your-token-here"
```
3. **Parse Arguments**: Extract project key and optional filters from arguments
- Project key: Required `--project` flag (e.g., "OCPBUGS", "OCPSTRAT")
- Optional filters:
- `--component`: Space-separated list of component search strings (fuzzy match)
- `--status`: Space-separated list of status values
- `--include-closed`: Flag to include closed bugs
- `--limit`: Maximum number of issues to fetch per component (default: 1000, max: 1000)
4. **Resolve Component Names** (if component filter provided): Use fuzzy matching to find actual component names
- Extract release from context or ask user for release version
- Run list_components.py to get all available components:
```bash
python3 plugins/component-health/skills/list-components/list_components.py --release <release>
```
- For each search string in `--component`:
- Find all components containing that string (case-insensitive)
- Combine all matches into a single list
- Remove duplicates
- If no matches found for a search string, warn the user and show available components
5. **Execute Python Script**: Run the summarize_jiras.py script for each component
- Script location: `plugins/component-health/skills/summarize-jiras/summarize_jiras.py`
- The script internally calls `list_jiras.py` to fetch raw data
- **Important**: Iterate over each resolved component separately to avoid overly large queries
- For each component:
- Build command with project, single component, and other filters
- Execute: `python3 summarize_jiras.py --project <project> --component "<component>" [other args]`
- Capture JSON output from stdout
- Aggregate summary statistics from all components into a combined response
6. **Parse Output**: Process the aggregated JSON response
- Extract summary statistics:
- `total_count`: Total matching issues in JIRA
- `fetched_count`: Number of issues actually fetched
- `summary.by_status`: Count of issues per status
- `summary.by_priority`: Count of issues per priority
- `summary.by_component`: Count of issues per component
- Extract per-component breakdowns:
- Each component has its own counts by status and priority
- Includes opened/closed in last 30 days per component
7. **Present Results**: Display summary in a clear format
- Show which components were matched (if fuzzy search was used)
- Show total bug count across all components
- Display status breakdown (e.g., New, In Progress, Verified, etc.)
- Display priority breakdown (Critical, Major, Normal, Minor, etc.)
- Display component distribution
- Show per-component breakdowns with status and priority counts
- Highlight any truncation (if fetched_count < total_count for any component)
- Suggest increasing --limit if results are truncated
8. **Error Handling**: Handle common error scenarios
- Network connectivity issues
- Invalid JIRA credentials
- Invalid project key
- HTTP errors (401, 404, 500, etc.)
- Rate limiting (429)
## Return Value
The command outputs a **JIRA Bug Summary** with the following information:
### Project Overview
- **Project**: JIRA project key
- **Total Count**: Total number of matching bugs (open + recently closed)
- **Query**: JQL query that was executed (includes 30-day closed bug filter)
- **Fetched Count**: Number of bugs actually fetched (may be less than total if limited)
### Summary Statistics
**Overall Metrics**:
- Total bugs fetched
- Bugs opened in last 30 days
- Bugs closed in last 30 days
**By Status**: Count of bugs in each status (includes recently closed)
| Status | Count |
|--------|-------|
| New | X |
| In Progress | X |
| Verified | X |
| Closed | X |
| ... | ... |
**By Priority**: Count of bugs by priority level
| Priority | Count |
|----------|-------|
| Critical | X |
| Major | X |
| Normal | X |
| Minor | X |
| Undefined | X |
**By Component**: Count of bugs per component
| Component | Count |
|-----------|-------|
| kube-apiserver | X |
| Management Console | X |
| Networking | X |
| ... | ... |
### Per-Component Breakdown
For each component:
- **Total**: Number of bugs assigned to this component
- **Opened (30d)**: Bugs created in the last 30 days
- **Closed (30d)**: Bugs closed in the last 30 days
- **By Status**: Status distribution for this component
- **By Priority**: Priority distribution for this component
### Additional Information
- **Filters Applied**: Lists any component, status, or other filters used
- **Note**: If results are truncated, suggests increasing the limit
- **Query Scope**: By default includes open bugs and bugs closed in the last 30 days
## Examples
1. **Summarize all open bugs for a project**:
```
/component-health:summarize-jiras --project OCPBUGS
```
Fetches all open bugs in the OCPBUGS project (up to default limit of 1000) and displays summary statistics.
2. **Filter by specific component**:
```
/component-health:summarize-jiras --project OCPBUGS --component "kube-apiserver"
```
Shows bug counts for only the kube-apiserver component.
3. **Filter by multiple components**:
```
/component-health:summarize-jiras --project OCPBUGS --component "kube-apiserver" "etcd" "Networking"
```
Shows bug counts for kube-apiserver, etcd, and Networking components.
4. **Include closed bugs**:
```
/component-health:summarize-jiras --project OCPBUGS --include-closed --limit 500
```
Includes both open and closed bugs, fetching up to 500 issues.
5. **Filter by status**:
```
/component-health:summarize-jiras --project OCPBUGS --status New "In Progress" Verified
```
Shows only bugs in New, In Progress, or Verified status.
6. **Combine multiple filters**:
```
/component-health:summarize-jiras --project OCPBUGS --component "Management Console" --status New Assigned --limit 200
```
Shows bugs for Management Console component that are in New or Assigned status.
## Arguments
- `--project <project>` (required): JIRA project key
- Format: Project key in uppercase (e.g., "OCPBUGS", "OCPSTRAT")
- Must be a valid JIRA project you have access to
- Additional optional flags:
- `--component <search1> [search2 ...]`: Filter by component names using fuzzy search
- Space-separated list of component search strings
- Case-insensitive substring matching
- Each search string matches all components containing that substring
- Makes separate JIRA queries for each matched component to avoid overly large results
- Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
- Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
- Note: Requires release context (inferred from recent commands or specified by user)
- `--status <status1> [status2 ...]`: Filter by status values
- Space-separated list of status names
- Examples: `New`, `"In Progress"`, `Verified`, `Modified`, `ON_QA`
- `--include-closed`: Include closed bugs in results
- By default, only open bugs are returned
- When specified, closed bugs are included
- `--limit <N>`: Maximum number of issues to fetch per component
- Default: 1000
- Range: 1-1000
- When using component filters, this limit applies to each component separately
- Higher values provide more accurate statistics but slower performance
## Prerequisites
1. **Python 3**: Required to run the data fetching and summarization scripts
- Check: `which python3`
- Version: 3.6 or later
2. **JIRA Authentication**: Environment variables must be configured
- `JIRA_URL`: Your JIRA instance URL
- `JIRA_PERSONAL_TOKEN`: Your JIRA bearer token or personal access token
How to get a JIRA token:
- Navigate to JIRA → Profile → Personal Access Tokens
- Generate a new token with appropriate permissions
- Export it as an environment variable
3. **Network Access**: Must be able to reach your JIRA instance
- Ensure HTTPS requests can be made to JIRA_URL
- Check firewall and VPN settings if needed
## Notes
- The script uses Python's standard library only (no external dependencies)
- Output is JSON format for easy parsing
- Diagnostic messages are written to stderr, data to stdout
- The script has a 30-second timeout for HTTP requests
- For large projects, consider using component filters to reduce query size
- Summary statistics are based on fetched issues (controlled by --limit), not total matching issues
- If results show truncation, increase the --limit parameter for more accurate statistics
- This command internally uses `/component-health:list-jiras` to fetch raw data
## See Also
- Skill Documentation: `plugins/component-health/skills/summarize-jiras/SKILL.md`
- Script: `plugins/component-health/skills/summarize-jiras/summarize_jiras.py`
- Related Command: `/component-health:list-jiras` (for raw JIRA data)
- Related Command: `/component-health:analyze`

285
commands/summarize-regressions.md Normal file
View File

@@ -0,0 +1,285 @@
---
description: Query and summarize regression data for OpenShift releases with counts and metrics
argument-hint: <release> [--components comp1 comp2 ...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
---
## Name
component-health:summarize-regressions
## Synopsis
```
/component-health:summarize-regressions <release> [--components comp1 comp2 ...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
```
## Description
The `component-health:summarize-regressions` command queries regression data for a specified OpenShift release and generates summary statistics. It leverages the `list-regressions` command to fetch raw regression data and then presents counts, percentages, and timing metrics to help understand regression trends at a glance.
By default, the command analyzes:
- All regressions within the release development window
- Both open and closed regressions
- Triage coverage and timing metrics
- Per-component breakdowns
This command is useful for:
- Getting a quick count of regressions in a release
- Analyzing regression distribution by component
- Tracking triage coverage and response times
- Generating summary reports for regression management
- Monitoring regression resolution speed by component
- Comparing regression metrics across different components
- Understanding open vs closed regression breakdown
## Implementation
1. **Verify Prerequisites**: Check that Python 3 is installed
- Run: `python3 --version`
- Verify version 3.6 or later is available
2. **Parse Arguments**: Extract release version and optional filters from arguments
- Release format: "X.Y" (e.g., "4.17", "4.21")
- Optional filters:
- `--components`: Space-separated list of component search strings (fuzzy match)
- `--start`: Start date for filtering (YYYY-MM-DD)
- `--end`: End date for filtering (YYYY-MM-DD)
3. **Resolve Component Names**: Use fuzzy matching to find actual component names
- Run list_components.py to get all available components:
```bash
python3 plugins/component-health/skills/list-components/list_components.py --release <release>
```
- If `--components` was provided:
- For each search string, find all components containing that string (case-insensitive)
- Combine all matches into a single list
- Remove duplicates
- If no matches found for a search string, warn the user and show available components
- If `--components` was NOT provided:
- Use all available components from the list
4. **Fetch Release Dates**: Run the get_release_dates.py script to get development window dates
- Script location: `plugins/component-health/skills/get-release-dates/get_release_dates.py`
- Pass release as `--release` argument
- Extract `development_start` and `ga` dates from JSON output
- Convert timestamps to simple date format (YYYY-MM-DD)
- Use these dates if `--start` and `--end` are not explicitly provided
5. **Execute Python Script**: Run the list_regressions.py script with appropriate arguments
- Script location: `plugins/component-health/skills/list-regressions/list_regressions.py`
- Pass release as `--release` argument
- Pass resolved component names as `--components` argument
- Pass `development_start` date as `--start` argument (if available)
- Always applied (for both GA'd and in-development releases)
- Excludes regressions closed before development started
- Pass `ga` date as `--end` argument (only if GA date is not null)
- Only applied for GA'd releases
- Excludes regressions opened after GA
- For in-development releases (null GA date), no end date filtering is applied
- **Always pass `--short` flag** to exclude regression arrays (only summaries)
6. **Parse Output**: Process the JSON output from the script
- Script writes JSON to stdout with summary structure:
- `summary`: Overall statistics (total, triaged, percentages, timing)
- `components`: Per-component summary statistics
- **ALWAYS use the summary fields** for counts and metrics
- Regression arrays are not included (due to `--short` flag)
7. **Present Results**: Display summary in a clear, readable format
- Show which components were matched (if fuzzy search was used)
- Show overall summary statistics
- Display per-component breakdowns
- Highlight key metrics:
- Triage coverage percentages
- Average time to triage
- Average time to close (for closed regressions)
- Open vs closed counts
- Present data in tables or structured format
- Note any date filtering applied
8. **Error Handling**: Handle common error scenarios
- Network connectivity issues
- Invalid release format
- API errors (404, 500, etc.)
- Empty results
- No matches for component filter
- Release dates not found
## Return Value
The command outputs a **Regression Summary Report** with the following information:
### Overall Summary
- **Release**: OpenShift release version
- **Development Window**: Start and end dates (or "In Development" if no GA date)
- **Total Regressions**: `summary.total`
- **Filtered Infrastructure Regressions**: `summary.filtered_suspected_infra_regressions`
- **Triaged**: `summary.triaged` regressions (`summary.triage_percentage`%)
- **Open**: `summary.open.total` regressions (`summary.open.triage_percentage`% triaged)
- **Closed**: `summary.closed.total` regressions (`summary.closed.triage_percentage`% triaged)
### Timing Metrics
**Overall Metrics**:
- **Average Time to Triage**: `summary.time_to_triage_hrs_avg` hours
- **Maximum Time to Triage**: `summary.time_to_triage_hrs_max` hours
- **Average Time to Close**: `summary.time_to_close_hrs_avg` hours (closed regressions only)
- **Maximum Time to Close**: `summary.time_to_close_hrs_max` hours (closed regressions only)
**Open Regression Metrics**:
- **Average Open Duration**: `summary.open.open_hrs_avg` hours
- **Maximum Open Duration**: `summary.open.open_hrs_max` hours
- **Average Time to Triage** (open): `summary.open.time_to_triage_hrs_avg` hours
- **Maximum Time to Triage** (open): `summary.open.time_to_triage_hrs_max` hours
**Closed Regression Metrics**:
- **Average Time to Close**: `summary.closed.time_to_close_hrs_avg` hours
- **Maximum Time to Close**: `summary.closed.time_to_close_hrs_max` hours
- **Average Time to Triage** (closed): `summary.closed.time_to_triage_hrs_avg` hours
- **Maximum Time to Triage** (closed): `summary.closed.time_to_triage_hrs_max` hours
- **Average Triage-to-Close Time**: `summary.closed.time_triaged_closed_hrs_avg` hours
- **Maximum Triage-to-Close Time**: `summary.closed.time_triaged_closed_hrs_max` hours
### Per-Component Summary
For each component (from `components.*.summary`):
| Component | Total | Open | Closed | Triaged | Triage % | Avg Time to Triage | Avg Time to Close |
|-----------|-------|------|--------|---------|----------|--------------------|-------------------|
| Monitoring | 15 | 1 | 14 | 13 | 86.7% | 68 hrs | 156 hrs |
| etcd | 20 | 0 | 20 | 19 | 95.0% | 84 hrs | 192 hrs |
| kube-apiserver | 27 | 1 | 26 | 27 | 100.0% | 58 hrs | 144 hrs |
### Additional Information
- **Filters Applied**: Lists any component or date filters used
- **Data Scope**: Notes which regressions are included based on date filtering
- For GA'd releases: Regressions within development window (start to GA)
- For in-development releases: Regressions from development start onwards
## Examples
1. **Summarize all regressions for a release**:
```
/component-health:summarize-regressions 4.17
```
Fetches and summarizes all regressions for release 4.17, automatically applying development window date filtering.
2. **Filter by specific component (exact match)**:
```
/component-health:summarize-regressions 4.21 --components Monitoring
```
Shows summary statistics for only the Monitoring component in release 4.21.
3. **Filter by fuzzy search**:
```
/component-health:summarize-regressions 4.21 --components network
```
Finds all components containing "network" (case-insensitive) and shows summary statistics for all matches (e.g., "Networking / ovn-kubernetes", "Networking / DNS", etc.).
4. **Filter by multiple search strings**:
```
/component-health:summarize-regressions 4.21 --components etcd kube-
```
Finds all components containing "etcd" OR "kube-" and shows combined summary statistics.
5. **Specify custom date range**:
```
/component-health:summarize-regressions 4.17 --start 2024-05-17 --end 2024-10-29
```
Summarizes regressions within a specific date range:
- Excludes regressions closed before 2024-05-17
- Excludes regressions opened after 2024-10-29
6. **In-development release**:
```
/component-health:summarize-regressions 4.21
```
Summarizes regressions for an in-development release:
- Automatically fetches development_start date
- No end date filtering (release not yet GA'd)
- Shows current state of regression management
## Arguments
- `$1` (required): Release version
- Format: "X.Y" (e.g., "4.17", "4.21")
- Must be a valid OpenShift release number
- `$2+` (optional): Filter flags
- `--components <search1> [search2 ...]`: Filter by component names using fuzzy search
- Space-separated list of component search strings
- Case-insensitive substring matching
- Each search string matches all components containing that substring
- If no components provided, all components are analyzed
- Example: "network" matches "Networking / ovn-kubernetes", "Networking / DNS", etc.
- Example: "kube-" matches "kube-apiserver", "kube-controller-manager", etc.
- `--start <YYYY-MM-DD>`: Filter by start date
- Excludes regressions closed before this date
- Defaults to development_start from release metadata if not provided
- `--end <YYYY-MM-DD>`: Filter by end date
- Excludes regressions opened after this date
- Defaults to GA date from release metadata if not provided and release is GA'd
- Omitted for in-development releases
## Prerequisites
1. **Python 3**: Required to run the data fetching script
- Check: `which python3`
- Version: 3.6 or later
2. **Network Access**: Must be able to reach the component health API
- Ensure HTTPS requests can be made
- Check firewall and VPN settings if needed
3. **API Configuration**: The API endpoint must be configured in the script
- Location: `plugins/component-health/skills/list-regressions/list_regressions.py`
- The script should have the correct API base URL
## Notes
- The script uses Python's standard library only (no external dependencies)
- Output presents summary statistics in a readable format
- Diagnostic messages are written to stderr
- The script has a 30-second timeout for HTTP requests
- Summary statistics are based on all matching regressions (not limited by pagination)
- The `--short` flag is always used internally to optimize performance
- Infrastructure regressions are automatically filtered from counts
- Date filtering focuses analysis on the development window for accuracy
- This command internally uses `/component-health:list-regressions` to fetch data
- For raw regression data, use `/component-health:list-regressions` instead
- For health grading and analysis, use `/component-health:analyze` instead
## See Also
- Skill Documentation: `plugins/component-health/skills/list-regressions/SKILL.md`
- Script: `plugins/component-health/skills/list-regressions/list_regressions.py`
- Related Command: `/component-health:list-regressions` (for raw regression data)
- Related Command: `/component-health:analyze` (for health grading and analysis)
- Related Skill: `get-release-dates` (for fetching development window dates)