gh-openshift-eng-ai-helpers-plugins-component-health/commands/summarize-jiras.md at master

zhongwei/gh-openshift-eng-ai-helpers-plugins-component-health

Files

Zhongwei Li 77cb91c246 Initial commit

2025-11-30 08:45:43 +08:00

11 KiB

Raw Permalink Blame History

description, argument-hint

description	argument-hint
Query and summarize JIRA bugs for a specific project with counts by component	--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

Verify Prerequisites: Check that Python 3 is installed
- Run: python3 --version
- Verify version 3.6 or later is available
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:
```
echo "JIRA_URL: ${JIRA_URL}"
echo "JIRA_PERSONAL_TOKEN: ${JIRA_PERSONAL_TOKEN:+***set***}"
```
- If missing, guide the user to set them:
```
export JIRA_URL="https://issues.redhat.com"
export JIRA_PERSONAL_TOKEN="your-token-here"
```
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)
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:
```
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
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
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
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
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

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.
Filter by specific component:
```
/component-health:summarize-jiras --project OCPBUGS --component "kube-apiserver"
```
Shows bug counts for only the kube-apiserver component.

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.

Include closed bugs:

/component-health:summarize-jiras --project OCPBUGS --include-closed --limit 500

Includes both open and closed bugs, fetching up to 500 issues.

Filter by status:

/component-health:summarize-jiras --project OCPBUGS --status New "In Progress" Verified

Shows only bugs in New, In Progress, or Verified status.

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

Python 3: Required to run the data fetching and summarization scripts
- Check: which python3
- Version: 3.6 or later
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
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

11 KiB Raw Permalink Blame History