Monitor Validate Validator

Automatically validates monitoring configurations and alert rules before they are committed to the repository.

When to Use This Hook

Attach this hook when you need to:

• Ensure monitoring YAML/JSON configs pass schema validation before reaching production
• Catch malformed alert thresholds, missing metric names, or invalid query syntax early
• Enforce organizational standards for monitoring definitions across teams

Consider alternatives when:

• Your monitoring platform already has a built-in validation API you call in CI
• You only have a handful of static alert rules that rarely change

Quick Start

Configuration

Copy
name: monitor-validate-validator
type: hook
trigger: PreToolUse
category: git

Example Trigger

Copy
# Hook triggers when editing monitoring config files
claude> Edit monitoring/alerts/cpu-alerts.yaml
# Hook automatically validates the alert definition structure

Example Output

Validating monitoring config: monitoring/alerts/cpu-alerts.yaml
  Checking metric names... OK
  Checking threshold ranges... OK
  Checking alert severity levels... OK
  Checking notification channels... OK
All 4 validation checks passed for cpu-alerts.yaml

Core Concepts

Validation Coverage Overview

Aspect	Details
Metric Names	Validates against registered metric catalog
Threshold Logic	Ensures min < warning < critical ordering
Query Syntax	Parses PromQL/LogQL expressions for correctness
Channel Routing	Confirms notification channels exist and are active
Label Compliance	Checks required labels (team, service, severity)

Validation Workflow

File Edit Detected
       |
  Is monitoring config?
   /          \
  No           Yes
  |             |
 Skip     Parse YAML/JSON
              |
        Schema Validate
              |
        Check Thresholds
              |
        Verify Channels
              |
      Pass ──── Fail
       |          |
    Allow      Block + Report

Configuration

Parameter	Type	Default	Description
config_patterns	string[]	["alerts/*.yaml","monitors/*.json"]	Glob patterns for monitoring config files
schema_path	string	.claude/schemas/monitor.json	Path to JSON schema for validation
strict_mode	boolean	true	Block edits on validation failure vs warn only
metric_catalog	string	metrics/catalog.yaml	Registered metric names catalog path
required_labels	string[]	["team","severity"]	Labels every alert definition must include

Best Practices

1. Maintain a Metric Catalog - Keep a central registry of valid metric names so the validator can catch typos in metric references before they cause silent alert failures in production.

2. Enforce Threshold Ordering - Always validate that warning thresholds are less severe than critical thresholds. A misconfigured alert where warning > critical creates confusing on-call experiences.

3. Require Notification Channels - Every alert rule should route to at least one notification channel. The validator should block alerts with empty or invalid channel references.

4. Version Your Schemas - As monitoring standards evolve, version your validation schemas so older configs can migrate gracefully rather than breaking on new required fields.

5. Run in Strict Mode for Production - Use strict mode (blocking) for production monitoring configs but allow warn-only mode for development and staging environments.

Common Issues

1. False Positives on Dynamic Metrics - Some metrics are generated at runtime and will not appear in the static catalog. Add a dynamic: true annotation to skip catalog checks for those entries.

2. YAML Parsing Failures on Anchors - Complex YAML with anchors and aliases can confuse simple parsers. Ensure your validation uses a full YAML 1.2 parser that handles references correctly.

3. Schema Drift Between Teams - Different teams may evolve their monitoring schemas independently. Establish a single source of truth schema and use CI to enforce it across all repositories.