Download the PHP package run-as-root/magento2-prometheus-exporter without Composer

Magento 2 Prometheus Exporter

A comprehensive Magento 2 module that exposes essential Magento metrics in Prometheus format, enabling powerful monitoring and observability for your e-commerce platform.

🚀 Features

• 📊 Rich Metrics Collection: Monitors orders, products, customers, CMS content, cron jobs, indexers, and more
• 🔧 Configurable Metrics: Enable/disable specific metrics through Magento admin interface
• 🔐 Secure Access: Bearer token authentication support to protect your metrics endpoint
• ⚡ Performance Optimized: Efficient cron-based data aggregation to minimize performance impact
• 🎯 Prometheus Ready: Native Prometheus format output for seamless integration
• 🔌 Extensible Architecture: Easy to add custom metrics with clean interfaces

📋 Table of Contents

• Installation
• Configuration
• Prometheus Setup
• Available Metrics
• Security
• Custom Metrics
• CLI Commands
• Architecture
• Troubleshooting
• Contributing
• License

📦 Installation

Requirements

• Magento 2.3.x or higher
• PHP 8.2 or higher
• Composer

Install via Composer

Verify Installation

After installation, your metrics endpoint will be available at:

⚙️ Configuration

Admin Configuration

Navigate to Stores → Configuration → Prometheus → Metric Configuration to:

• Enable/disable specific metric collectors
• Configure authentication settings
• Set collection intervals
• Manage metric labels and groupings

Cron Configuration

The 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.

The four order aggregators (magento_orders_amount_total, magento_orders_count_total, magento_orders_items_amount_total, magento_orders_items_count_total) each run a full scan of sales_order / sales_order_item, which is too expensive to repeat every minute on a large store. They are therefore throttled to once every 5 minutes. Their values stay constant between runs, which is correct for a gauge. All other aggregators still run on every cron tick.

The throttle remembers the last successful run in the Magento cache without a cache tag, so bin/magento cache:clean leaves it in place and only bin/magento cache:flush clears it. To force one metric to recompute right away, use bin/magento run_as_root:metric:collect --only=<metric_code>, which ignores the throttle.

🎯 Prometheus Setup

Basic Configuration

Add the following scrape configuration to your prometheus.yml:

With Authentication

For production environments, secure your metrics endpoint:

Advanced Configuration with Labels

📊 Available Metrics

Order Metrics

Product & Catalog Metrics

EAV & Attribute Metrics

Customer Metrics

Content Metrics

System Health Metrics

Infrastructure Metrics

🔐 Security

Authentication Setup

1. Generate Bearer Token: Navigate to Magento Admin → System → Integrations
2. Create New Integration: Set up API access with appropriate permissions
3. Configure Token: Use the generated access token in your Prometheus configuration

Best Practices

• Always use HTTPS for metrics endpoints in production
• Regularly rotate authentication tokens
• Restrict access to metrics endpoint via firewall rules
• Monitor access logs for unusual activity

IP Whitelisting

Consider restricting access to your Prometheus server IPs:

🔧 Custom Metrics

Creating a Custom Metric Aggregator

1. Implement the Interface:

2. Register in DI Configuration (etc/di.xml):

Example: Product Rating Aggregator

💻 CLI Commands

Collect Metrics Manually

View Current Metrics

Clear Metrics Data

🏗️ Architecture

Data Flow

1. Cron Execution: Every minute, the run_as_root_prometheus_metrics_aggregator cron group executes
2. Metric Aggregation: Each enabled aggregator collects and processes data
3. Data Storage: Aggregated metrics are stored in run_as_root_prometheus_metrics table
4. Endpoint Response: /metrics controller serves data in Prometheus format

Key Components

• MetricAggregatorInterface: Contract for all metric collectors
• MetricAggregatorPool: Registry of all available aggregators
• UpdateMetricService: Service for storing metric data
• PrometheusController: HTTP endpoint for serving metrics

Database Schema

The module creates a dedicated table run_as_root_prometheus_metrics with the following structure:

• metric_id: Primary key
• metric_code: Unique metric identifier
• metric_value: Numeric value
• metric_type: Type (gauge, counter, histogram)
• metric_help: Description text
• metric_labels: JSON-encoded labels
• updated_at: Last update timestamp

🔍 Troubleshooting

Common Issues

Metrics Not Updating

Permission Denied on /metrics

• Verify web server has read access to Magento files
• Check Magento file permissions: find . -type f -exec chmod 644 {} \;
• Ensure proper ownership: chown -R www-data:www-data .

High Memory Usage

• Reduce collection frequency in cron configuration
• Disable unused metric aggregators in admin configuration
• Consider implementing metric data retention policies

Debug Mode

Enable debug logging by adding to app/etc/env.php:

Performance Monitoring

Monitor the impact of metric collection:

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://gitlab.com/your-username/magento2-prometheus-exporter.git
3. Install dependencies: composer install
4. Create a feature branch: git checkout -b feature/your-feature-name

Code Standards

• Follow Magento 2 coding standards
• Write unit tests for new features
• Update documentation for new metrics or features
• Use meaningful commit messages

Pull Request Process

1. Ensure all tests pass: vendor/bin/phpunit
2. Update the CHANGELOG.md
3. Submit a pull request with a clear description
4. Respond to code review feedback

Reporting Issues

Please include:

• Magento version
• PHP version
• Module version
• Detailed error messages
• Steps to reproduce

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• run_as_root GmbH - Original development and maintenance
• Prometheus Community - For the excellent monitoring toolkit
• Magento Community - For feedback and contributions

📞 Support

• Email: [email protected]
• GitLab Issues: Report a bug
• Documentation: Wiki

Made with ❤️ by run_as_root