Merge pull request ceph#66326 from afreen23/fixes-mixins

monitoring: Fixes for development

Reviewed-by: Nizamudeen A <[email protected]>
Reviewed-by: Anthony D Atri <[email protected]>

Author: afreen23

monitoring/ceph-mixin/.gitignore

@@ -1 +1,3 @@
 vendor
+jb
+jsonnet-bundler

monitoring/ceph-mixin/Makefile

@@ -1,25 +1,48 @@
+# Main development workflow
 all: fmt generate lint test
 
+# Format Jsonnet code automatically
 fmt:
 	./lint-jsonnet.sh -i
 
+# Generate all dashboards and alerts
 generate: dashboards_out
 	tox -ealerts-fix
 
+# Install Jsonnet dependencies
 vendor: jsonnetfile.lock.json
 	tox -ejsonnet-bundler-install
 
+# Generate JSON dashboards from Jsonnet templates
 dashboards_out: vendor dashboards
 	tox -ejsonnet-fix
 
+# Run all linters (Jsonnet and alerts)
 lint:
 	tox -ejsonnet-lint
 	tox -ealerts-lint
 
+# Run all tests (verifies generated files match templates)
 test: generate
 	tox -ejsonnet-check
 	tox -epromql-query-test
 	tox -ealerts-test
+
+# Alias for test
 check: test
 
-.PHONY: all fmt generate lint test check
+# Show this help message
+help:
+	@echo "Ceph Mixin Development Commands:"
+	@echo ""
+	@echo "  all       - Format, generate, lint, and test everything"
+	@echo "  fmt       - Format Jsonnet code automatically"
+	@echo "  generate  - Generate all dashboards and alerts"
+	@echo "  vendor    - Install Jsonnet dependencies"
+	@echo "  lint      - Run all linters (Jsonnet and alerts)"
+	@echo "  test      - Run all tests (requires generated files)"
+	@echo "  check     - Alias for test"
+	@echo ""
+	@echo "Quick start: 'make all' to run the complete workflow"
+
+.PHONY: all fmt generate lint test check help

monitoring/ceph-mixin/README.md

@@ -8,6 +8,8 @@ You can use the Grafana dashboards and alerts with Jsonnet like any other
 prometheus mixin. You can find more resources about mixins in general on
 [monitoring.mixins.dev](https://monitoring.mixins.dev/).
 
+-------
+
 ### Grafana dashboards for Ceph
 In `dashboards_out` you can find a collection of
 [Grafana](https://grafana.com/grafana) dashboards for Ceph Monitoring.
@@ -18,25 +20,20 @@ plugin](http://docs.ceph.com/en/latest/mgr/prometheus/) and the
 [node_exporter (0.17.0)](https://github.com/prometheus/node_exporter).
 
 
-##### Recommended versions: 
--grafana 8.3.5
-    -grafana-piechart-panel 1.6.2
-    -grafana-status-panel 1.0.11
-
-#### Requirements
-
-- [Status Panel](https://grafana.com/plugins/vonage-status-panel) installed on
- your Grafana instance
-- [Pie Chart Panel](https://grafana.com/grafana/plugins/grafana-piechart-panel/)
- installed on your Grafana instance
-
-
 ### Prometheus alerts
 In `prometheus_alerts.libsonnet` you'll find a set of Prometheus
 alert rules that should provide a decent set of default alerts for a
 Ceph cluster. After building them with jsonnet put this file in place according to your Prometheus
 configuration (wherever the `rules` configuration stanza points).
 
+
+### SNMP
+Ceph provides a MIB (CEPH-PROMETHEUS-ALERT-MIB.txt) to support sending
+Prometheus alerts to an SNMP management platform. The translation from
+Prometheus alert to SNMP trap requires the Prometheus alert to contain an OID
+that maps to a definition within the MIB. When making changes to the Prometheus
+alert rules file, developers should include any necessary changes to the MIB.
+
 ### Multi-cluster support
 Ceph-mixin supports dashboards and alerts across multiple clusters. 
 To enable this feature you need to configure the following in `config.libsonnnet`:
@@ -45,38 +42,56 @@ To enable this feature you need to configure the following in `config.libsonnnet
 showMultiCluster: true,
 clusterLabel: '<your cluster label>',
 ```
+----------------
 
-##### Recommended versions: 
--prometheus v2.33.4
+### Building from Jsonnet
 
-#### SNMP
-Ceph provides a MIB (CEPH-PROMETHEUS-ALERT-MIB.txt) to support sending
-Prometheus alerts to an SNMP management platform. The translation from
-Prometheus alert to SNMP trap requires the Prometheus alert to contain an OID
-that maps to a definition within the MIB. When making changes to the Prometheus
-alert rules file, developers should include any necessary changes to the MIB.
+#### Method 1: System Packages (Recommended for most users)
 
+```bash
+sudo dnf install jsonnet jsonnet-bundler  # RHEL/Fedora
+sudo apt-get install jsonnet jsonnet-bundler  # Ubuntu/Debian
 
-##### Recommended: 
--alertmanager 0.16.2
+# Install dependencies
+jb install
 
-### Building from Jsonnet
+# Generate all dashboards and alerts
+make generate
+
+# Run tests
+make test
+```
 
-- Install [jsonnet](https://jsonnet.org/) (at least v0.18.0)
-    - By installing the package `jsonnet` in most of the distro and
-      `golang-github-google-jsonnet` in fedora
-- Install [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler)
+#### Method 2: Local Build (For CI/CD or no root access)
 
-To rebuild all the generated files, you can run `tox -egrafonnet-fix`.
+```bash
+./jsonnet-bundler-build.sh
 
-The jsonnet code located in this directory depends on some Jsonnet third party
-libraries. To update those libraries you can run `jb update` and then update
-the generated files using `tox -egrafonnet-fix`.
+# Install dependencies using local jb
+./jb install
 
-### Building alerts from `prometheus_alerts.libsonnet`
+# Generate all dashboards and alerts  
+make generate
 
-To rebuild the `prometheus_alerts.yml` file from the corresponding libsonnet,
-you can run `tox -ealerts-fix`.
+# Run tests
+make test
+```
+
+### Ceph Mixin Development Commands
 
+```bash
+make all        # Format, generate, lint, and test
+make fmt        # Format Jsonnet files
+make generate   # Regenerate JSON dashboards and alerts from templates
+make lint       # Run linters
+make test       # Run all tests
+make vendor     # Install dependencies
+make help       # List all available commands
+```
 
-##### Any upgrade or downgrade to different major versions of the recommended tools mentioned above is not supported.
+### Supported Versions
+* jsonnet: v0.18.0+
+* jsonnet-builder: 0.4.0+
+* grafonnet-lib: always uses latest `master` branch
+* alertmanager: 0.16.2+
+* prometheus: v2.33.4+

monitoring/ceph-mixin/tox.ini

@@ -56,7 +56,7 @@ description =
      test: Run promtool unit testing on grafana queries.
 deps =
     -rrequirements-lint.txt
-depends = grafonnet-check
+depends = jsonnet-check
 setenv =
 allowlist_externals =
   promtool
@@ -67,7 +67,7 @@ commands =
 deps =
     -rrequirements-alerts.txt
     pytest
-depends = grafonnet-check
+depends = jsonnet-check
 allowlist_externals =
   promtool
   jsonnet