Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Management Console (3.2)
  3. Analyzing Business Events

  4. Tracking and Querying Business Events

Tracking and Querying Business Events

The Mule servers generate default events for the flows and message processors handling your business transactions, tracking such information as processing time and errors. In addition, you may have set up custom events to capture specific payload information. All events, whether custom or default, are stored for later retrieval and analysis. Using the Business Events tab, you can have the console retrieve transaction and event information, and you can audit events. Auditing events has only a low overhead on server performance.

This page explains how to use the transaction and event querying and filtering features. It also explains how you can add your own custom code to your application to enhance default event tracking.

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.

  • Events are low-level details of a transaction. Events map to message processors and endpoints. Events can also be exceptions and custom events. All events, except for custom events, are considered default events.

Tracking Default Events

Event tracking requires some processing and network overhead to aggregate and store the events that the Mule servers generate. Custom events are always tracked once they’re configured. However, you can also enable tracking for default events. To do that you 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 endpoint level

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

Here are some examples that enable default event tracking:

Enable all default events for a specific flow:

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

Enable default events for a specific message processor (in this case, the logger):

<flow id="flow">
  <logger tracking:enable-default-events="true"/>
</flow>

Enable all default events for a specific flow, but not for a specific message processor (in this case, the logger):

<flow id="flow" tracking:enable-default-events="true">
  <logger tracking:enable-default-events="false" />
</flow>

Tracking Custom Events

As mentioned previously, you can use the Business Events tab to track custom events. In addition, you can define some properties for custom events that will appear with the recorded data for the event. In this way, you can capture specific payload information with an event.

To track a custom event, you must add some code to your application’s configuration file. First, you need to add the tracking namespace definition to the configuration file. The example below illustrates the code that you need to add to the schema/mule/core section.

<?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/3.2/mule-tracking-ee.xsd">
    ...
</mule>

Next, you define a custom event. You can define a custom event anywhere a meta-property is defined. When you define a custom event, you can also add extra metadata. For example:

<flow name="flow">
  <tracking:custom-event event-name="event">
    <tracking:meta-data key="price" value="700" />
  </tracking:custom-event>
</flow>

In the metadata you set for custom events, you can make use of fine-grained expression language, as shown below.

<flow name="flow">
    <tracking:custom-event event-name="price_discount">
      <tracking:meta-data key="price-after-discount" value="#[groovy:payload.price]" />
    </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, as follows:

<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 the previous 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.

Querying and Filtering Business Transactions and Events

You set up transaction queries from the main Business Events screen, the screen that opens when you click the Business Events tab. If you want to track default events, be sure to enable default event generation and tracking for your application(s), as described in Tracking Default Events.

To query transactions and events:

  • Select a key from the Search pull-down list for limiting the selection. For example, you might specify customId or event: type as the key.

  • Select an operator (that is, the condition for selecting values that match the key) from the pull-down list. You can choose operators such as equals, like, greater than, and less than. The operators available in the pull-down list vary depending on the key you select. For example, if you select event:timestamp as the key, you can choose from a list of arithmetic operators: Equals, Greater than, Greater than or equals, Less Than, or Less than or equals. If you select an event attribute as the key, such as event: exceptionDetails, you can choose either the operators Equals, Starts with Contains, Ends with, Is empty, or Is not empty.

  • Enter a value for the key. The search selects the events or transactions whose key field matches this value according to the selected operator.

Note, too, that you can specify the number of matching transactions you want retrieved. The default value is 50 transactions (highlighted in the figure below). Enter a new number to change this default.

The figure below shows how you might specify a simple search for transactions based on one key.

event search

You can also set up more sophisticated queries by entering multiple key fields. Click the green plus sign icon (circled in the figure above) to the right of the key field selection to enter additional keys.

Select the keys and operators and enter values for any additional selection criteria in the same manner as for a single search criterion. Click the red X icon to the right of a criterion to remove it from the list. Click the green plus sign icon to add more selection keys.

When you use multiple selection criteria, you can further designate that the search must match all specified rules (this is the default condition) or that the the search can match any of the specified rules. Use the pull-down list above the selection rules to make this choice.

In addition to only letting you select appropriate operators for the key selection fields, the console also helps you enter the correct values. In the figure below, if a key field requires a date value, click the calendar icon in the value box to open a calendar from which you can select a date. The console then enters the date value in the correct format. The transactions from today, the current day, are displayed by default.

event search mult keys

After specifying all the search rules, click the Search button to initiate the search and data retrieval. The lower portion of the screen displays a table with the transactions or events that matched the specified criteria. For example, the figure below shows the results of a search.

search results

You can use the filter box to filter the displayed data. Filtering can be done on the event or transaction id, server, and status fields.

filtered search results

Keep in mind that these searchable fields are pre-populated and always available. This feature keeps the processing overhead to a minimum.

Customizing the Transaction ID

Notice that the data returned for a transaction includes a rather long ID in the Id column. You can simplify and otherwise customize the ID using expression language, as follows:

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

In this way you can give the transaction a more meaningful identification. You only need to customize the transaction ID once in your application.

It’s good practice to customize the ID such that the ID is unique for each transaction. The following example sets up a unique ID based on a unique order ID:

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

Viewing All Events for a Transaction

You can view details of all events for a single transaction.

After selecting a set of transactions, click the transaction id from the transaction display pane. The detailed events pane opens and shows all events within that transaction in a single list.

details

Using the console filter box, you can filter events by particular attribute values. Because the console does not need to communicate to the server to display a filtered list of event details, there is no impact on server performance.

filtered events

Click on an event to display properties defined for the event.

For example, suppose an application enables and defines a custom event as follows:

<tracking:custom-event-template name="orderDetails">
     <tracking:meta-data key="Order Id" value="#[ognl:orderId]" />
     <tracking:meta-data key="Customer Name" value="#[ognl:customer.firstName]
      #[ognl:customer.lastName]" />
     <tracking:meta-data key="Location" value="#[ognl:customer.city], #[ognl:customer.state]" />
     <tracking:meta-data key="Product Name" value="#[ognl:items[0].name]" />
     <tracking:meta-data key="Product Id" value="#[ognl:items[0].productId]" />
     <tracking:meta-data key="Quantity" value="#[ognl:items[0].quantity]" />
     <tracking:meta-data key="List Price" value="#[ognl:items[0].listPrice]" />
 </tracking:custom-event-template>

<flow name="order_management" doc:name="Order Processing" tracking:enable-default-events="true">

<cxf:jaxws-service serviceClass="com.mulesoft.demo.orderprocessing.ProcessOrderImpl"
 doc:name="Process SOAP Order request"/>

<processor-chain>
    <tracking:custom-event event-name="Order Details" inherits="orderDetails"/>
     ...
    </processor-chain>
</flow>

Clicking on the event named "Order Details" displays the properties defined for the event, as shown below.

event properties

Or if default tracking is enabled, you can click on an exception event to get details.

exception details

Customizing Flow or Event Names

Unless you identify specific names to display for flows and events, Mule displays default flow and event names in the details pane of the Business Events tab. However, you can customize the name displayed for a flow or event through the doc:name attribute. This gives you flexibility in naming a flow or event. For example, you can include spaces in the name (something you cannot do if you specify a name in the name attribute for the flow or the event-name attribute for the custom event). You can specify the doc:name attribute for a flow or any message processor. The namespace for the doc:name attribute is as follows:

xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"

Here’s an example that specifies a name, Main Hello Flow, to be displayed in the Flow name column when events associated with that flow are listed:

xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
...
<flow doc:name="Main Hello Flow" name="Hello World" tracking:enable-default-events="true">

Note that it is the name specified in the doc:name attribute, (Main Hello Flow) that will be displayed in the details pane, and not the name specified in the name attribute (HelloWorld). If both are specified, the name specified in the doc:name attribute takes precedence over the name specified in the name attribute.

Here is an example that specifies a name, Http Endpoint, to be displayed for events generated for a specific inbound endpoint:

xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
...
<inbound-endpoint doc:name="Http Endpoint"
  address="http://localhost:8888" transformer-refs="HttpRequestToNameString" exchange-pattern="request-response">

And here is an example that specifies a name, Greeter component, to be displayed for events generated for a specific component:

xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
...
<component doc:name="Greeter component" class="org.mule.example.hello.Greeter"/>

Best Practices

There are a number of recommended practices related to business events. These include:

  • Customize the transaction ID so that a meaningful ID, such as an order number, is displayed for a transaction. It’s good practice to customize the ID such that the ID is unique for each transaction.

  • Enable default events for processes that have particular business value, that is, stages within a business transaction that you want to track from a business perspective.

  • Use custom events to track key process indicators, for example, "Total Order Amount" or "Tracking Number".

  • Use the doc:name attribute to assign a meaningful display name, such as "Processor Order", to a flow or event.

  • Correctly size the database that will be used to store events. Mule stores event-related data in a default database, which persists the data. However, you also have the option to persist the data in an Oracle database. This can give you control over how much data to store. It can also provide better scalability and performance than the default data storage. See Configuring a Database for Business Event Data Persistence for further details.

  • Fine-tune the cleanup script. The management console provides a cleanup script as part of the Admin Shell in the Administration tab. The script periodically cleans old data from the tracking database. By default, the script runs once a day and cleans all data from the database that is older than one week. You can customize the cleanup script so that it specifically meets your requirements.

<< Previous: Analyzing Business Events

Next: Business Events Use Cases >>