magewatch/module-agent

Read-only monitoring agent for Magento 2 that collects health metrics and pushes them to the MageWatch SaaS API.

1.0.0 2026-07-07 15:46 UTC

Requires

• php: ~8.1.0||~8.2.0||~8.3.0
• magento/framework: *
• magento/module-backend: *
• magento/module-config: *
• magento/module-cron: *
• magento/module-indexer: *
• magento/module-sales: *
• magento/module-store: *

Requires (Dev)

• phpunit/phpunit: ^9.5

OSL-3.0

• MageWatch

• cron
• monitoring
• magento
• saas
• indexer
• magento2
• magewatch

Published on Packagist.org on 2026-07-07 15:48 UTC

README

Read-only monitoring agent for Magento 2.4.6+. Collects indexers, cron, queues, orders, logs, and system metrics every 5 minutes and POSTs a JSON heartbeat to MageWatch.

• Packagist: magewatch/module-agent
• Source: github.com/krivtsuna/magewatch-module-agent

Requirements

• Magento 2.4.6+ (Open Source or Adobe Commerce)
• PHP 8.1, 8.2, or 8.3

Installation

From Packagist (recommended)

From your Magento project root:

composer require magewatch/module-agent
bin/magento module:enable MageWatch_Agent
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Before Packagist indexes the repo (or for private mirrors)

Add the GitHub VCS repository to your Magento composer.json, then require the package:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/krivtsuna/magewatch-module-agent"
        }
    ]
}

composer require magewatch/module-agent:^1.0
bin/magento module:enable MageWatch_Agent
bin/magento setup:upgrade
bin/magento cache:flush

Local monorepo development (path repository)

{
    "repositories": [
        {
            "type": "path",
            "url": "../magewatch.io/packages/magewatch-module-agent",
            "options": { "symlink": true }
        }
    ],
    "require": {
        "magewatch/module-agent": "@dev"
    }
}

Configuration

Stores → Configuration → MageWatch → Agent

Field	Description
Enabled	Turns the cron job on/off
API Endpoint URL	HTTPS ingest URL, e.g. https://magewatch.io/api/v1/ingest
Site Token	Bearer token from the MageWatch dashboard
Stuck Cron Threshold	Minutes before a running job is reported as stuck (default 30)

CLI

bin/magento magewatch:status
bin/magento magewatch:send
bin/magento magewatch:send --force

How it works

• Cron group magewatch runs CollectAndSend on a configurable schedule (default */5 * * * *).
• Collectors implement CollectorInterface; failures are logged and listed in collector_errors without breaking the run.
• Delivery uses Magento's Curl client (TLS verification on, 5s connect / 10s total timeout).
• Log line deltas use the magewatch_log_offset DB table (multi-node safe).

Tests

Unit tests run inside a Magento dev environment:

vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/MageWatch/Agent/Test/Unit

In this standalone repo (requires Magento packages in vendor/):

composer install
vendor/bin/phpunit

Uninstall

bin/magento module:disable MageWatch_Agent
composer remove magewatch/module-agent
bin/magento setup:upgrade

License

OSL-3.0 — see LICENSE.