Business Events

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

Enterprise Edition / CloudHub

Mule can collect business events information for the flows and message processors handling your business transactions. Business events information can include transaction execution time, errors, and results (successful completion or failure), and message payload information, which you can customize using Mule Expression Language (MEL) . Using Insight or Mule Management Console, you can monitor these events at runtime to analyze the root cause of failures, isolate performance bottlenecks, and test for compliance to company procedures.

Mule lets you set up custom events to capture specific payload information for later tracking and analysis at runtime. Also, some default events are automatically generated by Mule servers. For MMC users, to track and analyze default events at runtime, you must first enable event tracking in your application. For CloudHub users, certain default events are tracked automatically once Insight is enabled, but others need to be enabled in your application before they are tracked.

This page explains how to set up business events in your application:

How to enable tracking of default events at the flow level or the message processor/connector level
How to configure custom events
Best practices for designing applications for effective event tracking

Refer to the following pages for information about runtime business event tracking and analysis:

How to filter and analyze business events in Insight
How to analyze business events using Mule Management Console’s Business Events tab
How to query and filter transactions and events in the Mule Management Console
Business event tracking use cases for Mule Management Console

Terminology

It is important to understand some terminology before going further.

Transactions are logical groupings of related events, and often correspond to a business view of the system. Transactions map to flows.
Events are low-level details of a transaction. Events map to message processors and connectors. Events can also be exceptions and custom events. All events, except for custom events, are considered default events.

Batch processing does not support the use of Business Events.

Code Summaries

Configuring Business Events

There are two ways to configure business event tracking in Mule:

Configure custom business events at specific points within a flow.
Enable default event tracking for a flow or for specific message processors/connectors within a flow.

Custom event tracking is supported by the custom business event element. Custom events are always tracked once they’re configured. Custom events allow you to track high-level activities in your flow that are relevant to your business.

Default event tracking is supported by all connectors and selected message processors. Enabling default events for these elements allows you to perform advanced debugging at runtime.

Custom Events

Mule gives you the ability to attach custom metadata in your flow using the custom business event message processor. You can add custom events to your flow using Studio or XML. Each custom business event can be configured to have multiple metadata properties associated with it.

Studio Visual Editor

Within the Palette, search for and drag Custom Business Events to the desired location in your flow. Click the icon to open the Properties Editor.
Enter string values for Display Name and Event Name.
Optionally, click the green plus sign to create a list of Key Performance Indicators (KPIs) to capture information from the message payload. For each subsequent KPI, click the green plus sign:
1. After you click the green plus sign, Studio displays tracking:meta-data.
2. Click tracking:meta-data and a field appears to enter text:
3. Enter a name that can be used in the search interface of Mule Management Console or CloudHub at runtime, and a value, which may be any Mule expression.
  
  In this example the values are:
  
  Name Expression/Value
  
  Employee ID
  
  #[payload['ID']]
  
  Employee Email
  
  #[payload['Email']]
  
  Employee Git ID
  
  #[payload['GITHUB_ID']]

Name	Expression/Value
Employee ID	`#[payload['ID']]`
Employee Email	`#[payload['Email']]`
Employee Git ID	`#[payload['GITHUB_ID']]`

Note that key/value pairs can vary according to your business needs. Additional examples:

Name Expression/Value

Name	Expression/Value
`price`	`700`
price-after-discount	#[groovy:payload.price]
price-after-discount	The price for the item is:#[groovy:payload.price]

price

700

price-after-discount

#[groovy:payload.price]

price-after-discount

The price for the item is:#[groovy:payload.price]

Using the XML editor, you can set up your flow so that metadata can be shared among events. See the XML tab for details on how to set up the tracking:custom-event-template global element in your flow.

You can also trigger conditional custom events to help track how messages are processed through your flow. For example, you could set up a choice router in your flow.

XML Editor or Standalone

Configure a custom event using XML as in the following example:

<flow name="flow">
...
  <tracking:custom-event event-name="Retrieved Employee">
  </tracking:custom-event>
...
</flow>

When you define a custom event, you can also add metadata. Use Mule expression language in the value to capture information from the message payload.

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:spring="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
    <flow name="bizFlow">
        <tracking:custom-event event-name="Retrieved Employee" doc:name="Custom Business Event">
            <tracking:meta-data key="Employee ID" value="#[payload['ID']]"/>
            <tracking:meta-data key="Employee Email" value="#[payload['Email']]"/>
            <tracking:meta-data key="Employee Git ID" value="#[payload['GITHUB_ID']]"/>
        </tracking:custom-event>
    </flow>
</mule>

You can even add text to the expression language, as shown in the following example:

        <tracking:custom-event event-name="price_discount">
            <tracking:meta-data key="price-after-discount"
            value="The price for the item is:#[groovy:payload.price]" />
        </tracking:custom-event>

Also, metadata can be shared among events using the tracking:custom-event-template global element:

<tracking:custom-event-template name="template">
  <tracking:meta-data key="tier-level" value="platinum" />
  <tracking:meta-data key="price-after-discount" value="#[groovy:payload.price]" />
</tracking:custom-event-template>

<flow name="flow">
  <tracking:custom-event event-name="event1" inherits="template" />
  <tracking:custom-event event-name="event2" inherits="template" />
</flow>

And you can define how conditional custom events are fired. The code below shows how to do this:

<choice>
  <when expression="INVOCATION:debugflag = on" evaluator="header">
    <tracking:custom-event event-name="success" />
  </when>
  <otherwise>
    <tracking:custom-event event-name="failure" />
  </otherwise>
</choice>

In this last example, a custom event with the event name "success" is fired if the debug flag is on when the message processor is invoked. Otherwise, a custom event with the event name "failure" is fired.

Default Events

Event tracking requires some processing and network overhead to aggregate and store the events that the Mule servers generate, so by default, tracking is not enabled for connectors or message processors that support it. However, enabling tracking for default events is very simple. You just need to explicitly configure the scope for tracking the default events. You can configure the scope either:

At the flow level
At the message processor or connector level

Message processor or connector level configuration takes precedence over flow level configuration.

if you want to enable all default events for a specific flow:
if you want to enable default events for a specific message processor (in this case, the All router):
if you want to enable all default events for a specific flow, but not for a specific message processor (in this case, the All router):

To enable default event tracking for all relevant elements within your flow, follow these instructions:

Studio Visual Editor

Click the title bar of the flow in the canvas to open the flow’s Properties Editor.
Enable default Business Events by selecting Enable default events tracking:
Optionally, check Use transaction ID to set an identifier for all tracked events pertaining to this flow so that meaningful information, such as an order number, is displayed for a transaction.
Click anywhere in the canvas to save your settings.

This enables default events tracking for all supported processors within the flow.

If you wish, you can disable tracking for specific processors or connectors to override the flow-level enablement.

XML Editor or Standalone

Include the attribute tracking:enable-default-events="true" at the level of your flow in your XML, as in the following example:

<flow name="flow" tracking:enable-default-events="true">
  ...
</flow>

This enables event tracking for all supported elements in the flow. If you wish, you can disable tracking for specific processors or connectors to override the flow-level enablement. For example, the code below specifies that although the flow has tracking enabled for default events, tracking is disabled for the All router.

<flow name="flow" tracking:enable-default-events="true">
  ...
  <all tracking:enable-default-events="false" />
  ...
</flow>

Optionally, you can define a transaction ID so that meaningful information, such as an order number, is displayed for a transaction. If you do not customize the transaction ID, Mule assigns a numeric transaction ID by default. To make the ID more user-friendly for your business needs, you can customize it with Mule expression language:

<flow name="flow">
  ...
  <tracking:transaction id="#[expression]" />
  ...
</flow>

To enable default event tracking for individual elements within your flow, follow these instructions:

Studio Visual Editor

Open the Properties Editor of the desired processor within the flow.
In the Advanced tab, select Enable default events tracking to enable default business events tracking for only the selected processor.

Not all processors support default event tracking. If the checkbox is not present in a message processor or connector, default tracking is not supported.

Studio Standalone XML

To enable default events tracking for a specific element in a flow, add the attribute tracking:enable-default-events="true" to the element, as shown here for the All router:

<flow name="flow">
  ...
    <file:outbound-endpoint path="/tmp" tracking:enable-default-events="true"/>
  ...
</flow>

Not all elements support default event tracking. If Mule throws an exception specifying that the prefix "tracking" is invalid for that element, default tracking is not supported.

Customizing the Transaction ID

You can define a transaction ID so that meaningful information, such as an order number, is displayed for a transaction when you analyze tracked events at runtime. If you do not customize the transaction ID, Mule assigns a numeric transaction ID by default. To make the ID more user-friendly for your business needs, you can customize it with Mule expression language.

It’s good practice to customize the ID such that the ID is unique for each transaction in your application. The following example sets up a unique ID based on a unique order ID extracted from a payload.

Studio Visual Editor

Studio Standalone XML

<flow name="flow">
...
  <tracking:transaction id="#[groovy:payload.orderId]" />
...
</flow>

Best Practices

There are a number of recommended practices for setting up your business event tracking in your application.

Enable default events only for processes that have particular value to you. Determine which stages within a business transaction that you want to track, and enable tracking for those stages before deployment. Tracking all possible events is also an option, but you have to spend more time at runtime filtering or querying to find the events you really need to analyze.
Use custom events to track key process indicators, for example, "Total Order Amount" or "Tracking Number" to surface the high-level business activities in your flow.
Customize the transaction ID so that meaningful information, such as an order number, an employee identification number, or a shipment tracking number, is displayed for a transaction. This makes analysis and debugging easier and more intuitive at runtime, whether you are using Mule Management Console or CloudHub.

Code Summaries

Namespace:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    ...
    xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking"
    xsi:schemaLocation="
        ...
        http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
   ...
</mule>

Example of custom event tracking:

<flow name="flow">
...
  <tracking:custom-event event-name="Retrieved Employee" doc:name="Retrieved Employee">
    <tracking:meta-data key="Employee Id" value="#[payload['ID']]"/>
    <tracking:meta-data key="Employee First Name" value="#[payload['FIRST_NAME']]"/>
    <tracking:meta-data key="Employee Last Name" value="#[payload['LAST_NAME']]"/>
    <tracking:meta-data key="Employee Email" value="#[payload['EMAIL']]"/>
    <tracking:meta-data key="Employee Git ID" value="#[payload['GITHUB_ID']]"/>
  </tracking:custom-event>
...
</flow>

Example of default event tracking at the flow level:

<flow name="flow">
...
  <tracking:custom-event event-name="Retrieved Employee" doc:name="Retrieved Employee">
    <tracking:meta-data key="Employee Id" value="#[payload['ID']]"/>
    <tracking:meta-data key="Employee First Name" value="#[payload['FIRST_NAME']]"/>
    <tracking:meta-data key="Employee Last Name" value="#[payload['LAST_NAME']]"/>
    <tracking:meta-data key="Employee Email" value="#[payload['EMAIL']]"/>
    <tracking:meta-data key="Employee Git ID" value="#[payload['GITHUB_ID']]"/>
  </tracking:custom-event>
...
</flow>

Example of default event tracking at the message processor level:

<flow name="flow">
  ...
  <all tracking:enable-default-events="true" />
  ...
</flow>

Example of customized transaction Id:

<flow name="flow">
...
  <tracking:transaction id="#[groovy:payload.orderId]" />
...
</flow>

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Gartner names MuleSoft a Leader

Create connected experiences with AI

Future of connected AI agents

The world of AI is a world of APIs

Business Events

Configuring Business Events

Custom Events

Studio Visual Editor

XML Editor or Standalone

Default Events

Studio Visual Editor

XML Editor or Standalone

Studio Visual Editor

Studio Standalone XML

Customizing the Transaction ID

Studio Visual Editor

Studio Standalone XML

Best Practices

Code Summaries

See Also