Metrics commands: usability improvements for v1.9.0-beta.1

[leggetter]

Summary

The new metrics functionality in v1.9.0-beta.1 is excellent and provides powerful querying capabilities. After testing all metrics subcommands, here are some usability improvements that would enhance the developer experience.

Testing Context

Tested commands:

• hookdeck gateway metrics events
• hookdeck gateway metrics requests
• hookdeck gateway metrics attempts
• hookdeck gateway metrics queue-depth
• hookdeck gateway metrics pending
• hookdeck gateway metrics transformations
• hookdeck gateway metrics events-by-issue

All commands work correctly with filtering, granularity, dimensions, and JSON output.

Proposed Improvements

1. Relative Time Shortcuts

Current: Requires full ISO 8601 timestamps

hookdeck gateway metrics events --start 2026-02-20T00:00:00Z --end 2026-02-26T23:59:59Z

Suggestion: Support relative time shortcuts

hookdeck gateway metrics events --start 7d --end now
hookdeck gateway metrics events --last 24h
hookdeck gateway metrics events --start 2026-02-20 --end 2026-02-26  # accept date-only

Rationale: Reduces friction for ad-hoc queries, matches common monitoring tool UX patterns.

2. Measure Discovery

Current: Available measures are listed in help text (good!) but you must run --help on each subcommand

Suggestion: Add flag to list available measures

hookdeck gateway metrics events --list-measures
# Output: count, successful_count, failed_count, scheduled_count, paused_count, error_rate, avg_attempts, scheduled_retry_count

Or include a summary in the main hookdeck gateway metrics --help output.

Rationale: Improves discoverability, reduces need to consult docs or help for common queries.

3. Dimension Discovery

Current: --dimensions flag exists but valid dimension names aren't documented in help

Suggestion: Document available dimensions in help text

Flags:
  --dimensions string   Comma-separated list of dimensions (available: destination_id, source_id, connection_id, status)

Or add a discovery flag:

hookdeck gateway metrics events --list-dimensions

Rationale: Currently requires guessing or reading API docs to know what dimensions are available.

4. Clearer Error Messages for Missing Required Flags

Current: Missing --start or --end shows generic error

Suggestion: Show example with valid format

Error: required flag(s) "start", "end" not set

Example usage:
  hookdeck gateway metrics events --start 2026-02-20T00:00:00Z --end 2026-02-26T23:59:59Z --measures count,error_rate

Optional: Quality of Life

Default Measures

Consider setting sensible defaults for --measures when omitted:

• events: count,failed_count,error_rate
• queue-depth: max_depth,max_age
• transformations: count,failed_count,error_rate

This reduces typing for common queries while keeping explicit control when needed.

Time Range Validation

If --end is before --start, show friendly error instead of API error.

Impact

These improvements would:

• Reduce typing and friction for common queries
• Improve discoverability of features
• Better align with patterns from other monitoring/observability tools
• Maintain backward compatibility (all suggestions are additive)

Priority Assessment

High impact, low effort:

1. Relative time shortcuts (fix: taking cli_path from attempt request instead of destination #1)
2. Dimension documentation in help (Feat/unauthenticated user #3)
3. Better error messages (fix: Fix to send data in string_data in case the content-type is text/plain or x-wwww-form-urlencoded #4)

Medium impact, medium effort:
4. Measure discovery flag (#2)
5. Default measures (optional)

Low effort:
6. Time range validation (optional)

---

Great work on this feature! The foundation is solid and these refinements would make it even more delightful to use.