Skip to content

feat: add standalone promtool validation scripts - #41

Merged
HahaSula merged 3 commits into
mainfrom
feat-promtool-validation-scripts
Jul 2, 2026
Merged

feat: add standalone promtool validation scripts#41
HahaSula merged 3 commits into
mainfrom
feat-promtool-validation-scripts

Conversation

@HahaSula

@HahaSula HahaSula commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Summary

Refs #40

Implements standalone/manual promtool validation scripts.

  • Add extract_rules.py for extracting PrometheusRule.spec.groups from rendered Helm YAML
  • Add render_and_check.py for chart/deployment helm template -> promtool check rules
  • Add chart-level promtool test rules wrapper
  • Add sample MariaDB promtool series/demo data under sample/promtool-tests/
  • Support deployment discovery outside fixed deployments/ paths
  • Run dependency builds in a temporary copy to avoid writing Chart.lock / charts/*.tgz

Validation

Passed:

  • python3 -m unittest discover -s tests/scripts
  • scripts/promtool_test.sh sample
  • python3 scripts/render_and_check.py chart --root sample
  • python3 scripts/render_and_check.py deployment --root sample --build-dependencies
  • npm run build
  • npm run lint

Known existing issue:

  • npm test has 1 locale-sensitive failure unrelated to this change:
    • tests/unit/git-lib.test.js
    • expected English git output containing On branch
    • current environment returns Chinese output: 位於分支 master

Remaining

  • Promote these scripts to CI jobs in a follow-up

Summary by CodeRabbit

  • New Features
    • Added end-to-end tooling to render alert charts, extract PrometheusRule groups, and validate them with Promtool.
    • Added an automated Promtool test runner for discovered rule test files.
  • Documentation
    • Added a manual Promtool validation guide, including chart and deployment validation workflows.
  • Tests
    • Added/expanded unit and integration tests for rule extraction, Promtool checking/testing, chart discovery, and dependency build behavior.
  • Chores
    • Updated ignore rules for Git, Docker, and Helm packaging to exclude cache/test artifacts and keep build contexts clean.

@rophy

rophy commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

PR Preview Bot

Preview environment torn down.

@coderabbitai

coderabbitai Bot commented Jun 30, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@HahaSula, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 34 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8c82c7dc-5047-46c1-b0ce-24456f25ea96

📥 Commits

Reviewing files that changed from the base of the PR and between 17ea2ff and 8a59890.

📒 Files selected for processing (1)
  • tests/scripts/test_render_and_check.py
📝 Walkthrough

Walkthrough

Adds a Promtool validation pipeline for Helm alert charts: scripts/extract_rules.py extracts PrometheusRule groups from rendered Helm YAML; scripts/render_and_check.py discovers chart/deployment targets, renders them, and runs promtool check rules; scripts/promtool_test.sh runs chart-level rule tests. Sample MariaDB alert rules and promtool test fixtures, unit/integration tests, documentation, and .gitignore/.dockerignore exclusions are also added.

Changes

Promtool Validation Pipeline

Layer / File(s) Summary
extract_rules.py: PrometheusRule extraction utility
scripts/extract_rules.py, tests/scripts/test_extract_rules.py
Defines RuleExtractionError, implements multi-document YAML parsing, PrometheusRule filtering and spec.groups merging, YAML serialization, I/O helpers, CLI parsing, and unit coverage for success and error cases.
render_and_check.py: chart rendering and rule checking
scripts/render_and_check.py, tests/scripts/test_render_and_check.py
Defines RenderTarget, implements chart/deployment discovery with filtering, helm template rendering, temp-copy-isolated helm dependency build, promtool check rules invocation, and run_target orchestration; unit tests cover discovery, rendering, rule checking, and dependency-build isolation.
promtool_test.sh: rule test runner
scripts/promtool_test.sh, tests/scripts/test_promtool_test_sh.py
POSIX shell script discovers *.yaml/*.yml test files under charts/*/tests and promtool-tests/*, runs promtool test rules for each; tests stub promtool and assert invocation and exit-code propagation.
Sample MariaDB alert rules and test data
sample/promtool-tests/mariadb-alerts/..., sample/charts/mariadb-alerts/.helmignore
Adds rules YAML with MariaDB alerts and a test YAML with input series and expected alert assertions; excludes tests/ from Helm packaging.
Integration tests
tests/scripts/test_promtool_integration.py
End-to-end tests running actual promtool and render_and_check.py: invalid PromQL rejection, multi-document rule merge acceptance, failing test detection, MariaDB sample test pass, and Chart.lock non-persistence after dependency build.
Documentation and repo config
docs/promtool-validation.md, .gitignore, .dockerignore
Documents all scripts and workflows; excludes __pycache__/*.pyc from git and sample test directories from Docker build context.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

Poem

🐇 Hop, hop! The rules are checked,
Through Helm-rendered YAML we inspect.
PrometheusRule groups extracted tight,
promtool check rules says "Alright!"
No Chart.lock left, no side effects found—
The rabbit validates safe and sound. 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 5.88% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: new standalone promtool validation scripts.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat-promtool-validation-scripts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@sample/promtool-tests/mariadb-alerts/mariadb_alerts_test.yaml`:
- Around line 14-30: Add missing test coverage for the
MariadbLatencySlowQueries_WarnThreshold alert in mariadb_alerts_test.yaml.
Update the alert_rule_test section to include an assertion for this alert
alongside the existing MariadbLatencySlowQueries_CriticalThreshold and
MariadbTrafficQpsHigh_MaxQps cases, using the same pattern for eval_time,
exp_alerts, exp_labels, and exp_annotations so the warning slow-query rule is
exercised by the sample suite.

In `@scripts/extract_rules.py`:
- Around line 103-105: main() is treating an explicitly passed empty argv the
same as no argv, so callers of main([]) are incorrectly falling back to
sys.argv[1:]. Update main in extract_rules.py to distinguish None from an empty
list by only using sys.argv[1:] when argv is None, and otherwise pass the
provided argv directly into parse_args.
- Around line 34-40: The validation in extract_rules.py is masking malformed
PrometheusRule shapes by using defaults for spec and groups. Update the logic
around document.get("spec") in the rule extraction path so invalid empty or
wrong-typed values like spec: [] or groups: {} still trigger RuleExtractionError
instead of being coerced to {} or []. Keep the existing type checks in the
extraction flow, especially the code that handles spec and rule_groups, but
remove the fallback behavior that turns bad shapes into empty containers.

In `@scripts/render_and_check.py`:
- Around line 52-63: The skip logic in should_skip_deployment_chart is too broad
because it excludes any Chart.yaml whose path contains a "charts" segment, even
when that directory is a legitimate deployment location under root. Narrow the
final return condition so it only skips Helm vendor/dependency charts inside an
actual deployment chart subtree, while still allowing real charts discovered
anywhere under root; keep the existing root/charts and dependency-directory
checks in should_skip_deployment_chart aligned with the discovery contract.
- Around line 78-85: The run_command helper currently lets subprocess.run raise
FileNotFoundError when helm or promtool is missing, which bypasses normal
validation handling. Update run_command to catch FileNotFoundError around the
subprocess.run call and return a failure-like result or otherwise surface a
clean error state that the callers in render_and_check.py can treat as a
validation failure. Keep the fix localized to run_command and preserve its
current contract for existing command execution paths.

In `@tests/scripts/test_promtool_integration.py`:
- Around line 15-19: The PromtoolIntegrationTest class is only gated on
PROMTOOL, but test_real_render_check_supports_non_deployments_path also depends
on Helm via render_and_check.py. Update the test class setup so the
Helm-dependent case is skipped unless both promtool and helm are available,
using the existing PromtoolIntegrationTest and
test_real_render_check_supports_non_deployments_path symbols to add the
additional Helm availability check before running that test.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 07702ffa-e7f8-453d-9513-d21baceb392c

📥 Commits

Reviewing files that changed from the base of the PR and between 0c3f166 and 8256330.

📒 Files selected for processing (13)
  • .dockerignore
  • .gitignore
  • docs/promtool-validation.md
  • sample/charts/mariadb-alerts/.helmignore
  • sample/promtool-tests/mariadb-alerts/mariadb_alerts_test.yaml
  • sample/promtool-tests/mariadb-alerts/rules/mariadb_alerts_rules.yaml
  • scripts/extract_rules.py
  • scripts/promtool_test.sh
  • scripts/render_and_check.py
  • tests/scripts/test_extract_rules.py
  • tests/scripts/test_promtool_integration.py
  • tests/scripts/test_promtool_test_sh.py
  • tests/scripts/test_render_and_check.py

Comment thread sample/promtool-tests/mariadb-alerts/mariadb_alerts_test.yaml
Comment thread scripts/extract_rules.py Outdated
Comment thread scripts/extract_rules.py
Comment thread scripts/render_and_check.py Outdated
Comment thread scripts/render_and_check.py Outdated
Comment thread tests/scripts/test_promtool_integration.py

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/scripts/test_render_and_check.py`:
- Around line 173-178: The test_run_command_reports_missing_binary_cleanly case
is environment-sensitive because it relies on a real missing command name; patch
subprocess.run in run_command’s test path to raise FileNotFoundError instead of
invoking missing-promtool, then keep the assertions on the returned code and
stderr message to verify the fallback behavior deterministically.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8944e363-fa5a-4fe6-87c6-e1588cf786cb

📥 Commits

Reviewing files that changed from the base of the PR and between 8256330 and 17ea2ff.

📒 Files selected for processing (6)
  • sample/promtool-tests/mariadb-alerts/mariadb_alerts_test.yaml
  • scripts/extract_rules.py
  • scripts/render_and_check.py
  • tests/scripts/test_extract_rules.py
  • tests/scripts/test_promtool_integration.py
  • tests/scripts/test_render_and_check.py
🚧 Files skipped from review as they are similar to previous changes (3)
  • tests/scripts/test_promtool_integration.py
  • sample/promtool-tests/mariadb-alerts/mariadb_alerts_test.yaml
  • scripts/extract_rules.py

Comment thread tests/scripts/test_render_and_check.py
@HahaSula
HahaSula requested a review from rophy June 30, 2026 16:22

@rophy rophy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clean, well-tested validation scripts. One minor note: main() in extract_rules.py re-inlines the extract + yaml.safe_dump logic that promtool_rules_yaml() already encapsulates — could call the helper to avoid drift. Not blocking.

@HahaSula
HahaSula merged commit a5d4a56 into main Jul 2, 2026
4 checks passed
@HahaSula
HahaSula deleted the feat-promtool-validation-scripts branch July 2, 2026 02:15
HahaSula added a commit that referenced this pull request Jul 6, 2026
Bump version from 1.3.0 to 1.4.0 to trigger a new image build and
GitHub Release via CI. Since 1.3.0: deployment sync (#44), alert
overview mode with column filters (#37), promtool validation (#41,
#43), plus several fixes — enough new features to warrant a minor
bump per this project's convention (1.2.0 -> 1.3.0 similarly bumped
minor for the Gitea migration).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants