Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.5)
  3. Developing
  4. Transformers

  5. Business Events

Business Events

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can 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 makes it possible to 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 will be tracked automatically once Insight is enabled, but others need to be enabled in your application before they will be 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:

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

  1. Within the Palette, click Miscellaneous, then drag Custom Business Events to the desired location in your flow. Click the icon to open the Properties Editor.

  2. Enter string values for Display Name and Event Name.

  3. Optionally, create a list of Key Performance Indicators (KPIs) to capture information from the message payload. For each KPI, enter a name (which can be used in the search interface of Mule Management Console or CloudHub at runtime), and a value, which may be any Mule expression.

    custom_business_events

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

    Name Expression/Value

    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 like this:

Studio_customevent_choice

In this 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.

Studio or Standalone XML

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.

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

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

<flow name="flow">
...
    <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>
...
</flow>

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.

Click for examples

  • if you want to enable all default events for a specific flow:

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

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

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

  • 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):

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

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

Studio Visual Editor

  1. Click the title bar of the flow in the canvas to open the flow’s Properties Editor.

  2. Enable default Business Events by selecting Enable default events tracking.

  3. flow_events

  4. 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.

  5. Click anywhere in the canvas to save your settings.

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

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

Studio or Standalone XML

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 will enable 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

  1. Open the Properties Editor of the desired building block within the flow.

  2. In the Advanced tab, select Enable default events tracking to enable default business events tracking for only the selected building block.

events+tracking

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

Studio or 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">
  ...
  <all 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

transactionID

Studio or 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 will 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
<?xml version="1.0" encoding="UTF-8"?>
<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:enable-default-events="true">
  ...
</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>

See Also