README

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

📦 Installation

Requirements

Magento 2.3.x or higher
PHP 7.4 or higher
Composer

Install via Composer

composer require run_as_root/magento2-prometheus-exporter
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

Verify Installation

After installation, your metrics endpoint will be available at:

https://your-magento-store.com/metrics

⚙️ 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.

🎯 Prometheus Setup

Basic Configuration

Add the following scrape configuration to your prometheus.yml:

scrape_configs:
  - job_name: 'magento-2'
    scrape_interval: 5m
    scrape_timeout: 60s
    metrics_path: /metrics
    static_configs:
      - targets: 
          - 'your-magento-store.com'

With Authentication

For production environments, secure your metrics endpoint:

scrape_configs:
  - job_name: 'magento-2'
    scrape_interval: 5m
    scrape_timeout: 60s
    metrics_path: /metrics
    authorization:
      type: 'Bearer'
      credentials: 'your-bearer-token-here'
    static_configs:
      - targets: 
          - 'your-magento-store.com'

Advanced Configuration with Labels

scrape_configs:
  - job_name: 'magento-2'
    scrape_interval: 5m
    scrape_timeout: 60s
    metrics_path: /metrics
    authorization:
      type: 'Bearer'
      credentials: 'your-bearer-token-here'
    static_configs:
      - targets: 
          - 'your-magento-store.com'
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
        replacement: 'magento-production'

📊 Available Metrics

Order Metrics

Metric	Type	Labels	Description
`magento_orders_count_total`	gauge	`status`, `store_code`	Total count of orders by status and store
`magento_orders_amount_total`	gauge	`status`, `store_code`	Total revenue by order status and store
`magento_order_items_count_total`	gauge	`status`, `store_code`	Total count of order items

Product & Catalog Metrics

Metric	Type	Labels	Description
`magento_products_by_type_count_total`	gauge	`product_type`	Count of products by type (simple, configurable, etc.)
`magento_catalog_category_count_total`	gauge	`status`, `menu_status`, `store_code`	Count of categories by status

EAV & Attribute Metrics

Metric	Type	Labels	Description
`magento_eav_attribute_count_total`	gauge	-	Total count of EAV attributes
`magento_eav_attribute_options_above_recommended_level_total`	gauge	-	Count of attributes with more than 100 options (performance risk)

Customer Metrics

Metric	Type	Labels	Description
`magento_customer_count_total`	gauge	`store_code`	Total count of registered customers

Content Metrics

Metric	Type	Labels	Description
`magento_cms_block_count_total`	gauge	`store_code`	Count of CMS blocks
`magento_cms_page_count_total`	gauge	`store_code`	Count of CMS pages

System Health Metrics

Metric	Type	Labels	Description
`magento_cronjob_count_total`	gauge	`status`, `job_code`	Count of cron jobs by status
`magento_cronjob_broken_count_total`	gauge	-	Count of broken cron jobs
`magento_indexer_backlog_count_total`	gauge	`title`	Count of items in indexer backlog

Infrastructure Metrics

Metric	Type	Labels	Description
`magento_store_count_total`	gauge	`status`	Count of stores by status
`magento_website_count_total`	gauge	-	Total count of websites
`magento_shipments_count_total`	counter	`source`, `store_code`	Count of shipments created

🔐 Security

Authentication Setup

Generate Bearer Token: Navigate to Magento Admin → System → Integrations
Create New Integration: Set up API access with appropriate permissions
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:

location /metrics {
    allow 10.0.0.0/8;     # Your Prometheus server
    allow 172.16.0.0/12;  # Internal network
    deny all;
    try_files $uri $uri/ /index.php?$args;
}

🔧 Custom Metrics

Creating a Custom Metric Aggregator

Implement the Interface:

<?php
namespace YourNamespace\YourModule\Aggregator;

use RunAsRoot\PrometheusExporter\Api\MetricAggregatorInterface;
use RunAsRoot\PrometheusExporter\Service\UpdateMetricService;

class CustomMetricAggregator implements MetricAggregatorInterface
{
    private UpdateMetricService $updateMetricService;

    public function __construct(UpdateMetricService $updateMetricService)
    {
        $this->updateMetricService = $updateMetricService;
    }

    public function aggregate(): void
    {
        // Your metric collection logic here
        $value = $this->calculateCustomMetric();
        
        $this->updateMetricService->update(
            'your_custom_metric_total',
            (string) $value,
            'gauge',
            'Description of your custom metric',
            ['label1' => 'value1', 'label2' => 'value2']
        );
    }

    private function calculateCustomMetric(): int
    {
        // Implement your metric calculation
        return 42;
    }
}

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

<type name="RunAsRoot\PrometheusExporter\Metric\MetricAggregatorPool">
    <arguments>
        <argument name="items" xsi:type="array">
            <item name="YourCustomAggregator" xsi:type="object">YourNamespace\YourModule\Aggregator\CustomMetricAggregator</item>
        </argument>
    </arguments>
</type>

Example: Product Rating Aggregator

<?php
namespace YourNamespace\YourModule\Aggregator;

use Magento\Review\Model\ResourceModel\Review\CollectionFactory;
use RunAsRoot\PrometheusExporter\Api\MetricAggregatorInterface;
use RunAsRoot\PrometheusExporter\Service\UpdateMetricService;

class ProductRatingAggregator implements MetricAggregatorInterface
{
    private CollectionFactory $reviewCollectionFactory;
    private UpdateMetricService $updateMetricService;

    public function __construct(
        CollectionFactory $reviewCollectionFactory,
        UpdateMetricService $updateMetricService
    ) {
        $this->reviewCollectionFactory = $reviewCollectionFactory;
        $this->updateMetricService = $updateMetricService;
    }

    public function aggregate(): void
    {
        $collection = $this->reviewCollectionFactory->create()
            ->addStatusFilter(\Magento\Review\Model\Review::STATUS_APPROVED);

        $averageRating = $collection->getConnection()
            ->fetchOne('SELECT AVG(rating_value) FROM rating_option_vote');

        $this->updateMetricService->update(
            'magento_product_average_rating',
            (string) round($averageRating, 2),
            'gauge',
            'Average product rating across all approved reviews'
        );
    }
}

💻 CLI Commands

Collect Metrics Manually

php bin/magento run_as_root:metrics:collect

View Current Metrics

php bin/magento run_as_root:metrics:show

Clear Metrics Data

php bin/magento run_as_root:metrics:clear

🏗️ Architecture

Data Flow

Cron Execution: Every minute, the run_as_root_prometheus_metrics_aggregator cron group executes
Metric Aggregation: Each enabled aggregator collects and processes data
Data Storage: Aggregated metrics are stored in run_as_root_prometheus_metrics table
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

# Check cron status
php bin/magento cron:status

# Run metrics collection manually
php bin/magento run_as_root:metrics:collect

# Check system logs
tail -f var/log/system.log | grep prometheus

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:

'system' => [
    'default' => [
        'prometheus_exporter' => [
            'debug' => '1'
        ]
    ]
]

Performance Monitoring

Monitor the impact of metric collection:

# Check metric collection execution time
grep "prometheus.*aggregator" var/log/system.log

# Monitor database table size
SELECT COUNT(*) as total_metrics, 
       MAX(updated_at) as last_update 
FROM run_as_root_prometheus_metrics;

🤝 Contributing

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

Development Setup

Fork the repository
Clone your fork: git clone https://gitlab.com/your-username/magento2-prometheus-exporter.git
Install dependencies: composer install
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

Ensure all tests pass: vendor/bin/phpunit
Update the CHANGELOG.md
Submit a pull request with a clear description
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: info@run-as-root.sh
GitLab Issues: Report a bug
Documentation: Wiki

Made with ❤️ by run_as_root

run-as-root / magento2-prometheus-exporter

Maintainers

Details