# run_as_root/magento2-prometheus-exporter

> Magento2 Prometheus Exporter

`composer require run_as_root/magento2-prometheus-exporter`

Canonical URL: https://packagento.com/run_as_root/magento2-prometheus-exporter

## At a glance

- **Vendor**: run_as_root (https://packagento.com/run_as_root.md)
- **Latest version**: 4.1.0 — released 2026-05-28
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/run_as_root/magento2-prometheus-exporter and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

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

## What it does

Magento2 Prometheus Exporter

## README

[![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)

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](#-installation)
- [Configuration](#-configuration)
- [Prometheus Setup](#-prometheus-setup)
- [Available Metrics](#-available-metrics)
- [Security](#-security)
- [Custom Metrics](#-custom-metrics)
- [CLI Commands](#-cli-commands)
- [Architecture](#-architecture)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [License](#-license)

### 📦 Installation

#### Requirements

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

#### Install via Composer

```bash
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`:

```yaml
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:

```yaml
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

```yaml
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 |
| `magento_complex_product_variations_above_recommended_level` | gauge | - | Count of configurable products with more than 50 variations (performance risk) |
| `magento_products_with_bad_reviews_count_total` | gauge | `store_code` | Count of products whose rating_summary is below 60 (≈ 3 of 5 stars) |

#### 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 |
| `magento_cache_flush_count_total` | counter | - | Cumulative count of `bin/magento cache:flush` / admin flush-storage invocations |

_(README truncated for .md surface. Full README on https://packagento.com/run_as_root/magento2-prometheus-exporter.)_

## Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

### [4.1.0] - 2026-05-28

#### Changed

- `symfony/console` constraint widened to `^5.4.46|^6.0|^7.0` for Magento 2.4.9 compatibility. (#65)
- Test suite modernised: removed `getMockForAbstractClass()` usage (deprecated in PHPUnit 10+), replaced `returnCallback()` pattern to resolve deprecation notices, and completed mock method definitions. (#65)

### [4.0.0] - 2026-04-20

#### Added

- GitHub Actions CI via `graycoreio/github-actions-magento2` against the Mage-OS `supported-version` matrix (Magento 2.4.6-p14 / 2.4.7-p9 / 2.4.8-p4). Unit tests, DI compile, Magento coding standard, and integration tests all run on every push and PR. (#60)
- `phpcs.xml.dist` with the Magento2 coding standard and project-specific exclusions.
- `magento_complex_product_variations_above_recommended_level` (gauge) — count of configurable products with more than 50 variations. (#25)
- `magento_quotes_over_item_limit_count_total` (gauge, `store_code` label) — count of active carts with more than 100 items. (#32)
- `magento_products_with_bad_reviews_count_total` (gauge, `store_code` label) — count of products with `rating_summary < 60`. Guarded by `Magento_Review` module-enabled check. (#26)
- `magento_cache_flush_count_total` (counter) — incremented on every `Magento\Framework\App\Cache\Manager::flush()` invocation via a plugin. (#29)
- `UpdateMetricServiceInterface::increment(string $code, array $labels = []): bool` for counter semantics.

#### Changed

- **BREAKING:** minimum PHP requirement is now **8.2** (was 7.4).
- **BREAKING:** `UpdateMetricServiceInterface` gained the `increment()` method — downstream implementers must add it.
- `magento/module-quote` is now a runtime dependency (added to `composer.json` require and `module.xml` sequence).
- `magento/module-review` is now suggested; the bad-reviews aggregator no-ops if the module isn't installed.
- Test suite migrated from phpunit 9.x patterns (`withConsecutive`, `at()`, `onConsecutiveCalls`) to `willReturnCallback` so it runs green on phpunit 9/10/12.
- `composer.json` declares `repositories.mage-os` (public Mage-OS mirror) and `config.allow-plugins` for the Magento composer plugins graycore's coding-standard job pulls in.

#### Fixed

- `Test/Integration/Controller/IndexControllerTest` now supplies the `metric_configuration/security/enable_token` fixture so the test actually exercises the token validation code path.
- Several unit tests had stale constructor mocks and mock-expectation drift versus current production signatures; all updated.
- `src/view/adminhtml/templates/system/config/tokenGeneratorButton.phtml`: switched from deprecated `$block->escape*` to `$escaper->escape*` and fixed an unescaped-output XSS sniff.

#### Removed

- **BREAKING:** deleted `build/tools/` (legacy GitLab-CI tooling). Closes GHSA-r39x-jcww-82v6 (symfony/process MSYS2 arg escaping).

### [2.0.2] - 2021-06-11

#### Fixed

- Reset order count/amount metric before setting them

### [2.0.1] - 2021-05-31

#### Fixed

- Fix order count reset

### [2.0.0] - 2020-05-15

#### Added

- Added new CLI Command: `run_as_root:metrics:collect`.
- Added `CronJobCountAggregator` to collect metric `magento_cronjob_count_total`.
- Added `BrokenCronJobCountAggregator` to collect metric `magento_cronjob_broken_count_total`.
- Added `IndexerBacklogCountAggregator` to collect metric `magento_indexer_backlog_count_total`.
- Introduced custom cron group `run_as_root_prometheus_metrics_aggregator`.

#### Changed

- Added some Interfaces instead of hard file links.
- Changed CLI namespace to `run_as_root`.
- Made all Test Cases final.
- Restructured module directories.
- Updated Readme.

#### Removed

- Removed Licenses from PHP Files.

### [1.0.0] - 2019-06-14

#### Added

_(Changelog truncated for .md surface. Full history on https://packagento.com/run_as_root/magento2-prometheus-exporter.)_

## Recent Versions

| Version | Released |
|---|---|
| 4.1.0 | 2026-05-28 |
| 4.0.0 | 2026-04-20 |
| 3.2.6 | 2025-12-28 |
| 3.2.5 | 2025-12-19 |
| 3.2.4 | 2025-08-29 |
| 3.2.3 | 2025-06-03 |
| 3.2.2 | 2024-11-12 |
| 3.2.1 | 2024-11-07 |
| 3.2.0 | 2024-11-07 |
| 3.1.6 | 2023-11-22 |

Showing 10 of 24 versions. Full release history on https://packagento.com/run_as_root/magento2-prometheus-exporter.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| guzzlehttp/guzzle | ^7.4.5 |
| laminas/laminas-http | ^2.15.0 |
| magento/framework | * |
| magento/module-backend | * |
| magento/module-catalog | * |
| magento/module-cms | * |
| magento/module-config | * |
| magento/module-cron | * |
| magento/module-eav | * |
| magento/module-indexer | * |
| magento/module-payment | * |
| magento/module-quote | * |
| magento/module-sales | * |
| magento/module-shipping | * |
| magento/module-store | * |
| magento/zend-db | * |
| monolog/monolog | ^2.9.0\|^3.0 |
| php | ^8.2 |
| psr/log | ^1.1\|^2.0\|^3.0 |
| symfony/console | ^5.4.46\|^6.0\|^7.0 |

### Require (dev)

| Package | Constraint |
|---|---|
| phpunit/phpunit | ^9.5\|^10.0 |

### Conflict

| Package | Constraint |
|---|---|
| guzzlehttp/guzzle | <7.4.5 |
| monolog/monolog | <2.9.0 |
| symfony/console | <5.4.46 |
| symfony/process | <5.4.46 |

### Suggest

| Package | Constraint |
|---|---|
| magento/module-review | Enables the magento_products_with_bad_reviews_count_total metric |

## Quality

Latest release (4.1.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | not tested | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 277 | 29 errors, 248 warnings (ruleset: Magento2) — 32 auto-fixable with phpcbf |
| PHPMD | Warning | 16 | 16 rule violations (MissingImport:7, UnusedLocalVariable:5, UnusedFormalParameter:3, ExcessiveMethodLength:1) |
| Cpd | Warning | 3 | 3 duplicated chunks spanning 71 total lines (min-lines=5, min-tokens=70) |
| Composer validate | Info | 15 | valid; 15 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 30 | 30 | – | – |
| 2.4.8 | – | 31 | 31 | – |
| 2.4.9 | – | – | 31 | 31 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["run_as_root/magento2-prometheus-exporter"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

run_as_root is a Magento 2 vendor on Packagento. See https://packagento.com/run_as_root.md for their full catalogue.