Skip to content

Add minimal metrics guidance to event-gateway skill #11

@leggetter

Description

@leggetter

Summary

The Hookdeck CLI v1.9.0-beta.1 added metrics commands under hookdeck gateway metrics. The event-gateway skill should provide minimal guidance on when to use metrics and point to live docs for syntax/details.

Current State

skills/event-gateway/references/cli-workflows.md mentions metrics at line 226 with a brief example and link to docs. This is good! However, metrics aren't integrated into the monitoring/debugging workflow guidance.

Proposed Minimal Changes

Following the principle "only add context agents don't already have" - the skill should NOT duplicate command syntax (that's in the docs). Instead, provide use-case context for when/why agents should reach for metrics.

1. Add metrics decision point to references/monitoring-debugging.md

Add a brief section explaining when to use metrics vs event list:

## Metrics vs Event Inspection

**Use metrics** (`hookdeck gateway metrics`) when you need aggregate views:
- Overall health checks (error rates, volume trends)
- Identifying problematic resources (group failures by destination, source, connection)
- Queue depth monitoring (delivery backlog)
- Time-based trend analysis

**Use event list/inspect** (`hookdeck gateway event`) when you need individual event details:
- Inspecting specific event payloads
- Retrying individual events
- Detailed attempt history

For metrics command reference and examples, fetch [/docs/cli/metrics.md](https://hookdeck.com/docs/cli/metrics.md).

2. Update references/04-iterate.md

Add one line suggesting metrics as a starting point:

## Debug Workflow

Before diving into individual events, consider using `hookdeck gateway metrics events` to understand scope (isolated vs systemic failure, when it started, trends). See [Metrics docs](https://hookdeck.com/docs/cli/metrics.md).

Then proceed with event list/inspect/retry...

3. Keep existing cli-workflows.md as-is

The current line 226 already points to docs - that's sufficient. Don't add command examples (they'll go stale).

Rationale

Per AGENTS.md:

  • "Only add context agents don't already have" - provide the decision context (when to use metrics), not syntax
  • "Always link to live docs" - let docs be the source of truth for command details
  • "Avoid time-sensitive information" - don't embed example commands that might change

Metrics are a monitoring workflow enhancement, so the main additions should be in monitoring-debugging.md (decision criteria) and 04-iterate.md (integration into debug workflow).

Anti-Pattern to Avoid

Do NOT add:

  • Full command examples with all flags (that's in docs)
  • Lists of available measures (that's in CLI help / docs)
  • Syntax reference (that's in docs)

Impact

Minimal, focused additions (~10-15 lines total) that help agents know when metrics are useful, while keeping docs as the source of truth for how to use them.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions