mongo-x-ray-hc 2.0.0__tar.gz

mongo_x_ray_hc-2.0.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: mongo-x-ray-hc
+Version: 2.0.0
+Summary: Health check analysis plugin for x-ray
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mongo-x-ray>=2.0.0
+Requires-Dist: pymongo>=4.0
+
+# mongo-x-ray-hc
+
+[![CI](https://github.com/zhangyaoxing/mongo-x-ray-hc/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangyaoxing/mongo-x-ray-hc/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mongo-x-ray-hc.svg)](https://pypi.org/project/mongo-x-ray-hc/)
+
+Health check analysis plugin for [x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray).
+
+## Install
+
+```bash
+pip install mongo-x-ray mongo-x-ray-hc
+```
+
+## Usage
+
+```bash
+x-ray healthcheck
+x-ray hc  # alias for healthcheck
+x-ray healthcheck -u mongodb://localhost:27017 -f html -o /path/to/output/
+```
+
+## Compatibility
+
+Supports MongoDB 5.0 and above on replica sets and sharded clusters.
+**Standalone deployments are not supported.**
+
+| Replica Set | Sharded Cluster | Standalone |
+| :---------: | :-------------: | :--------: |
+| ✅ | ✅ | ❌ |
+
+## Parameters
+
+```bash
+x-ray healthcheck [-h] [-u URI] [-s CHECKSET] [-o OUTPUT]
+                  [-f {markdown,html,pdf}] [--no-browser]
+```
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| `-u, --uri` | MongoDB connection URI. | `HC_URI` env var, else `mongodb://localhost:47017` |
+| `-s, --checkset` | Checkset to run. | `default` |
+| `-o, --output` | Output folder path. | `output/` |
+| `-f, --format` | Output format: `markdown`, `html` or `pdf` (PDF also keeps Markdown and HTML). | `html` |
+| `--no-browser` | Do not open the generated report in the browser. | `false` |
+
+## Check Items
+
+| Item | Purpose |
+| --- | --- |
+| `BuildInfoItem` | MongoDB server build information, including a version end-of-life check. |
+| `ClusterItem` | Cluster topology: replica set config/status, sharding overview and oplog window. |
+| `CollInfoItem` | Collection information: sizes, fragmentation and operation latency. |
+| `HostInfoItem` | Host information: filesystem type, NUMA settings and host properties. |
+| `IndexInfoItem` | Index coverage and health. |
+| `SecurityItem` | Security posture (authentication and authorization). |
+| `ServerStatusItem` | Server status: cache, connections, opcounters and query targeting. |
+| `ShardKeyItem` | Shard key selection and data balance. |
+
+## Development
+
+Requires Python 3.10+, MongoDB 5.0 or later, and the [mongo-x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray) core package.
+
+```bash
+make unit-test   # run the unit tests
+make lint        # ruff check + ruff format --check
+make minify      # minify templates
+```

mongo_x_ray_hc-2.0.0/README.md

@@ -0,0 +1,67 @@
+# mongo-x-ray-hc
+
+[![CI](https://github.com/zhangyaoxing/mongo-x-ray-hc/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangyaoxing/mongo-x-ray-hc/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mongo-x-ray-hc.svg)](https://pypi.org/project/mongo-x-ray-hc/)
+
+Health check analysis plugin for [x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray).
+
+## Install
+
+```bash
+pip install mongo-x-ray mongo-x-ray-hc
+```
+
+## Usage
+
+```bash
+x-ray healthcheck
+x-ray hc  # alias for healthcheck
+x-ray healthcheck -u mongodb://localhost:27017 -f html -o /path/to/output/
+```
+
+## Compatibility
+
+Supports MongoDB 5.0 and above on replica sets and sharded clusters.
+**Standalone deployments are not supported.**
+
+| Replica Set | Sharded Cluster | Standalone |
+| :---------: | :-------------: | :--------: |
+| ✅ | ✅ | ❌ |
+
+## Parameters
+
+```bash
+x-ray healthcheck [-h] [-u URI] [-s CHECKSET] [-o OUTPUT]
+                  [-f {markdown,html,pdf}] [--no-browser]
+```
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| `-u, --uri` | MongoDB connection URI. | `HC_URI` env var, else `mongodb://localhost:47017` |
+| `-s, --checkset` | Checkset to run. | `default` |
+| `-o, --output` | Output folder path. | `output/` |
+| `-f, --format` | Output format: `markdown`, `html` or `pdf` (PDF also keeps Markdown and HTML). | `html` |
+| `--no-browser` | Do not open the generated report in the browser. | `false` |
+
+## Check Items
+
+| Item | Purpose |
+| --- | --- |
+| `BuildInfoItem` | MongoDB server build information, including a version end-of-life check. |
+| `ClusterItem` | Cluster topology: replica set config/status, sharding overview and oplog window. |
+| `CollInfoItem` | Collection information: sizes, fragmentation and operation latency. |
+| `HostInfoItem` | Host information: filesystem type, NUMA settings and host properties. |
+| `IndexInfoItem` | Index coverage and health. |
+| `SecurityItem` | Security posture (authentication and authorization). |
+| `ServerStatusItem` | Server status: cache, connections, opcounters and query targeting. |
+| `ShardKeyItem` | Shard key selection and data balance. |
+
+## Development
+
+Requires Python 3.10+, MongoDB 5.0 or later, and the [mongo-x-ray](https://github.com/mongodb-ps/ce-mongo-x-ray) core package.
+
+```bash
+make unit-test   # run the unit tests
+make lint        # ruff check + ruff format --check
+make minify      # minify templates
+```

mongo_x_ray_hc-2.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools==83.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mongo-x-ray-hc"
+version = "2.0.0"
+description = "Health check analysis plugin for x-ray"
+readme = "README.md"
+requires-python = ">=3.10,<4"
+dependencies = [
+  "mongo-x-ray>=2.0.0",
+  "pymongo>=4.0",
+]
+
+[project.entry-points."mongo_x_ray.plugins"]
+healthcheck = "mongo_x_ray_hc.plugin:HealthcheckPlugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mongo_x_ray_hc*"]
+
+[tool.setuptools.package-data]
+"mongo_x_ray_hc" = ["templates/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+  "slow: marks tests as slow",
+  "integration: marks tests as integration tests",
+  "unit: marks tests as unit tests",
+]
+
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+exclude = [".venv", "build", "dist"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mongo_x_ray", "mongo_x_ray_ftdc", "mongo_x_ray_gmd", "mongo_x_ray_hc", "mongo_x_ray_log", "mongo_x_ray_risk"]
+
+
+[tool.pyright]
+pythonVersion = "3.10"
+venvPath = "../ce-mongo-x-ray"
+venv = ".venv"
+typeCheckingMode = "basic"
+extraPaths = [
+  "src",
+  "../ce-mongo-x-ray/src",
+]

mongo_x_ray_hc-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mongo_x_ray_hc-2.0.0/src/mongo_x_ray_hc/__init__.py

@@ -0,0 +1,11 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+
+MongoDB health check analysis package.
+"""

mongo_x_ray_hc-2.0.0/src/mongo_x_ray_hc/check_items/__init__.py

@@ -0,0 +1,9 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+"""

mongo_x_ray_hc-2.0.0/src/mongo_x_ray_hc/check_items/base_item.py

@@ -0,0 +1,202 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+"""
+
+import gzip
+import html as html_mod
+import logging
+import os
+from abc import ABC, abstractmethod
+from typing import Optional, Union
+
+from bson import json_util
+
+from mongo_x_ray.parsers.base_parser import TABLE_ALIGNMENT
+from mongo_x_ray.shared import SEVERITY, to_json
+from mongo_x_ray.utils import env, get_script_path, to_ejson
+from mongo_x_ray_hc.rules.base_rule import BaseRule
+
+
+def colorize_severity(severity: SEVERITY) -> str:
+    mapping = {
+        SEVERITY.HIGH.name: "red",
+        SEVERITY.MEDIUM.name: "orange",
+        SEVERITY.LOW.name: "green",
+        SEVERITY.INFO.name: "gray",
+    }
+    return mapping.get(severity.name, "black")
+
+
+class BaseItem(ABC):
+    _name: str
+    _test_result: list
+    _config: dict
+
+    def __init__(self, output_folder: str, config: Optional[dict] = None, **_kwargs) -> None:
+        self._config: dict = config or {}
+        self._test_result: list = []
+        self._logger = logging.getLogger(self.__class__.__name__)
+        self._output_folder: str = output_folder if output_folder.endswith("/") else f"{output_folder}/"
+        self._rules: dict[str, BaseRule] = {}
+
+    @abstractmethod
+    def test(self, *args, **kwargs) -> None:
+        pass
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def description(self) -> str:
+        desc: str = ""
+        for rule in self._rules.values():
+            desc += rule.description_md + "\n"
+        return desc
+
+    @property
+    def captured_sample(self) -> Optional[Union[dict, list]]:
+        try:
+            if self.cache_file_name.endswith(".gz"):
+                with gzip.open(self.cache_file_name, "rt") as f:
+                    return json_util.loads(f.read())
+            else:
+                with open(self.cache_file_name, "r", encoding="utf-8") as f:
+                    return json_util.loads(f.read())
+        except FileNotFoundError:
+            return None
+
+    @captured_sample.setter
+    def captured_sample(self, data: Union[dict, list]) -> None:
+        if self.cache_file_name.endswith(".gz"):
+            with gzip.open(self.cache_file_name, "wt") as f:
+                f.write(to_ejson(data))
+        else:
+            with open(self.cache_file_name, "w", encoding="utf-8") as f:
+                f.write(to_ejson(data))
+
+    @property
+    def test_result(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "items": self._test_result,
+        }
+
+    @property
+    def test_result_markdown(self) -> str:
+        result = ""
+        if len(self._test_result) == 0:
+            result += "<b style='color: green;'>Pass.</b>\n\n"
+            return result
+
+        result += (
+            '| <span data-sortable="false">\\#</span>{60px}'
+            ' | <span data-sortable="true">Host</span>{180px}'
+            ' | <span data-sortable="true">Severity</span>{120px}'
+            ' | <span data-sortable="true">Category</span>{200px}'
+            ' | <span data-sortable="false">Message</span>{*} |\n'
+        )
+        result += "|:----------:|:----------:|:----------:|---------|---------|\n"
+        for idx, item in enumerate(self._test_result):
+            severity = item["severity"]
+            severity_cell = (
+                f'<span data-sort-value="{severity.value}">'
+                f"<b style='color: {colorize_severity(severity)}'>"
+                f" {severity.name} </b></span>"
+            )
+            category_cell = item["title"]
+            risk = item.get("matched_risk")
+            if risk:
+                risk_id = html_mod.escape(str(risk.get("id", "")))
+                risk_name = html_mod.escape(str(risk.get("name", ""))).replace("\r\n", "<br>").replace("\n", "<br>")
+                risk_desc = (
+                    html_mod.escape(str(risk.get("description", ""))).replace("\r\n", "<br>").replace("\n", "<br>")
+                )
+                category_cell += (
+                    f' <span class="risk-badge">RISK-{risk_id}'
+                    f'<span class="risk-tooltip">'
+                    f'<span class="risk-name">{risk_name}</span>'
+                    f"{risk_desc}"
+                    f"</span></span>"
+                )
+            result += f"| **{idx + 1}** | `{item['host']}` | {severity_cell} | {category_cell} | {item['message']} |\n"
+        result += "\n"
+        return result
+
+    @property
+    def review_result(self) -> dict:
+        return {"name": self.name, "description": self.description, "data": []}
+
+    @property
+    def review_result_markdown(self) -> str:
+        result_data = self.review_result["data"]
+        result = ""
+        if len(result_data) == 0:
+            result += "(No data)\n\n"
+            return result
+        i = 0
+        for j, block in enumerate(result_data):
+            chart_type = block.get("type")
+            caption = block.get("caption")
+            notes = block.get("notes", "")
+            if chart_type == "table":
+                result += f"#### ({i + 1}) {caption}\n"
+                result += f"{notes}\n"
+                columns = block.get("columns", [])
+                header_parts = []
+                for col in columns:
+                    name = col.get("name", "(NOT SET)")
+                    sortable = col.get("sortable", True)
+                    header_parts.append(f'<span data-sortable="{"true" if sortable else "false"}">{name}</span>')
+                align = [TABLE_ALIGNMENT.get(col.get("align", "center"), TABLE_ALIGNMENT["center"]) for col in columns]
+                result += f"|{'|'.join(header_parts)}|\n"
+                result += f"|{'|'.join(align)}|\n"
+                for row in block.get("rows", []):
+                    row_text = []
+                    for cell in row:
+                        if isinstance(cell, tuple):
+                            display, sort_value = cell
+                            row_text.append(
+                                f'<span data-sort-value="{html_mod.escape(str(sort_value), quote=True)}">{display}</span>'
+                            )
+                        else:
+                            row_text.append(str(cell))
+                    result += "|" + "|".join(row_text) + "|\n"
+                result += "\n"
+                i += 1
+            elif chart_type == "chart":
+                result += f'<div id="container_{self.__class__.__name__}_{j}"></div>'
+                result += "<script type='text/javascript'>\n"
+                result += "(function() {\n"
+                result += f"const container = document.getElementById('container_{self.__class__.__name__}_{j}');\n"
+                result += f"let data = {to_json(block.get('data'))};\n"
+                file_name = f"{self.__class__.__name__}_{j}.js"
+                file_path = os.path.join("templates", "healthcheck", "snippets", file_name)
+                file_path = get_script_path(file_path, package="mongo_x_ray_hc")
+                if os.path.exists(file_path):
+                    with open(file_path, "r", encoding="utf-8") as js_file:
+                        for line in js_file:
+                            result += line.replace("{name}", self.__class__.__name__)
+                result += "})()\n"
+                result += "</script>\n"
+        return result
+
+    @property
+    def cache_file_name(self) -> str:
+        if env == "development":
+            return f"{self._output_folder}{self.__class__.__name__}_raw.json"
+        return f"{self._output_folder}{self.__class__.__name__}_raw.json.gz"
+
+    def append_test_result(self, host: str, severity: SEVERITY, title: str, message: str) -> None:
+        self._test_result.append({"host": host, "severity": severity, "title": title, "message": message})
+
+    def append_test_results(self, items: list) -> None:
+        for item in items:
+            self.append_test_result(item["host"], item["severity"], item["title"], item["description"])

mongo_x_ray_hc-2.0.0/src/mongo_x_ray_hc/check_items/build_info_item.py

@@ -0,0 +1,81 @@
+"""
+Copyright (c) 2026 MongoDB Inc.
+
+DISCLAIMER: THESE CODE SAMPLES ARE PROVIDED FOR EDUCATIONAL AND ILLUSTRATIVE PURPOSES ONLY,
+TO DEMONSTRATE THE FUNCTIONALITY OF SPECIFIC MONGODB FEATURES.
+THEY ARE NOT PRODUCTION-READY AND MAY LACK THE SECURITY HARDENING, ERROR HANDLING, AND TESTING REQUIRED FOR A LIVE ENVIRONMENT.
+YOU ARE RESPONSIBLE FOR TESTING, VALIDATING, AND SECURING THIS CODE WITHIN YOUR OWN ENVIRONMENT BEFORE IMPLEMENTATION.
+THIS MATERIAL IS PROVIDED "AS IS" WITHOUT WARRANTY OR LIABILITY.
+"""
+
+from typing import Optional
+
+from mongo_x_ray.utils import yellow
+from mongo_x_ray.version import Version
+from mongo_x_ray_hc.check_items.base_item import BaseItem
+from mongo_x_ray_hc.parsers.build_info_parser import BuildInfoParser
+from mongo_x_ray_hc.rules.version_eol_rule import VersionEOLRule
+from mongo_x_ray_hc.shared import MAX_MONGOS_PING_LATENCY, discover_nodes, enum_all_nodes, enum_result_items
+
+
+class BuildInfoItem(BaseItem):
+    """Build Info Check Item Module. Used to check MongoDB server build information."""
+
+    def __init__(self, output_folder: str, config: Optional[dict] = None):
+        super().__init__(output_folder, config)
+        self._name = "Build Information"
+        self._rules["version_eol"] = VersionEOLRule(config)
+
+    def test(self, *args, **kwargs) -> None:
+        client = kwargs.get("client")
+        parsed_uri = kwargs.get("parsed_uri")
+        nodes = discover_nodes(client, parsed_uri)
+
+        def func_node(set_name, node, **kwargs):
+            host = node["host"]
+            if "pingLatencySec" in node and node["pingLatencySec"] > MAX_MONGOS_PING_LATENCY:
+                self._logger.warning(
+                    yellow(
+                        f"Skip {host} because it has been irresponsive for {node['pingLatencySec'] / 60:.2f} minutes."
+                    )
+                )
+                return None, None
+            client = node["client"]
+            raw_result = client.admin.command("buildInfo")
+            test_result, _ = self._rules["version_eol"].apply(raw_result, extra_info={"host": host})
+            running_version = Version(raw_result.get("versionArray", None))
+            node["version"] = running_version
+            self.append_test_results(test_result)
+
+            return test_result, raw_result
+
+        raw_result = enum_all_nodes(
+            nodes,
+            func_mongos_member=func_node,
+            func_rs_member=func_node,
+            func_shard_member=func_node,
+            func_config_member=func_node,
+        )
+
+        self.captured_sample = raw_result
+
+    @property
+    def review_result_markdown(self):
+        result = self.captured_sample
+        build_infos = []
+
+        def func_node(name, node, **kwargs):
+            raw_result = node.get("rawResult", {})
+            host = node["host"]
+            build_infos.append((name, host, raw_result))
+
+        enum_result_items(
+            result,
+            func_mongos_member=func_node,
+            func_rs_member=func_node,
+            func_shard_member=func_node,
+            func_config_member=func_node,
+        )
+        parser = BuildInfoParser()
+
+        return parser.markdown(build_infos, caller=self.__class__.__name__)