Upload files to "/"
This commit is contained in:
189
README.md
Normal file
189
README.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# Storage Saturation Report for Nagios XI
|
||||
|
||||
**Product:** Storage Saturation Report
|
||||
**Vendor:** Everwatch.Global
|
||||
**Document:** Technical documentation for implementation, calculations, and perfdata parsing. For compliance and audit traceability.
|
||||
**Component version:** 1.0.2 (see CHANGELOG.txt)
|
||||
|
||||
This component displays a report-style view of storage volumes that are close to capacity. Only services with the `trackvolume` custom variable enabled are included.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Custom Variables
|
||||
|
||||
To enable volume tracking for a service, add a custom variable named **`trackvolume`** with value **`1`** or **`true`** (case-insensitive) to the service configuration.
|
||||
|
||||
- **`trackvolume`**: Set to `1` or `true` to include the service in the report.
|
||||
|
||||
The service must provide performance data (perfdata) that includes disk usage. The component parses this data to obtain used space, total space, and derived percentage and available space.
|
||||
|
||||
### Template Support
|
||||
|
||||
Custom variables can be set in templates and inherit to all services using that template.
|
||||
|
||||
### Navigation Path in CCM
|
||||
|
||||
1. Navigate to **Core Configuration Manager** → **Hosts/Services**
|
||||
2. Select the config and the service that monitors disk usage
|
||||
3. Open **Custom Variables**
|
||||
4. Add `trackvolume` with value `1` or `true`
|
||||
|
||||
---
|
||||
|
||||
## Technical Operation
|
||||
|
||||
The following flow is implemented in `saturationreport.api.php` and is deterministic for audit traceability.
|
||||
|
||||
1. **Service inclusion**
|
||||
Only services with custom variable **`trackvolume`** equal to **`1`** or **`true`** (case-insensitive) are included. Implemented via `get_xml_custom_service_variable_status()` and `has_trackvolume_enabled()`.
|
||||
|
||||
2. **Data source**
|
||||
- Service list: `get_data_service_status()`
|
||||
- Perfdata: from each service’s `perfdata` field when present; if empty, from `get_xml_service_status()` (backend `getservicestatus`).
|
||||
|
||||
3. **Parsing**
|
||||
Each service’s single perfdata string is passed to `parse_disk_perfdata()`. Parsing tries **four formats in fixed order** (see Performance Data Parsing). The first successful parse is used. Output includes: `used`, `total`, `available`, `percent`, `used_bytes`, `total_bytes`, `available_bytes`, `used_unit`, `total_unit`, and when applicable `label`.
|
||||
|
||||
4. **Multi-metric behavior**
|
||||
For the single-metric format (Format 3), the perfdata string may contain multiple metrics (e.g. multiple drives). All matches are evaluated; the metric with the **highest percent used** is selected for that service. If that metric has a quoted label, it is used as the CAPTION.
|
||||
|
||||
5. **Sorting**
|
||||
Rows are sorted by **`disk_available_bytes` ascending** (least available first / most critical first).
|
||||
|
||||
6. **Display**
|
||||
CAPTION uses the perfdata **label** when present (e.g. `C:\_Label:__Serial_Number_2c3f47f4`); otherwise the service name/description. All displayed sizes and percentages are derived from the parsed values and the formulas below.
|
||||
|
||||
---
|
||||
|
||||
## Calculations
|
||||
|
||||
All formulas below are implemented in `saturationreport.api.php` (`parse_disk_perfdata`, `convert_to_bytes`, `format_bytes`). They are deterministic for a given perfdata string and unit handling.
|
||||
|
||||
### Percent used
|
||||
|
||||
- **Formula:** `percent_used = (used_bytes / total_bytes) * 100`
|
||||
- **Storage/display:** Rounded to **2 decimal places** (e.g. `round($percent, 2)`).
|
||||
|
||||
### Available space
|
||||
|
||||
- **Formula:** `available_bytes = total_bytes - used_bytes`
|
||||
- In display units: `available = total - used` (same unit as used/total).
|
||||
|
||||
### Byte conversion (input → bytes)
|
||||
|
||||
All capacity math uses **base 1024** for both binary and decimal-style units in this component:
|
||||
|
||||
| Unit | Formula |
|
||||
|------|--------|
|
||||
| TiB, T | `value × 1024⁴` |
|
||||
| GiB, G | `value × 1024³` |
|
||||
| MiB, M | `value × 1024²` |
|
||||
| KiB, K | `value × 1024` |
|
||||
| B, (none), % | `value` (no scaling) |
|
||||
|
||||
- Implemented in: `convert_to_bytes($value, $unit)`.
|
||||
|
||||
### Human-readable display (bytes → display)
|
||||
|
||||
- **Function:** `format_bytes($bytes, $unit)`
|
||||
- Divides bytes by 1024^n and rounds to **1 decimal place**.
|
||||
- Unit selection: TB if bytes ≥ 1024⁴, else GB if ≥ 1024³, else MB if ≥ 1024², else KB if ≥ 1024, else B.
|
||||
|
||||
### Unit inference
|
||||
|
||||
- If **total** (or max) has no unit but **used** has a unit, total is interpreted in the **same unit as used** (e.g. both MB).
|
||||
|
||||
---
|
||||
|
||||
## Performance Data (Perfdata) Parsing
|
||||
|
||||
Parsing is attempted in the following order. The **first** successful format wins. All patterns are PCRE and case-insensitive unless noted.
|
||||
|
||||
### Format 1 – NCPA-style quoted `used` / `total`
|
||||
|
||||
- Two metrics: `'used'=value[unit];` and `'total'=value[unit];`
|
||||
- **Patterns:**
|
||||
- Used: `/'used'\s*=\s*([0-9.]+)([KMGT]?(?:IB|B)?);/i`
|
||||
- Total: `/'total'\s*=\s*([0-9.]+)([KMGT]?(?:IB|B)?);/i`
|
||||
- **Capture groups:** (1) numeric value, (2) unit (e.g. MB, MiB)
|
||||
- **Example:** `'used'=0.69GiB;;; 'total'=5.82GiB;;;`
|
||||
|
||||
### Format 2 – NCPA-style unquoted `used` / `total`
|
||||
|
||||
- Same as Format 1 with unquoted labels.
|
||||
- **Patterns:**
|
||||
- Used: `/\bused\s*=\s*([0-9.]+)([KMGT]?(?:IB|B)?);/i`
|
||||
- Total: `/\btotal\s*=\s*([0-9.]+)([KMGT]?(?:IB|B)?);/i`
|
||||
- **Example:** `used=0.69GiB;;; total=5.82GiB;;;`
|
||||
|
||||
### Format 3 – Single-metric with optional quoted label (multi-metric)
|
||||
|
||||
- Standard Nagios: **label**`=`**value**`[unit]`**;**warn**;**crit**;**min**;**max**`[unit]`. Value is “used”; 5th field is “max” (total). If max has no unit, the value’s unit is used.
|
||||
- **Label:** Quoted `'...'` (any characters except single quote) or unquoted (non-whitespace, non-`=`).
|
||||
- **Full pattern:**
|
||||
`(?:'([^']*)'|[^=\s]+)=([0-9.]+)([KMGT]?(?:IB|B)?);[^;]*;[^;]*;[^;]*;([0-9.]+)([KMGT]?(?:IB|B)?)?`
|
||||
- **Capture groups:** (1) label if quoted, (2) value, (3) value unit, (4) max/total, (5) max unit if present.
|
||||
- **Example:** `'C:\_Label:__Serial_Number_2c3f47f4'=91445.6016MB;111560;132477;0;139450`
|
||||
- When **multiple** such metrics appear in one perfdata string, the metric with the **largest percent used** is chosen; its label (if any) is used for CAPTION.
|
||||
|
||||
### Format 4 – Fallback single-metric (no label capture)
|
||||
|
||||
- Same structure as Format 3; label is not captured.
|
||||
- **Pattern:** `/[^=]*=([0-9.]+)([KMGT]?(?:IB|B)?);[^;]*;[^;]*;[^;]*;([0-9.]+)([KMGT]?(?:IB|B)?)?/i`
|
||||
- **Capture groups:** (1) value, (2) value unit, (3) max, (4) max unit.
|
||||
- **Example:** `/=4985MiB;9592;10791;0;11991`
|
||||
|
||||
### Unit token
|
||||
|
||||
- **Pattern:** `[KMGT]?(?:IB|B)?` — optional K/M/G/T followed by optional `iB` or `B` (e.g. M, MB, MiB).
|
||||
|
||||
---
|
||||
|
||||
## Display
|
||||
|
||||
The report is a table, ordered by available disk space (ascending). Each row shows:
|
||||
|
||||
- **DISPLAY NAME:** Host name
|
||||
- **CAPTION:** Perfdata volume label when present (e.g. `C:\_Label:__Serial_Number_2c3f47f4`), otherwise service description/name
|
||||
- **DISK SPACE USED:** Used space (e.g. "117 GB")
|
||||
- **DISK SPACE AVAILABLE:** Available space (e.g. "2.7 GB") with color coding
|
||||
- **PERCENT USED:** Percentage with progress bar (e.g. "97%")
|
||||
|
||||
---
|
||||
|
||||
## Export and Print
|
||||
|
||||
Export uses **client-side** PDF and image generation (jsPDF + html2canvas). No dependency on Nagios XI Chromium or the report command pipeline.
|
||||
|
||||
- **PDF:** Client-side export: html2canvas captures `#saturationreport-container`, jsPDF creates a one-page PDF and triggers download. Libraries loaded from `scripts/vendor/` when present (html2canvas.min.js, jspdf.umd.min.js), else CDN. Fallback to browser Print (e.g. Print to PDF) if jsPDF or html2canvas unavailable.
|
||||
- **Image (PNG):** Client-side: html2canvas captures `#saturationreport-container` (2× scale). Same vendor/CDN loading as PDF.
|
||||
- **Progress bar:** The "percent used" bar uses color classes (green/amber/red) in both the main stylesheet and the minimal export document so the bar is styled correctly in the report and in exported PDF/image.
|
||||
|
||||
Add to My Reports / Schedule / Email use `get_add_myreport_html()` with the full report URL. All report actions (settings, star, Schedule, Email, Export PDF, Export Image) are in the report options well in a single row.
|
||||
|
||||
### Mode routing (index.php)
|
||||
|
||||
- **default:** Full page with form, reportexportlinks, and `#report` container. Report body is loaded via AJAX from `?mode=getreport`.
|
||||
- **mode=getreport:** Returns only the report HTML (table and optional header). Used by (1) AJAX to fill `#report`, (2) client-side capture for PDF/image.
|
||||
- **mode=submitpdf** / **mode=submitjpg:** Still available for XI installs that use the Chromium pipeline; the Export PDF button uses client-side jsPDF + html2canvas by default.
|
||||
|
||||
---
|
||||
|
||||
## Compliance and Audit
|
||||
|
||||
- **Implementation reference:** Parsing and calculations are in `saturationreport.api.php`: `parse_disk_perfdata()`, `convert_to_bytes()`, `format_bytes()`, `get_saturationreport_services_data()`, `has_trackvolume_enabled()`.
|
||||
- **Parsing order:** Formats 1 → 2 → 3 → 4; first successful parse is used.
|
||||
- **Determinism:** For a given perfdata string and unit rules, percent used and available space are uniquely determined by the formulas and pattern order above.
|
||||
- **Version:** This document and the formulas/patterns apply to component version 1.0.3 (see CHANGELOG.txt).
|
||||
|
||||
---
|
||||
|
||||
## Author / Vendor
|
||||
|
||||
**Everwatch.Global**
|
||||
https://everwatch.global
|
||||
|
||||
Component development: snapier
|
||||
Technical documentation: Component version 1.0.3, January 2026
|
||||
Reference in New Issue
Block a user