{"id":13518549,"url":"https://github.com/run-as-root/magento2-prometheus-exporter","last_synced_at":"2025-12-26T00:10:49.965Z","repository":{"id":45601410,"uuid":"191891355","full_name":"run-as-root/magento2-prometheus-exporter","owner":"run-as-root","description":"Simple Magento 2 Prometheus Exporter.","archived":false,"fork":false,"pushed_at":"2024-11-12T11:42:28.000Z","size":397,"stargazers_count":65,"open_issues_count":7,"forks_count":21,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-28T19:58:19.925Z","etag":null,"topics":["magento","magento-extension","magento-module","magento2","magento2-extension","magento2-module","metrics","prometheus","prometheus-exporter","prometheus-metrics"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/run-as-root.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2019-06-14T06:53:05.000Z","updated_at":"2025-03-23T00:16:51.000Z","dependencies_parsed_at":"2022-08-24T07:20:13.761Z","dependency_job_id":"2a710883-1e56-49cf-8757-e3274844981a","html_url":"https://github.com/run-as-root/magento2-prometheus-exporter","commit_stats":{"total_commits":239,"total_committers":15,"mean_commits":"15.933333333333334","dds":0.5941422594142259,"last_synced_commit":"8833d6b52ba2c84e9a89b0dd4c5a84bc7cb347e0"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/run-as-root%2Fmagento2-prometheus-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/run-as-root%2Fmagento2-prometheus-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/run-as-root%2Fmagento2-prometheus-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/run-as-root%2Fmagento2-prometheus-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/run-as-root","download_url":"https://codeload.github.com/run-as-root/magento2-prometheus-exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246453676,"owners_count":20779992,"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":["magento","magento-extension","magento-module","magento2","magento2-extension","magento2-module","metrics","prometheus","prometheus-exporter","prometheus-metrics"],"created_at":"2024-08-01T05:01:46.124Z","updated_at":"2025-12-26T00:10:49.959Z","avatar_url":"https://github.com/run-as-root.png","language":"PHP","funding_links":[],"categories":["PHP","Open Source Extensions"],"sub_categories":["Development Utilities"],"readme":"# Magento 2 Prometheus Exporter\n\n[![pipeline status](https://gitlab.com/run_as_root/magento2-prometheus-exporter/badges/master/pipeline.svg)](https://gitlab.com/run_as_root/magento2-prometheus-exporter/commits/master)\n\nA comprehensive Magento 2 module that exposes essential Magento metrics in Prometheus format, enabling powerful monitoring and observability for your e-commerce platform.\n\n## 🚀 Features\n\n- **📊 Rich Metrics Collection**: Monitors orders, products, customers, CMS content, cron jobs, indexers, and more\n- **🔧 Configurable Metrics**: Enable/disable specific metrics through Magento admin interface\n- **🔐 Secure Access**: Bearer token authentication support to protect your metrics endpoint\n- **⚡ Performance Optimized**: Efficient cron-based data aggregation to minimize performance impact\n- **🎯 Prometheus Ready**: Native Prometheus format output for seamless integration\n- **🔌 Extensible Architecture**: Easy to add custom metrics with clean interfaces\n\n## 📋 Table of Contents\n\n- [Installation](#-installation)\n- [Configuration](#-configuration)\n- [Prometheus Setup](#-prometheus-setup)\n- [Available Metrics](#-available-metrics)\n- [Security](#-security)\n- [Custom Metrics](#-custom-metrics)\n- [CLI Commands](#-cli-commands)\n- [Architecture](#-architecture)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 📦 Installation\n\n### Requirements\n\n- Magento 2.3.x or higher\n- PHP 7.4 or higher\n- Composer\n\n### Install via Composer\n\n```bash\ncomposer require run_as_root/magento2-prometheus-exporter\nphp bin/magento setup:upgrade\nphp bin/magento setup:di:compile\nphp bin/magento cache:flush\n```\n\n### Verify Installation\n\nAfter installation, your metrics endpoint will be available at:\n```\nhttps://your-magento-store.com/metrics\n```\n\n## ⚙️ Configuration\n\n### Admin Configuration\n\nNavigate to **Stores → Configuration → Prometheus → Metric Configuration** to:\n\n- Enable/disable specific metric collectors\n- Configure authentication settings\n- Set collection intervals\n- Manage metric labels and groupings\n\n### Cron Configuration\n\nThe module automatically registers a cron job that runs every minute to aggregate metrics. The job uses a dedicated cron group: `run_as_root_prometheus_metrics_aggregator`.\n\n## 🎯 Prometheus Setup\n\n### Basic Configuration\n\nAdd the following scrape configuration to your `prometheus.yml`:\n\n```yaml\nscrape_configs:\n  - job_name: 'magento-2'\n    scrape_interval: 5m\n    scrape_timeout: 60s\n    metrics_path: /metrics\n    static_configs:\n      - targets: \n          - 'your-magento-store.com'\n```\n\n### With Authentication\n\nFor production environments, secure your metrics endpoint:\n\n```yaml\nscrape_configs:\n  - job_name: 'magento-2'\n    scrape_interval: 5m\n    scrape_timeout: 60s\n    metrics_path: /metrics\n    authorization:\n      type: 'Bearer'\n      credentials: 'your-bearer-token-here'\n    static_configs:\n      - targets: \n          - 'your-magento-store.com'\n```\n\n### Advanced Configuration with Labels\n\n```yaml\nscrape_configs:\n  - job_name: 'magento-2'\n    scrape_interval: 5m\n    scrape_timeout: 60s\n    metrics_path: /metrics\n    authorization:\n      type: 'Bearer'\n      credentials: 'your-bearer-token-here'\n    static_configs:\n      - targets: \n          - 'your-magento-store.com'\n    relabel_configs:\n      - source_labels: [__address__]\n        target_label: instance\n        replacement: 'magento-production'\n```\n\n## 📊 Available Metrics\n\n### Order Metrics\n| Metric | Type | Labels | Description |\n|--------|------|--------|-------------|\n| `magento_orders_count_total` | gauge | `status`, `store_code` | Total count of orders by status and store |\n| `magento_orders_amount_total` | gauge | `status`, `store_code` | Total revenue by order status and store |\n| `magento_order_items_count_total` | gauge | `status`, `store_code` | Total count of order items |\n\n### Product \u0026 Catalog Metrics\n| Metric | Type | Labels | Description |\n|--------|------|--------|-------------|\n| `magento_products_by_type_count_total` | gauge | `product_type` | Count of products by type (simple, configurable, etc.) |\n| `magento_catalog_category_count_total` | gauge | `status`, `menu_status`, `store_code` | Count of categories by status |\n\n### EAV \u0026 Attribute Metrics\n| Metric | Type | Labels | Description |\n|--------|------|--------|-------------|\n| `magento_eav_attribute_count_total` | gauge | - | Total count of EAV attributes |\n| `magento_eav_attribute_options_above_recommended_level_total` | gauge | - | Count of attributes with more than 100 options (performance risk) |\n\n### Customer Metrics\n| Metric | Type | Labels | Description |\n|--------|------|--------|-------------|\n| `magento_customer_count_total` | gauge | `store_code` | Total count of registered customers |\n\n### Content Metrics\n| Metric | Type | Labels | Description |\n|--------|------|--------|-------------|\n| `magento_cms_block_count_total` | gauge | `store_code` | Count of CMS blocks |\n| `magento_cms_page_count_total` | gauge | `store_code` | Count of CMS pages |\n\n### System Health Metrics\n| Metric | Type | Labels | Description |\n|--------|------|--------|-------------|\n| `magento_cronjob_count_total` | gauge | `status`, `job_code` | Count of cron jobs by status |\n| `magento_cronjob_broken_count_total` | gauge | - | Count of broken cron jobs |\n| `magento_indexer_backlog_count_total` | gauge | `title` | Count of items in indexer backlog |\n\n### Infrastructure Metrics\n| Metric | Type | Labels | Description |\n|--------|------|--------|-------------|\n| `magento_store_count_total` | gauge | `status` | Count of stores by status |\n| `magento_website_count_total` | gauge | - | Total count of websites |\n| `magento_shipments_count_total` | counter | `source`, `store_code` | Count of shipments created |\n\n## 🔐 Security\n\n### Authentication Setup\n\n1. **Generate Bearer Token**: Navigate to Magento Admin → System → Integrations\n2. **Create New Integration**: Set up API access with appropriate permissions\n3. **Configure Token**: Use the generated access token in your Prometheus configuration\n\n### Best Practices\n\n- Always use HTTPS for metrics endpoints in production\n- Regularly rotate authentication tokens\n- Restrict access to metrics endpoint via firewall rules\n- Monitor access logs for unusual activity\n\n### IP Whitelisting\n\nConsider restricting access to your Prometheus server IPs:\n\n```nginx\nlocation /metrics {\n    allow 10.0.0.0/8;     # Your Prometheus server\n    allow 172.16.0.0/12;  # Internal network\n    deny all;\n    try_files $uri $uri/ /index.php?$args;\n}\n```\n\n## 🔧 Custom Metrics\n\n### Creating a Custom Metric Aggregator\n\n1. **Implement the Interface**:\n\n```php\n\u003c?php\nnamespace YourNamespace\\YourModule\\Aggregator;\n\nuse RunAsRoot\\PrometheusExporter\\Api\\MetricAggregatorInterface;\nuse RunAsRoot\\PrometheusExporter\\Service\\UpdateMetricService;\n\nclass CustomMetricAggregator implements MetricAggregatorInterface\n{\n    private UpdateMetricService $updateMetricService;\n\n    public function __construct(UpdateMetricService $updateMetricService)\n    {\n        $this-\u003eupdateMetricService = $updateMetricService;\n    }\n\n    public function aggregate(): void\n    {\n        // Your metric collection logic here\n        $value = $this-\u003ecalculateCustomMetric();\n        \n        $this-\u003eupdateMetricService-\u003eupdate(\n            'your_custom_metric_total',\n            (string) $value,\n            'gauge',\n            'Description of your custom metric',\n            ['label1' =\u003e 'value1', 'label2' =\u003e 'value2']\n        );\n    }\n\n    private function calculateCustomMetric(): int\n    {\n        // Implement your metric calculation\n        return 42;\n    }\n}\n```\n\n2. **Register in DI Configuration** (`etc/di.xml`):\n\n```xml\n\u003ctype name=\"RunAsRoot\\PrometheusExporter\\Metric\\MetricAggregatorPool\"\u003e\n    \u003carguments\u003e\n        \u003cargument name=\"items\" xsi:type=\"array\"\u003e\n            \u003citem name=\"YourCustomAggregator\" xsi:type=\"object\"\u003eYourNamespace\\YourModule\\Aggregator\\CustomMetricAggregator\u003c/item\u003e\n        \u003c/argument\u003e\n    \u003c/arguments\u003e\n\u003c/type\u003e\n```\n\n### Example: Product Rating Aggregator\n\n```php\n\u003c?php\nnamespace YourNamespace\\YourModule\\Aggregator;\n\nuse Magento\\Review\\Model\\ResourceModel\\Review\\CollectionFactory;\nuse RunAsRoot\\PrometheusExporter\\Api\\MetricAggregatorInterface;\nuse RunAsRoot\\PrometheusExporter\\Service\\UpdateMetricService;\n\nclass ProductRatingAggregator implements MetricAggregatorInterface\n{\n    private CollectionFactory $reviewCollectionFactory;\n    private UpdateMetricService $updateMetricService;\n\n    public function __construct(\n        CollectionFactory $reviewCollectionFactory,\n        UpdateMetricService $updateMetricService\n    ) {\n        $this-\u003ereviewCollectionFactory = $reviewCollectionFactory;\n        $this-\u003eupdateMetricService = $updateMetricService;\n    }\n\n    public function aggregate(): void\n    {\n        $collection = $this-\u003ereviewCollectionFactory-\u003ecreate()\n            -\u003eaddStatusFilter(\\Magento\\Review\\Model\\Review::STATUS_APPROVED);\n\n        $averageRating = $collection-\u003egetConnection()\n            -\u003efetchOne('SELECT AVG(rating_value) FROM rating_option_vote');\n\n        $this-\u003eupdateMetricService-\u003eupdate(\n            'magento_product_average_rating',\n            (string) round($averageRating, 2),\n            'gauge',\n            'Average product rating across all approved reviews'\n        );\n    }\n}\n```\n\n## 💻 CLI Commands\n\n### Collect Metrics Manually\n\n```bash\nphp bin/magento run_as_root:metrics:collect\n```\n\n### View Current Metrics\n\n```bash\nphp bin/magento run_as_root:metrics:show\n```\n\n### Clear Metrics Data\n\n```bash\nphp bin/magento run_as_root:metrics:clear\n```\n\n## 🏗️ Architecture\n\n### Data Flow\n\n1. **Cron Execution**: Every minute, the `run_as_root_prometheus_metrics_aggregator` cron group executes\n2. **Metric Aggregation**: Each enabled aggregator collects and processes data\n3. **Data Storage**: Aggregated metrics are stored in `run_as_root_prometheus_metrics` table\n4. **Endpoint Response**: `/metrics` controller serves data in Prometheus format\n\n### Key Components\n\n- **MetricAggregatorInterface**: Contract for all metric collectors\n- **MetricAggregatorPool**: Registry of all available aggregators\n- **UpdateMetricService**: Service for storing metric data\n- **PrometheusController**: HTTP endpoint for serving metrics\n\n### Database Schema\n\nThe module creates a dedicated table `run_as_root_prometheus_metrics` with the following structure:\n\n- `metric_id`: Primary key\n- `metric_code`: Unique metric identifier\n- `metric_value`: Numeric value\n- `metric_type`: Type (gauge, counter, histogram)\n- `metric_help`: Description text\n- `metric_labels`: JSON-encoded labels\n- `updated_at`: Last update timestamp\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n#### Metrics Not Updating\n```bash\n# Check cron status\nphp bin/magento cron:status\n\n# Run metrics collection manually\nphp bin/magento run_as_root:metrics:collect\n\n# Check system logs\ntail -f var/log/system.log | grep prometheus\n```\n\n#### Permission Denied on /metrics\n- Verify web server has read access to Magento files\n- Check Magento file permissions: `find . -type f -exec chmod 644 {} \\;`\n- Ensure proper ownership: `chown -R www-data:www-data .`\n\n#### High Memory Usage\n- Reduce collection frequency in cron configuration\n- Disable unused metric aggregators in admin configuration\n- Consider implementing metric data retention policies\n\n### Debug Mode\n\nEnable debug logging by adding to `app/etc/env.php`:\n\n```php\n'system' =\u003e [\n    'default' =\u003e [\n        'prometheus_exporter' =\u003e [\n            'debug' =\u003e '1'\n        ]\n    ]\n]\n```\n\n### Performance Monitoring\n\nMonitor the impact of metric collection:\n\n```bash\n# Check metric collection execution time\ngrep \"prometheus.*aggregator\" var/log/system.log\n\n# Monitor database table size\nSELECT COUNT(*) as total_metrics, \n       MAX(updated_at) as last_update \nFROM run_as_root_prometheus_metrics;\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n### Development Setup\n\n1. Fork the repository\n2. Clone your fork: `git clone https://gitlab.com/your-username/magento2-prometheus-exporter.git`\n3. Install dependencies: `composer install`\n4. Create a feature branch: `git checkout -b feature/your-feature-name`\n\n### Code Standards\n\n- Follow Magento 2 coding standards\n- Write unit tests for new features\n- Update documentation for new metrics or features\n- Use meaningful commit messages\n\n### Pull Request Process\n\n1. Ensure all tests pass: `vendor/bin/phpunit`\n2. Update the CHANGELOG.md\n3. Submit a pull request with a clear description\n4. Respond to code review feedback\n\n### Reporting Issues\n\nPlease include:\n- Magento version\n- PHP version\n- Module version\n- Detailed error messages\n- Steps to reproduce\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **run_as_root GmbH** - Original development and maintenance\n- **Prometheus Community** - For the excellent monitoring toolkit\n- **Magento Community** - For feedback and contributions\n\n## 📞 Support\n\n- **Email**: info@run-as-root.sh\n- **GitLab Issues**: [Report a bug](https://gitlab.com/run_as_root/magento2-prometheus-exporter/issues)\n- **Documentation**: [Wiki](https://gitlab.com/run_as_root/magento2-prometheus-exporter/wiki)\n\n---\n\n**Made with ❤️ by [run_as_root](https://www.run-as-root.sh)**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frun-as-root%2Fmagento2-prometheus-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frun-as-root%2Fmagento2-prometheus-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frun-as-root%2Fmagento2-prometheus-exporter/lists"}