Business event capture

To get started with business events, you first need to define the scope of the data you want to capture. The approach you use depends on the source of the business events.

There are three sources for business events.

  • OneAgent

    Configure in Dynatrace to add capture rules, triggers, data fields, and more.

  • Web and mobile RUM

    Obtain RUM business events by leveraging a dedicated method of the RUM JavaScript API, OneAgent for mobile, or OpenKit.

  • External sources

    Configure external business or IT systems to send business events in JSON format to the business events API (REST endpoint).

Get business events via OneAgent

OneAgent version 1.253+

To capture business events using OneAgent, you need to first enable the feature.

  1. Go to Settings > Preferences > OneAgent features.

  2. Enable the OneAgent business events feature for the technologies appropriate for your environment.

    You need to restart the application process before you can capture business events from the process.

Configuration requires one or more capture rules that consist of triggers, mandatory data fields, and optional event data fields.

The table below contains examples of mandatory (event.type, event.provider) and optional (event.category) data fields.

Field
Type
Description
Examples
event.category
string
Standard categorization based on the significance of an event according to the ITIL event management standard
Availability
event.type
string
The unique type identifier of a given event
buy-asset, sell-asset, login
event.provider
string
Source of the event, for example, the name of the component or system that generated the event
OneAgent, easyTrade.com, easyTravel.com

Supported technologies

Data extraction from incoming HTTP requests

AgentOneAgent featureMin. versionTechnologies supportedMin. versionCompressed bodyFull bodyMin. versionCompressed bodyFull body

Enablement (event capture)

application/json (payload capture)

Header: XML (payload capture)1

Webserver

Webserver Business Events

1.253

  • Apache Applicable
  • NGINX Applicable
  • IIS Applicable

1.253

Applicable

Applicable

1.275

Applicable

Applicable

.NET

.NET Business Events

1.253

Applicable

1.253

Not applicable

Applicable

1.279

Not applicable

Applicable

Java

Java Business Events

1.253

Servlet Applicable

  • Tomcat2
  • Jetty
  • JBoss
  • Websphere Liberty
  • WebLogic
  • Undertow
  • GlassFish

1.253

Applicable

Applicable

1.275

Applicable

Applicable

Node.js

Node.js Business Events

1.259

Applicable

1.259

Applicable

Applicable

n/a

Not applicable

Not applicable

Golang

Go Business Events

1.263

Applicable

1.263

Applicable (1.265)

Applicable

n/a

Not applicable

Not applicable

1

Supported content types for XML capture by default are text/xml and application/xml.

2

Tomcat 10 support—OneAgent version 1.263+ and Java Servlet 5.0 Oneagent feature (in Settings > Preferences > OneAgent features) required

Data extraction from outgoing HTTP requests

AgentOneAgent featureMin. versionTechnologies supportedMin. versionCompressed bodyFull bodyMin. versionCompressed bodyFull body

Enablement (event capture)

application/json (payload capture)

Header: XML (payload capture)1

Java

Java Business Events

1.297

HTTP Clients

  • Apache HTTP Client 4.x Synchronous
  • Apache HTTP Client 4.x Asynchronous
  • OK HTTP Client 3.4+ Synchronous
  • OK HTTP Client 3.4+ Asynchronous

1.297

Applicable

Applicable

1.297

Applicable

Applicable

1.297

HTTP Clients

  • Spring WebFlux 5, 6

1.297

Not applicable

Not applicable

1.297

Not applicable

Not applicable

Configure business event sources on OneAgent

OneAgent version 1.253+

To configure business event sources on OneAgent

  1. Go to Settings > Business Analytics > OneAgent Business Event Sources.

  2. Select Add new capture rule and name your rule.

  3. Select Add trigger to define a condition that will trigger a business event.

    Determine the data source for your trigger, such as the request Body, Path, or HTTP Header. Then select an Operator and define a Value. This allows you to match content retrieved from the source to the value you define. When OneAgent matches the trigger, a business event is generated.

    • The Summary displays the entire trigger rule (for example, Request - Path starts with '/api/trade/BuyAssets).
    • By default, the Value is not case sensitive. Turn on Case sensitive if you want your trigger to consider the case of the source.
    • Triggers are connected by AND logic within a rule; if you set multiple triggers, all of them need to be fulfilled to capture a business event.
    • The first matching rule is executed per OneAgent per request.
    • We recommend that you set specific triggers. If a trigger is too general and results in multiple identical rule matches, you will get multiple business events. For example, if you have a trigger condition contains api, and the term api is used in many of your applications, data can end up being captured from where it shouldn't be.

    Do not create triggers where the value is simply /; this can lead to overloading and shutting down your application environment.

  4. Select the Event provider source and value.

    This describes the source of the event, such as www.easytrade.com. The data source for this field can be a fixed value that you provide or it can be extracted from the event.

  5. Select the Event type source and value.

    This describes the type of event sent by the event provider, such as Asset purchase.

  6. optional Select Event category source and value to add helpful context to the event (for example, add a stock exchange name such as NASDAQ).

    This step concludes the configuration of a business event that will be generated each time the trigger criteria are matched. This might be sufficient if all you need is to count the number of matching events (for example, to answer the question of how many asset purchases were made). In most cases, however, you will want to add event attributes for more granular insight (described in the step below). Attributes are data fields extracted from the event JSON or XML payload.

  7. Select Add data field in Event data. Provide a field name, and then provide the data source and value from the JSON or XML payload. This describes the attribute-value pair that will be associated with the event, such as accountId, amount, instrumentId, or price. Adding such pairs can help you answer more complex questions such as how many accounts purchased a particular asset, which assets are purchased most often, or which accounts make the largest asset purchases.

    Example buy-asset request JSON file

    {
       "accountId":6,
       "amount":10,
       "instrumentId":1,
       "price":157.025
    }

  8. Select Save changes.

  9. Ensure that the rule is set to Enabled.

OneAgent capture rules can also be defined at the host or host-group level to limit the scope of capture.

Example of data extraction from JSON payloads

The following table shows additional examples of how to extract data from incoming JSON payloads.

  • Request URL—example.dynatrace.com/api?action=addItems

  • Request headers

    • Accept—*/*
    • Accept-Encoding—gzip, deflate
    • Accept-Language—en-US,en;q=0.9
    • Connection—keep-alive
    • Content-Length—64
    • Content-Type—application/json

  • Request payload

    {
       "time":"2022-03-12T12:16:36.5881611+00:00",
       "transactionId":"1748-2b59-5c78-9c75-f500-274a-88f5-7965",
       "user":{
          "user.id":"1684588",
          "userName":"johndoe",
          "name":"John",
          "surname":"Doe",
          "email":"me@johndoe.one"
       },
       "order":{
          "order.id":"58449798",
          "retailer":{
             "id":"558",
             "name":"HappyShop"
          },
          "amount":240.44,
          "currency":"usd",
          "tags":[
             "fancy",
             "modern",
             "classic",
             "vintage"
          ],
          "items":[
             {
                "itemId":"674",
                "price":175.99,
                "productName":"Product A",
                "productCategory":"Furniture",
                "quantity":1
             },
             {
                "itemId":48,
                "price":12.89,
                "productName":"Product Z",
                "productCategory":"Decoration",
                "quantity":5
             }
          ]
       }
    }
Field name
Source
Path
Result
Description
transactionId
Request – Body
transactionId
1748-2b59-5c78-9c75-f500-274a-88f5-7965
Captures a top-level attribute.
userName
Request – Body
user.userName
johndoe
Captures a nested attribute.
priceOfItems
Request – Body
items.0.price
175.99
Captures the first array item attribute.
Last tag
Request – Body
order.tags.-1
Vintage
Captures the last element of an array.
Second-last tag
Request – Body
order.tags.-2
Classic
Captures the second-last element of an array.
FullBody
Request – Body
*
The entire body as a string
Captures the entire request body.

Examples of data extraction from XML payloads

The extraction of data from XML payloads works with the same syntax as for JSON.

Example 1: Extracting attributes and values from basic XML

<LogoutRequest id=”102030AF”>
      <accountId>100</accountId>
</LogoutRequest>
Field name
Source
Path
Result
Description
LogoutRequest id
Request – Body
LogoutRequest.@id
102030AF
Captures XML tag attribute.
accountId
Request – Body
LogoutRequest.accountId
100
Captures XML tag value.

Example 2: Extracting attributes and values from XML with namespaces

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <Tagh1 xmlns="http://tempuri.org/">
         <Tagh2 cusType="A" xmlns:a="http://schemas.datacontract.org/ex" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:Code i:nil="true" />
            <a:Name>MyCustomer1</a:Name>
            <a:TotalValue>45</a:TotalValue>
         </Tagh2>
      </Tagh1>
   </s:Body>
</s:Envelope>
Field name
Source
Path
Result
Description
CustomerName
Request – Body
s:Envelope.s:Body.Tagh1.Tagh2.a:Name
MyCustomer1
Captures XML tag value.
CustomerType
Request – Body
s:Envelope.s:Body.Tagh1.Tagh2.@cusType
A
Captures XML tag attribute value.

Examples of data capture from requests and responses

Data capture from requests and responses is available for both JSON and XML.

The following table shows examples of how to extract data from requests and is based on the JSON payload example above.

Field name
Source
Path
Result
Description
ContentType
Request – HTTP Header
Content-Type
application/json
Captures a certain request header.
Action
Request – Query String parameters
action
addItems
Captures a certain query string parameter.
  • Field name—RequestHeaders
  • Source—Request – HTTP header
  • Path—*
  • Description—Capture all header attributes
  • Result—All header attributes as a string, separated by spaces
  • Field name—QueryParameters
  • Source—Request – Query string parameters
  • Path—*
  • Description—Capture all query string parameters
  • Result—All query string parameters as a JSON-compatible string

Get business events from RUM

Business events are available for all Dynatrace RUM technologies (web RUM, mobile RUM, and OpenKit). RUM business events can be obtained by leveraging a dedicated method of the RUM JavaScript, OneAgent for mobile, or OpenKit.

Check the sections below for instructions on how to report business events for different platforms.

RUM JavaScript

Android

iOS

Cordova1

Xamarin

Flutter

.NET MAUI

.NET MAUI

React Native

OpenKit

1

To report business events for the native part of Cordova applications, follow the instructions for Android or iOS. For the web part, use the RUM JavaScript.

let attributes = {
    "event.name": "Confirmed Booking",
    "page": "booking-confirmation",
    "product": "Danube Anna Hotel",
    "amount": 358.35,
    "currency": "USD",
    "reviewScore": 4.8,
    "arrivalDate": "2022-11-05",
    "departureDate": "2022-11-15",
    "journeyDuration": 10,
    "adultTravelers": 2,
    "childrenTravelers": 0
};


dynatrace.sendBizEvent('com.easytravel.funnel.booking-finished', attributes);

Business events are only captured for monitored sessions. When the RUM JavaScript is disabled either through a special method or due to cost and traffic control, business events are not reported for such sessions. Note that this behavior might be subject to change in the future, potentially allowing business events to be sent to Dynatrace regardless of session monitoring.