{"id":29027540,"url":"https://github.com/axonops/cassandra-analyzer","last_synced_at":"2025-06-26T06:32:36.238Z","repository":{"id":301170739,"uuid":"996226764","full_name":"axonops/cassandra-analyzer","owner":"axonops","description":"Comprehensive cluster analysis tool for Apache Cassandra® powered by AxonOps. Analyzes configuration, performance, security, and   data model to provide actionable recommendations.","archived":false,"fork":false,"pushed_at":"2025-06-25T14:02:39.000Z","size":191,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T14:27:13.822Z","etag":null,"topics":["analysis","apache-cassandra","axonops","cassandra","cluster-management","database-tools","devops","diagnostics","monitoring","performance-tuning"],"latest_commit_sha":null,"homepage":"https://axonops.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axonops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-04T16:32:22.000Z","updated_at":"2025-06-25T14:02:43.000Z","dependencies_parsed_at":"2025-06-25T14:41:12.454Z","dependency_job_id":null,"html_url":"https://github.com/axonops/cassandra-analyzer","commit_stats":null,"previous_names":["axonops/cassandra-analyzer"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/axonops/cassandra-analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcassandra-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcassandra-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcassandra-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcassandra-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axonops","download_url":"https://codeload.github.com/axonops/cassandra-analyzer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonops%2Fcassandra-analyzer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262014433,"owners_count":23245127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analysis","apache-cassandra","axonops","cassandra","cluster-management","database-tools","devops","diagnostics","monitoring","performance-tuning"],"created_at":"2025-06-26T06:30:56.839Z","updated_at":"2025-06-26T06:32:36.226Z","avatar_url":"https://github.com/axonops.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"Cassandra AxonOps Analyzer Logo\" width=\"200\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCassandra® AxonOps Analyzer\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eComprehensive Cassandra Cluster Analysis Tool Powered by AxonOps™\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003e ⚠️ **DEVELOPMENT STATUS**: This project is currently under active development and is not yet ready for production use. Features may change, and stability is not guaranteed. Please wait for the official release announcement before using in production environments.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/axonops/cassandra-analyzer/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/axonops/cassandra-analyzer/issues\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues/axonops/cassandra-analyzer\" alt=\"Issues\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/axonops/cassandra-analyzer/discussions\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/discussions/axonops/cassandra-analyzer\" alt=\"Discussions\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"#installation\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/PyPI-Coming%20Soon-orange\" alt=\"PyPI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/axonops/cassandra-analyzer/actions\"\u003e\n    \u003cimg src=\"https://github.com/axonops/cassandra-analyzer/workflows/CI/badge.svg\" alt=\"CI Status\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 🚀 Overview\n\nCassandra AxonOps Analyzer is a powerful diagnostic tool that performs comprehensive analysis of Apache Cassandra clusters using the [AxonOps](https://axonops.com) monitoring platform. Unlike traditional diagnostic tools that require manual collection of logs and metrics, Cassandra AxonOps Analyzer connects directly to your AxonOps instance to provide real-time insights and recommendations.\n\n### ✨ Key Features\n\n- **🔍 Real-time Analysis** - Analyze live clusters through AxonOps API without manual data collection\n- **📊 Comprehensive Health Checks** - Infrastructure, configuration, operations, data model, and security analysis\n- **🎯 Actionable Recommendations** - Get specific, prioritized recommendations for improvements\n- **📈 Performance Insights** - Identify bottlenecks, resource constraints, and optimization opportunities\n- **🏗️ Best Practices Validation** - Ensure your cluster follows Cassandra best practices\n- **📄 Professional Reports** - Generate detailed Markdown and PDF reports for documentation\n\n### 🛠️ Analysis Categories\n\n| Category | Description |\n|----------|-------------|\n| **Infrastructure** | CPU, memory, disk usage, network metrics, and hardware recommendations |\n| **Configuration** | JVM settings, Cassandra configuration, and tuning opportunities |\n| **Operations** | Compactions, repairs, garbage collection, and operational metrics |\n| **Data Model** | Table design, partition sizes, tombstones, and schema optimizations |\n| **Security** | Authentication, authorization, encryption, and security best practices |\n\n## 📋 Requirements\n\n- Python 3.11 or higher\n- Access to [AxonOps](https://axonops.com) monitoring platform\n- AxonOps API token with appropriate permissions\n\n## 🔧 Installation\n\nYou have multiple options for installing and running Cassandra AxonOps Analyzer:\n\n### Option 1: Run Directly from Source (Recommended for Development)\n\nThis is the best option if you want to:\n- Contribute to the project\n- Always have the latest changes\n- Modify the code for your needs\n- Avoid downloading large executables\n\n```bash\n# Clone the repository\ngit clone https://github.com/axonops/cassandra-analyzer.git\ncd cassandra-analyzer\n\n# Create a virtual environment (recommended)\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install the package in development mode\npip install -r requirements.txt\npip install -e .\n\n# Run the analyzer\ncassandra-analyzer --config config.yaml\n\n# Or run directly with Python\npython -m cassandra_analyzer --config config.yaml\n```\n\n### Option 2: Install from PyPI (Coming Soon)\n\nOnce published, this will be the easiest option for regular users:\n\n```bash\n# Coming soon:\n# pip install cassandra-axonops-analyzer\n# cassandra-analyzer --config config.yaml\n```\n\n### Option 3: Use Standalone Executables (No Python Required)\n\nPerfect if you:\n- Don't have Python installed\n- Want a simple, single-file solution\n- Need to distribute to non-technical users\n\n\u003e **⚠️ Security Note**: The executables are not code-signed. Your operating system may warn you about running unsigned software. See [platform-specific instructions](#platform-specific-instructions) below for handling these warnings safely.\n\nDownload pre-built executables from the [releases page](https://github.com/axonops/cassandra-analyzer/releases):\n\n#### Direct Download\n| Platform | File | Size | Notes |\n|----------|------|------|-------|\n| **Linux** | `cassandra-analyzer-linux-amd64` | ~53MB | Works on most Linux distributions |\n| **macOS Intel** | `cassandra-analyzer-macos-amd64` | ~53MB | For Intel-based Macs |\n| **macOS Apple Silicon** | `cassandra-analyzer-macos-arm64` | ~53MB | For M1/M2/M3 Macs |\n| **Windows** | `cassandra-analyzer-windows-amd64.exe` | ~53MB | Windows 10/11 64-bit |\n\n```bash\n# Linux/macOS: Make executable and run\nchmod +x cassandra-analyzer-*\n./cassandra-analyzer-linux-amd64 --config config.yaml\n\n# Windows: Run directly\ncassandra-analyzer-windows-amd64.exe --config config.yaml\n```\n\n#### Platform-Specific Instructions\n\n\u003e **Quick Download**: Visit the [releases page](https://github.com/axonops/cassandra-analyzer/releases/latest) and download the appropriate file for your platform.\n\n##### macOS Security (Gatekeeper)\n\nmacOS will block unsigned executables. You have several options:\n\n**Option 1: Remove quarantine attribute (Recommended)**\n```bash\n# Download the latest release (or replace 'latest' with a specific version like 'v0.9.20')\n# For Apple Silicon Macs:\ncurl -L -o cassandra-analyzer https://github.com/axonops/cassandra-analyzer/releases/latest/download/cassandra-analyzer-macos-arm64\n\n# For Intel Macs:\ncurl -L -o cassandra-analyzer https://github.com/axonops/cassandra-analyzer/releases/latest/download/cassandra-analyzer-macos-amd64\n\n# Remove quarantine attribute\nxattr -d com.apple.quarantine cassandra-analyzer\n\n# Make executable and run\nchmod +x cassandra-analyzer\n./cassandra-analyzer --config config.yaml\n```\n\n**Option 2: Right-click method**\n1. Download the executable\n2. In Finder, right-click the file and select \"Open\"\n3. Click \"Open\" in the security dialog\n4. Close the terminal that opens\n5. Now you can run it normally from Terminal\n\n**Option 3: System Preferences**\n1. Try to run the executable: `./cassandra-analyzer --config config.yaml`\n2. When blocked, go to System Settings \u003e Privacy \u0026 Security\n3. Click \"Allow Anyway\" next to the cassandra-analyzer message\n4. Try running again and click \"Open\" when prompted\n\n##### Windows Security (SmartScreen)\n\nWindows may show a SmartScreen warning for unsigned executables:\n\n1. When you run the .exe file, Windows may show \"Windows protected your PC\"\n2. Click \"More info\"\n3. Click \"Run anyway\"\n\n**To avoid future warnings:**\n```powershell\n# PowerShell (as Administrator)\n# Add file to exclusion list\nAdd-MpPreference -ExclusionPath \"C:\\path\\to\\cassandra-analyzer-windows-amd64.exe\"\n```\n\n##### Linux\n\nLinux typically doesn't block unsigned binaries, but ensure it's executable:\n```bash\n# Download the latest release (or replace 'latest' with a specific version like 'v0.9.20')\nwget https://github.com/axonops/cassandra-analyzer/releases/latest/download/cassandra-analyzer-linux-amd64\n\n# Or use curl\ncurl -L -o cassandra-analyzer https://github.com/axonops/cassandra-analyzer/releases/latest/download/cassandra-analyzer-linux-amd64\n\n# Make executable\nchmod +x cassandra-analyzer-linux-amd64  # or just 'cassandra-analyzer' if you used curl\n\n# Run\n./cassandra-analyzer-linux-amd64 --config config.yaml\n```\n\nIf you get \"Permission denied\" even after chmod:\n- Check if the filesystem is mounted with `noexec`\n- Check SELinux/AppArmor policies\n- Try running from your home directory\n\n### Option 4: Linux Package Managers\n\nFor system-wide installation on Linux:\n\n**DEB (Debian/Ubuntu)**:\n```bash\n# Download and install\nwget https://github.com/axonops/cassandra-analyzer/releases/download/vX.X.X/cassandra-analyzer_X.X.X_amd64.deb\nsudo dpkg -i cassandra-analyzer_X.X.X_amd64.deb\n\n# Run from anywhere\ncassandra-analyzer --config config.yaml\n```\n\n**RPM (RHEL/CentOS/Fedora)**:\n```bash\n# Download and install\nwget https://github.com/axonops/cassandra-analyzer/releases/download/vX.X.X/cassandra-analyzer-X.X.X-1.x86_64.rpm\nsudo rpm -i cassandra-analyzer-X.X.X-1.x86_64.rpm\n\n# Run from anywhere\ncassandra-analyzer --config config.yaml\n```\n\n### Option 5: Docker (Coming Soon)\n\n```bash\n# Coming soon:\n# docker run -v $(pwd)/config.yaml:/config.yaml ghcr.io/axonops/cassandra-analyzer\n```\n\n## 🚀 Quick Start\n\n1. **Create a configuration file** (`config.yaml`):\n\n```yaml\ncluster:\n  org: \"your-organization\"\n  cluster: \"your-cluster-name\"\n  cluster_type: \"cassandra\"  # or \"dse\"\n\naxonops:\n  api_url: \"https://dash.axonops.cloud/\"\n  token: \"your-api-token\"  # Or use AXONOPS_API_TOKEN env var\n\nanalysis:\n  hours: 24  # Hours of history to analyze\n```\n\n2. **Run the analyzer**:\n\n```bash\ncassandra-analyzer --config config.yaml\n```\n\n3. **View the generated report** in the `reports` directory.\n\n## 📖 Documentation\n\n- [Build Guide](BUILD.md) - Detailed instructions for building executables, packages, and Docker images\n- [Contributing Guide](CONTRIBUTING.md) - How to contribute to the project\n- [Change Log](CHANGELOG.md) - Version history and changes\n\n### Command Line Options\n\n```bash\ncassandra-analyzer [OPTIONS]\n\nOptions:\n  --config PATH         Path to configuration file (required)\n  --output-dir PATH     Output directory for reports (default: ./reports)\n  --verbose            Enable verbose logging\n  --pdf                Generate PDF report in addition to Markdown\n  --help               Show this message and exit\n```\n\n### Environment Variables\n\n- `AXONOPS_API_TOKEN` - AxonOps API token (alternative to config file)\n- `CA_LOG_LEVEL` - Log level (DEBUG, INFO, WARNING, ERROR)\n\n### Configuration Reference\n\nSee [example_config.yaml](example_config.yaml) for a complete configuration example with all available options.\n\n## 🔬 Advanced Usage\n\n### Custom Thresholds\n\nCustomize analysis thresholds in your configuration:\n\n```yaml\nanalysis:\n  thresholds:\n    cpu_usage_warn: 80.0\n    memory_usage_warn: 85.0\n    heap_usage_warn: 75.0\n    gc_pause_warn_ms: 200\n    pending_compactions_warn: 100\n```\n\n### PDF Generation\n\n**Note**: PDF generation requires additional system dependencies that are NOT included in standalone executables.\n\n#### When Running from Source\n\nInstall WeasyPrint and its dependencies:\n\n```bash\n# Install Python packages\npip install weasyprint markdown beautifulsoup4\n\n# Install system dependencies\n# Ubuntu/Debian:\nsudo apt-get install python3-cffi python3-brotli libpango-1.0-0 libpangoft2-1.0-0\n\n# macOS:\nbrew install pango\n\n# Then run with --pdf flag\ncassandra-analyzer --config config.yaml --pdf\n```\n\n#### When Using Standalone Executables\n\nPDF generation is **NOT available** in standalone executables due to system dependencies. Options:\n\n1. **Use Markdown output** (default) and convert separately:\n   ```bash\n   # Generate markdown report\n   ./cassandra-analyzer --config config.yaml\n   \n   # Convert using pandoc or other tools\n   pandoc reports/report.md -o report.pdf\n   ```\n\n2. **Run from source** if you need PDF generation\n\n3. **Use Docker** (includes all dependencies) - coming soon\n\n### Programmatic Usage\n\n```python\nfrom cassandra_analyzer import CassandraAnalyzer\nfrom cassandra_analyzer.config import Config\n\nconfig = Config.from_file(\"config.yaml\")\nanalyzer = CassandraAnalyzer(config)\nreport = analyzer.analyze()\n```\n\n## 🏗️ Architecture\n\n```\ncassandra-analyzer/\n├── analyzers/         # Analysis modules\n├── client/           # AxonOps API client\n├── collectors/       # Data collection\n├── models/          # Data models\n├── reports/         # Report generation\n└── utils/           # Utilities\n```\n\n## 🧪 Development\n\n### Quick Start for Developers\n\n```bash\n# Clone the repository\ngit clone https://github.com/axonops/cassandra-analyzer.git\ncd cassandra-analyzer\n\n# Create and activate a virtual environment\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\nmake install-dev\n\n# Run the project directly from source\npython -m cassandra_analyzer --config config.yaml\n\n# Run tests\nmake test\n\n# Run linting\nmake lint\n\n# Run all CI checks locally\nmake ci\n```\n\n### Available Make Commands\n\n```bash\nmake help         # Show all available commands\nmake install      # Install production dependencies\nmake install-dev  # Install development dependencies\nmake test         # Run unit tests\nmake test-coverage # Run tests with coverage report\nmake lint         # Run code linters\nmake format       # Auto-format code\nmake type-check   # Run type checking\nmake security-check # Run security scan\nmake build        # Build Python distribution packages\nmake build-exe    # Build standalone executable for your platform\nmake build-exe-onedir # Build executable in folder mode (for debugging)\nmake docker-build # Build Docker image\nmake run-example  # Run with example configuration\nmake clean        # Clean all build artifacts\nmake ci           # Run all CI checks locally\n```\n\n### Building Executables\n\nThe project supports building standalone executables that bundle Python and all dependencies:\n\n```bash\n# Install development dependencies (includes PyInstaller)\nmake install-dev\n\n# Build executable for your current platform\nmake build-exe\n\n# The executable will be in dist/\n# Linux/macOS: dist/cassandra-analyzer\n# Windows: dist/cassandra-analyzer.exe\n\n# Test the executable\n./dist/cassandra-analyzer --help\n\n# Build in one-folder mode (useful for debugging)\nmake build-exe-onedir\n```\n\n**Note**: Executables are platform-specific. You can only build for the platform you're currently on. For cross-platform builds, use the GitHub Actions release workflow.\n\n### Testing\n\nThe project uses pytest for testing and follows Test-Driven Development (TDD) principles:\n\n```bash\n# Run all tests\npytest\n\n# Run specific test file\npytest tests/test_infrastructure_analyzer.py\n\n# Run with coverage\npytest --cov=cassandra_analyzer --cov-report=html\n\n# Run tests in watch mode\npytest-watch\n\n# Test multiple Python versions\ntox\n```\n\n### Building from Source\n\nFor detailed build instructions including executables, packages, and Docker images, see our [Build Guide](BUILD.md).\n\nQuick build commands:\n\n```bash\n# Build Python packages\nmake build\n\n# Build standalone executable\nmake build-exe\n\n# Build Docker image\nmake docker-build\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests first (TDD)\n4. Implement your feature\n5. Ensure all tests pass (`make test`)\n6. Check code quality (`make lint`)\n7. Commit your changes (`git commit -m 'Add amazing feature'`)\n8. Push to the branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Community \u0026 Support\n\n### Get Involved\n\n- 💡 **Share Ideas**: Visit our [GitHub Discussions](https://github.com/axonops/cassandra-analyzer/discussions) to propose new features\n- 🐛 **Report Issues**: Found a bug? [Open an issue](https://github.com/axonops/cassandra-analyzer/issues)\n- 🤝 **Contribute**: We welcome pull requests! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines\n- ⭐ **Star Us**: If you find Cassandra AxonOps Analyzer useful, please star our repository!\n\n### Stay Connected\n\n- 🌐 **Website**: [axonops.com](https://axonops.com)\n- 📧 **Contact**: Visit our website for support options\n\n## 🙏 Acknowledgements\n\nCassandra AxonOps Analyzer builds upon the foundation laid by several open-source projects, particularly Apache Cassandra. We extend our sincere gratitude to the Apache Cassandra community for their outstanding work and contributions to the field of distributed databases.\n\nApache Cassandra is a free and open-source, distributed, wide-column store, NoSQL database management system designed to handle large amounts of data across many commodity servers, providing high availability with no single point of failure.\n\n### Apache Cassandra Resources\n\n- **Official Website**: [cassandra.apache.org](https://cassandra.apache.org)\n- **Source Code**: Available on [GitHub](https://github.com/apache/cassandra) or the Apache Git repository at [gitbox.apache.org/repos/asf/cassandra.git](https://gitbox.apache.org/repos/asf/cassandra.git)\n- **Documentation**: Comprehensive guides and references available at the [Apache Cassandra website](https://cassandra.apache.org/doc/latest/)\n\nCassandra AxonOps Analyzer incorporates and extends functionality from various Cassandra tools and utilities, enhancing them to provide comprehensive cluster analysis capabilities for Cassandra operators and DBAs.\n\nWe encourage users to explore and contribute to the main Apache Cassandra project, as well as to provide feedback and suggestions for Cassandra AxonOps Analyzer through our GitHub discussions and issues pages.\n\n## ⚖️ Legal Notices\n\nThis project may contain trademarks or logos for projects, products, or services. Any use of third-party trademarks or logos are subject to those third-party's policies.\n\n**Important**: This project is not affiliated with, endorsed by, or sponsored by the Apache Software Foundation or the Apache Cassandra project. It is an independent tool developed by [AxonOps](https://axonops.com) to analyze Apache Cassandra clusters.\n\n- **AxonOps** is a registered trademark of AxonOps Limited.\n- **Apache**, **Apache Cassandra**, **Cassandra**, **Apache Spark**, **Spark**, **Apache TinkerPop**, **TinkerPop**, **Apache Kafka** and **Kafka** are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by the AxonOps Team\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonops%2Fcassandra-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxonops%2Fcassandra-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonops%2Fcassandra-analyzer/lists"}