Prometheus Rules Dependency Finder

A Go application that analyzes Prometheus rules definitions and displays the dependency chains between rules.

Features

• Parses Prometheus rules YAML files (regardless of file extension)
• Identifies all recording rules and alert rules by their record or alert names
• Analyzes which rules are used in expressions of other rules
• Displays complete dependency chains with proper indentation
• Shows which rules are not used by any other rule
• Handles circular dependencies gracefully
• Sorts output alphabetically for consistent results
• Jinja Template Support: Automatically replaces Jinja templates ({{{...}}}) with placeholders before parsing
• External File Search: Searches for rule usage in external files within specified folders
• Automatic In-Memory Caching: Always-on caching of processed files with Jinja templates resolved for improved performance

Installation

1. Clone or download this repository
2. Ensure you have Go 1.21+ installed
3. Build the application:

   go build -o rules-finder .

Usage

./rules-finder <yaml-file> [folder1] [folder2] ...

Arguments

• yaml-file: Prometheus rules YAML file to analyze
• folder1, folder2, ...: Optional folders to search for external rule usage

Examples

# Basic analysis
./rules-finder rules.yaml

# Analyze with external file search
./rules-finder rules.yaml ./alerts ./dashboards

# Show help
./rules-finder --help

Output Format

The application displays the dependency analysis in the following format:

• Rule Name - not used: The rule is not referenced in any other rule's expression
• Rule Name - used in: The rule is referenced in other rules' expressions, followed by:
  • Indented list of rules that use this rule
  • Each usage shows the rule name and a truncated version of the expression
  • Recursive display of the dependency chain with increasing indentation
• Rule Name - used in external files: The rule is found in external files, showing:
  • File path and line number
  • Context snippet from the file

Sample Output

cpu_usage_rate - used in:
  high_cpu_usage (expression: cpu_usage_rate > __jinja__)
  high_cpu_usage - used in:
    HighCPUUsage (expression: high_cpu_usage > __jinja__)
    HighCPUUsage - not used
  system_load_score (expression: cpu_usage_rate * __jinja__ + memory_usage_percent * __jinja__)
  system_load_score - not used
  External usage:
    ./dashboards/grafana.json:15 - "expr": "cpu_usage_rate"

UnusedAlert - not used

Note: __jinja__ placeholders indicate where Jinja templates ({{{...}}}) were found and replaced during preprocessing.

Prometheus Rules File Format

The application supports both Prometheus rules file formats:

Format 1: Groups under spec (recommended)

spec:
  groups:
    - name: group_name
      rules:
        - record: recording_rule_name
          expr: some_expression
        
        - alert: alert_rule_name
          expr: some_expression
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "Alert description"

Format 2: Groups at root level (legacy)

groups:
  - name: group_name
    rules:
      - record: recording_rule_name
        expr: some_expression
      
      - alert: alert_rule_name
        expr: some_expression
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Alert description"

The application automatically detects which format is being used and processes the file accordingly.

Features in Detail

Dependency Detection

The application uses regex matching to find rule names in PromQL expressions. It looks for exact word matches to avoid false positives with partial matches.

Circular Dependency Handling

If circular dependencies are detected (Rule A depends on Rule B, which depends on Rule A), the application will detect this and display "(circular dependency detected)" to prevent infinite loops.

Expression Truncation

Long PromQL expressions are truncated to 80 characters for better readability in the output, with "..." appended to indicate truncation.

Jinja Template Handling

The application automatically detects and handles Jinja templates in YAML files:

• Pattern: {{{variable_name}}} (triple curly braces)
• Replacement: All Jinja templates are replaced with __jinja__ placeholder text before YAML parsing
• Purpose: Prevents parsing errors and allows dependency analysis to work with templated files
• Example: expr: cpu_usage > {{{threshold}}} becomes expr: cpu_usage > __jinja__

This feature is particularly useful when analyzing Prometheus rules that use templating systems like Helm or Ansible.

External File Search

When folder paths are provided, the application searches for rule usage in external files:

• Supported file types: .yaml, .yml, .json, .txt, .j2, .md, .go, .py, .js, .ts, .html, .xml, .conf, .cfg, .ini, .toml, .sh, .bash, .zsh, .fish, .ps1, .dockerfile, .makefile, and files without extensions
• Recursive search: Walks through all subdirectories
• Pattern matching: Uses the same regex pattern as internal dependency detection
• Context display: Shows the line number and content where the rule was found
• Automatic exclusion: The original YAML file passed as the first parameter is automatically excluded from the external search to avoid finding rule definitions in the same file being analyzed

Building from Source

# Initialize the module (if not already done)
go mod tidy

# Build the application
go build -o rules-finder .

# Run tests (if you add them)
go test ./...

Dependencies

• gopkg.in/yaml.v3 - For YAML parsing

License

This project is provided as-is for educational and practical use.

Assisted-By: Cursor