Enhance --breakout with multiple values and regex patterns (fixes #110)

[atheurer]

Summary

This PR enhances the --breakout option in get-metric-data.js with support for multiple values and regex pattern matching, addressing issue #110.

Features Implemented

1. Multiple Literal Values

Syntax: --breakout hostname=a,b,c
Result: Returns separate metrics for each value
Use Case: Compare specific hosts or components

2. Regex Pattern Matching

Syntax:

• --breakout hostname=r/pattern/ → Separate metrics per match
• --breakout hostname=R/pattern/ → Aggregated metric for all matches

Features:

• Custom delimiters: Use r|pattern| when pattern contains /
• Regex alternation for specific values: R/worker-1|worker-2|worker-3/
• Consistent lowercase/uppercase convention

3. Enhanced Error Handling

Feature: Clear error messages when filters match nothing
Benefit: Actionable feedback instead of cryptic errors

Complete Syntax Matrix

Syntax	Type	Result	Use Case
hostname=a	Single literal	1 metric for 'a'	Query specific host
hostname=a,b,c	Multiple literals	3 separate metrics	Compare specific hosts
hostname=r/pattern/	Regex separate	N separate metrics	Compare all matching
hostname=R/pattern/	Regex aggregated	1 combined metric	Total of all matching
hostname=R/a|b|c/	Regex alternation	1 combined metric	Aggregate specific values
hostname	No filter	All values (separate)	Explore all options

Design Philosophy

The implementation uses a consistent, intuitive syntax pattern:

• Lowercase r = Separate/individual metrics
• Uppercase R = Aggregated/combined metrics

This provides maximum flexibility while maintaining a clean, learnable interface.

Example Usage

# Multiple literal values - separate metrics
node ./get-metric-data.js --period <UUID> --source sar-net --type L2-Gbps \
  --breakout csid=1,2,cstype=worker

# Regex with separate metrics per match
node ./get-metric-data.js --period <UUID> --source mpstat --type Busy-CPU \
  --breakout hostname=r/^worker-.*/

# Regex with aggregated metric for all matches
node ./get-metric-data.js --period <UUID> --source sar-net --type L2-Gbps \
  --breakout hostname=R/^client-.*/

# Aggregate specific values using regex alternation
node ./get-metric-data.js --period <UUID> --source mpstat --type Busy-CPU \
  --breakout hostname=R/worker-1|worker-2|worker-3/

# Custom delimiter when pattern contains slashes
node ./get-metric-data.js --period <UUID> --source iostat --type kB-sec \
  --breakout dev=r|/dev/sd.*|

# Mix different filter types
node ./get-metric-data.js --period <UUID> --source mpstat --type Busy-CPU \
  --breakout hostname=r/worker-[0-9]+/,cstype=physical

Use Cases

Separate Metrics (, or r/):

• Compare performance across specific hosts
• Identify outliers or problem nodes
• Generate per-host charts and reports

Aggregated Metrics (R/):

• Measure total throughput across a cluster: R/^worker-.*/
• Aggregate specific hosts: R/worker-1|worker-2|worker-3/
• Calculate combined CPU usage of worker nodes
• Aggregate network traffic: R/eth0|eth1/

Technical Implementation

• Parsing: Smart detection of separators in list() function
• Query: Uses OpenSearch terms filter for multiple values, regexp for patterns
• Aggregation: Controlled by excluding fields from nested aggregation structure
• Error Handling: Detects empty results and provides actionable feedback
• Documentation: Comprehensive guide with examples and feature matrix

Backward Compatibility

✅ Fully backward compatible - all existing usage patterns work unchanged

Testing

• Code follows existing patterns
• Comprehensive documentation with examples
• Error handling tested with non-matching filters
• Feature matrix documents all syntax options
• Maintains backward compatibility
• Regex alternation tested for aggregating specific values
• R/pattern/ filtering tested and verified

Commits

1. c879aea - Add support for multiple values in --breakout option
2. 54b29df - Add regex pattern support for breakout filters
3. 217d77e - Add helpful error message when regex filter matches nothing
4. 054ae2e - Revert aggregated literal values (use regex alternation instead)
5. c8ac61c - Update documentation for regex alternation approach
6. 0f8c0c9 - Fix R/pattern/ to correctly filter aggregated results
7. d721b0f - prettier

Closes #110

🤖 Generated with Claude Code