mage-os / mageos-async-events
An event-driven flexible async events module that allows you to process any event asynchronously.
Installs: 3 998
Dependents: 4
Suggesters: 0
Security: 0
Stars: 16
Watchers: 11
Forks: 3
Open Issues: 1
Type:magento2-module
Requires
- php: >=8.1
- cloudevents/sdk-php: ^1.1
- magento/framework: *
Requires (Dev)
This package is auto-updated.
Last update: 2024-10-17 10:04:52 UTC
README
A framework for reliably handling asynchronous events with Magento.
- Asynchronous: The module uses RabbitMQ (or DB queues) to leverage asynchronous message delivery.
- Flexible: Decoupling events and dispatches provide greater flexibility in message modelling.
- Scalable: Handles back pressure and provides an asynchronous failover model automatically.
Installation
$ composer require mage-os/mageos-async-events
Install the module:
$ bin/magento setup:upgrade
Usage
Define an asynchronous event
Create a new async_events.xml
under a module's etc/
directory.
<?xml version="1.0"?> <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:MageOS_AsyncEvents:etc/async_events.xsd" > <async_event name="sales.order.created"> <service class="Magento\Sales\Api\OrderRepositoryInterface" method="get"/> </async_event> </config>
Create a Subscription
Tip
To view all available event sinks, check out Async Event Sinks
HTTP
curl --location --request POST 'https://test.mageos.dev/rest/V1/async_event' \ --header 'Authorization: Bearer TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "asyncEvent": { "event_name": "sales.order.created", "recipient_url": "https://example.com/order_created", "verification_token": "supersecret", "metadata": "http" } }'
Amazon EventBridge
Requires the AWS Sinks package
curl --location --request POST 'https://test.mageos.dev/rest/V1/async_event' \ --header 'Authorization: Bearer TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "asyncEvent": { "event_name": "sales.order.created", "recipient_url": "arn:aws:events:ap-southeast-2:ACCOUNT_ID:rule/BUS_NAME", "verification_token": "supersecret", "metadata": "eventbridge" } }'
Dispatch an asynchronous event
use \MageOS\AsyncEvents\Model\AsyncEventPublisher; // ... public function __construct(private readonly AsyncEventPublisher $asyncEventPublisher) {} public function execute(Observer $observer): void { /** @var Order $order */ $order = $observer->getData('order'); // arguments are the inputs required by the service class in the asynchronous // event definition in async_events.xml // e.g: Magento\Sales\Api\OrderRepositoryInterface::get $message = ['id' => $order->getId()]; $this->asyncEventPublisher->publish('sales.order.created', $message); }
Ensure the following consumers are running
bin/magento queue:consumer:start event.trigger.consumer bin/magento queue:consumer:start event.retry.consumer
Features
Trace
All events are logged at the individual subscription level with a UUID.
All information from the first delivery attempt to the latest attempt is presented as a trace table. The event payload is also available to view for investigation purposes.
Retries
Events are automatically retried with quadratic back off. The default retry limit is 5. The maximum backoff is 60 seconds.
Important
RabbitMQ is required for retries with back off. If you are using DB queues then quadratic back off is
not available, and you will have to implement your own \MageOS\AsyncEvents\Api\RetryManagementInterface
The quadratic backoff is calculated as min(60, pow($deathCount, 2));
To change the default retry limit visit Admin > Stores > Settings > Configuration > Advanced > System > Async Events and
update Maximum Deaths
.
Replays
An event can be replayed independent of its status. This is useful to debug or replay an event when all retries are exhausted.
Replays start a new chain of delivery attempts and will respect the same retry mechanism if they fail again.
Lucene Query Syntax
All events are indexed in Elasticsearch by default. This allows you to search through events including the event payload!
The module supports Lucene Query Syntax to query event data like attributes.
The following attributes are available across all asynchronous events.
log_id
uuid
event_name
success
created
The following attributes differ between asynchronous event types.
data
Examples
Assuming you have the following events configured
customer.created
customer.updated
customer.deleted
sales.order.created
sales.invoice.created
shipment.created
shipment.updated
shipment.deleted
You can query all customer events by using a wildcard like event_name: customer.*
which matches the following events
customer.created
customer.updated
customer.deleted
You can query all created events like *.created
which matches the following events
customer.created
sales.order.created
sales.invoice.created
shipment.created
You can further narrow down using the other available attributes such as status or uuid.
The following query returns all customer events which have failed. customer.* AND success: false
You can combine complex lucene queries to fetch event history and then export them via the admin grid as a csv if you wish.
Searching inside event payloads
Searching an event payload depends on what event you are searching on.
For the following example event payload, four properties are indexed as attributes. Therefore, you can query on
data.customer_email
, data.customer_firstname
, data.customer_lastname
and data.increment_id
.
Properties inside array at any level are not searchable.
{ "data": { "customer_email": "roni_cost@example.com", "customer_firstname": "Veronica", "customer_lastname": "Costello", "increment_id": "CK00000001", "payment_additional_info": [ { "key": "method_title", "value": "Check / Money order" } ] } }
Search all events where the customer email is roni_cost@example.com
data.data.customer_email: roni_cost@example.com
Search all events with the order increment id starting with CK
and status success
data.data.increment_id: CK* AND success: true
To turn off asynchronous event indexing visit Admin > Stores > Settings > Configuration > Advanced > System >
Async Events and disable Enable Asynchronous Events Indexing
.