• Home
  • Platform modules
  • Business Analytics in Dynatrace
  • Business event capture

Business event capture

powered by Grail

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

There are three sources for business events:

  • OneAgent

    Configure using the Dynatrace menu to add capture rules, triggers, data fields, and more.

  • Web and mobile RUM

    RUM business events can be obtained 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 1.253+

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

  1. In the Dynatrace menu, go to Settings > Preferences > OneAgent features.
  2. Enable the OneAgent business events feature for the technologies appropriate for your environment such as .NET, Java, or Webserver.
    Note: you need to restart the application process before you can capture business events from that process.

OneAgent can capture business events from incoming HTTP requests. Configuration requires one or more capture rules that consist of triggers, mandatory data fields, and optional event data fields.

Examples of mandatory (event.type, event.provider) and optional (event.category) data fields:

FieldTypeDescriptionExamples
event.categorystringStandard categorization based on the significance of an event according to the ITIL event management standardAvailability
event.typestringThe unique type identifier of a given event.buy-asset, sell-asset, login
event.providerstringSource of the event, for example the name of the component or system that generated the event.OneAgent, easyTrade.com, easyTravel.com

Configure business event sources on OneAgent

OneAgent 1.253+

To configure business event sources on OneAgent:

  1. In the Dynatrace menu, go to Settings > Business Analytics > Business Event Sources > OneAgent.

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

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

    Determine the data source for your trigger, such as Body, Path, or HTTP header, and 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 tab displays the entire trigger rule (for example, Request - Path starts with '/api/trade/BuyAssets).
    • By default, the search for value is not case-sensitive. Turn on Case sensitive if you want your trigger to consider the case of the source.
    • Triggers are connected with AND, so if you set multiple trigger rules, all of them must be fulfilled to capture a business event.
    • The first matching rule get executed per Agent per request.
    • It is recommended to set specific trigger rules. If a trigger rule is too general and results in multiple identical rule matches, you will get multiple business events.
  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 Event type source and value.
    This describes the type of event the event provider is sending, such as Asset purchase.

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

    You now have configured 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. Attributes are data fields extracted from the event JSON payload.

  7. Select Add data field in Event data. Provide a field name, and then provide the data source and value from the JSON 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 most often purchased, or which accounts make the largest asset purchases.

The buy-asset request JSON file:

json
{ "accountId":6, "amount":10, "instrumentId":1, "price":157.025 }
  1. Select Save changes.

Example of data extraction

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

Example request-payload JSON file for OneAgent
  • 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:

json
{ "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":[ "fency", "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 nameSourcePathDescription

transactionId

Request-Body

transactionId

Example of capturing a top-level attribute

userName

Request-Body

user.userName

Example of capturing a nested attribute

priceOfItems

Request-Body

items.0.price

Example of capturing the first array item attribute

Last tag

Request-Body

tags.-1

Example of capturing the last element of an array

Second last tag

Request-Body

tags.-2

Example of capturing the second last element of an array

FullBody

Request-Body

*

Example of capturing a full request body

ContentType

Request-HTTP Header

Content-Type

Example of capturing a certain request header

Action

Request-Query String parameters

action

Example of capturing a certain query string parameter

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.

To enable RUM business events, please contact a Dynatrace ONE product specialist by selecting the chat button in the upper-right corner of the Dynatrace menu bar.

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

RUM JavaScript

Android

iOS

Cordova1

Xamarin

Flutter

React Native

OpenKit

1

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

Send business events via RUM JavaScript
json
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);

Ingest business events from API

Business Analytics offers a dedicated API to ingest JSON format data into Dynatrace.
To access the dedicated Environment API:

  1. In Dynatrace, open the User menu by selecting the User icon in the upper-right corner.

  2. Select Environment API v2.

  3. Expand Business events, then POST section.

    • Endpoint-Url: [https://\|https:] {environmentId}.dynatrace.com/api/v2/bizevents/ingest
    • Method: POST
    • Authentication: OAuth

    Note: Business Events API limits the data size to 1 MB per request.

Request body

  • Pure JSON: no mandatory fields are required for ingest

Example payload using pure JSON:

json
{ "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}", "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}", "amount": {% randomnumber 1, 10000, 0, 0 %}, "event.type": "com.bizingest.json.flat" }

In addition to the pure JSON format, Dynatrace offers the CloudEvent and the CloudEvent Batch formats.

  • CloudEvent
Example payload using CloudEvent

CloudEvent (application/cloudevent+json)

json
{ "specversion": "1.0", "id": "{% uuid 'v4' %}", "source": "ba.dt.local", "type": "com.dynatrace.business", "time": "{% now 'iso-8601', '' %}", "data": { "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}", "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}", "nested": { "firstName": "Max", "lastName": "Meyer" } } }
  • In the CloudEvent standard, mandatory fields exist and can be enriched by additional data fields. The mandatory fields are:

    • Specversion
    • Source - automatically converted into event.provider
    • Type - automatically converted into event.type
    • Id - automatically converted into event.id

    Note: Your additional data need to be added in the data object fields. In the example above, the additional data is paymentId, orderId, firstName, and lastName.

  • CloudEvent batch (batch ingest of events): as in the previous example, mandatory fields exist and can be enriched by additional data fields, such as paymentId and orderId.

Example payload using CloudEvent batch

CloudEvent batch (application/cloudevent-batch+json)

json
[ { "specversion": "1.0", "id": "{% uuid 'v4' %}", "source": "ba.dt.local", "type": "com.dynatrace.business", "time": "{% now 'iso-8601', '' %}", "data": { "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}", "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}" } }, { "specversion": "1.0", "id": "{% uuid 'v4' %}", "source": "ba.dt.local", "type": "com.dynatrace.business", "time": "{% now 'iso-8601', '' %}", "data": { "paymentId": "pid-{% randomnumber 1, 10000, 0, 0 %}", "orderId": "oid-{% randomnumber 1, 10000, 0, 0 %}" } } ]

Set up OAuth for API access

To set up OAuth for API access, perform the following steps:

Create a new OAuth client

Create a new policy

Grant the policy to a group

Obtain an access token

Create a new OAuth client

You can create new OAuth clients on the account management page in your Dynatrace tenant, following the steps mentioned below.

  1. In the user menu in the upper-right corner of the page, go to Account management > Account Management API > Create new Client.
  2. Provide a description and email addresses of your users.
  3. Choose the needed scope by selecting one or more options: Read logs, Edit logs, Read metrics, Edit metrics, Read events, and Write/edit events.
  4. Select Generate client. Make sure to save your client's secret since you won't have the chance to see it again.

Create a new policy

To create a new policy

  1. In the user menu in the upper-right corner of the page, go to Account management > Identity management > Policy management.
  2. Select Add policy, name the policy and following policy statement:
    Allow storage:events:read, storage:events:write

Grant the policy to a group

You can assign the new policy to a group where your user belongs, or create a new group where you will add your user.

  1. In the user menu in the upper-right corner of the page, go to Account management > Identity management > Group management.
  2. Select Edit to edit a group, go to the Policies tab, and select the policies that you need to bind (for example, the ones you created).
  3. Select Save.

If you have access to multiple tenants, make sure that you work on the right one. You get an overview of all tenants by selecting Accounts in the upper left corner below the Dynatrace logo.

Obtain an access token

You can use the newly created OAuth client to obtain an access token for the API. Follow the OAuth 2.0 flow as described below and send a request to the access token url. You will receive a bearer access token that you can use for authentication in the other endpoints.

  • Method: POST

  • Grant Type: client_credentials

  • Access Token Url:

    • Live: https://sso.dynatrace.com/sso/oauth2/token
  • Client Id: your client ID

  • Client Secret: your client secret

  • Scope: storage:events:read, storage:events:write

  • If possible, send client credentials in the header.

Example API request
plaintext
POST /sso/oauth2/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded User-Agent: PostmanRuntime/7.29.0 Accept: */* Cache-Control: no-cache Postman-Token: 3823770b-3db8-42b3-bcd1-29391b300d4a Host: sso.dynatrace.com Accept-Encoding: gzip, deflate, br Connection: keep-alive Content-Length: 258 Cookie: AWSALB=Nw8l8nM4JmCdXHSRBqi8Sq/PbJzZXff/q0UAaBV6vIjN5Zb34ZZ5lmr3eux3R+2ggjZbh6H0eQu6DMrJoGbHBldkaNrchJFwF7WTaXyVX766I4GAlL/vVlvbSIMZ; AWSALBCORS=Nw8l8nM4JmCdXHSRBqi8Sq/PbJzZXff/q0UAaBV6vIjN5Zb34ZZ5lmr3eux3R+2ggjZbh6H0eQu6DMrJoGbHBldkaNrchJFwF7WTaXyVX766I4GAlL/vVlvbSIMZ grant_type=client_credentials&scope=storage%3Aevents%3Awrite%2Cstorage%3Aevents%3Aread%2Cstorage%3Alogs%3Aread%2Cstorage%3Ametrics%3Aread&client_id=dt0s02.XZF73LAL&client_secret=dt0s02.XZF73LAL.YW557U7TX6PVIPNSRZRZ5BHFMNZKYUW54IX327JX7XFXDGJ5LLXXU3JQDP3WUEUX
Example API response
plaintext
TTP/1.1 200 OK Date: Thu, 01 Sep 2022 05:15:12 GMT Content-Type: application/json Content-Length: 1060 Connection: keep-alive Set-Cookie: AWSALB=Dxxl1OSC7nq1HaIF9CzQxmKyqxDyYigbnd2QB0ZtMJ9yKDzgkxMubR/uT7XpatOrThreoACtEQ+fF7kbHz7SUBRzdsHzUHIqr36V8Rf3JL9Uk/HNQDKxf3PeBrwW; Expires=Thu, 08 Sep 2022 05:15:12 GMT; Path=/ Set-Cookie: AWSALBCORS=Dxxl1OSC7nq1HaIF9CzQxmKyqxDyYigbnd2QB0ZtMJ9yKDzgkxMubR/uT7XpatOrThreoACtEQ+fF7kbHz7SUBRzdsHzUHIqr36V8Rf3JL9Uk/HNQDKxf3PeBrwW; Expires=Thu, 08 Sep 2022 05:15:12 GMT; Path=/; SameSite=None; Secure X-Frame-Options: deny Frame-Options: deny X-XSS-Protection: 1; mode=block X-Content-Type-Options: nosniff Content-Security-Policy: default-src 'self' https://static.sso-sprint.dynatracelabs.com; script-src 'self' 'unsafe-inline' https://static.sso-sprint.dynatracelabs.com; frame-ancestors 'none'; form-action http: https:; report-uri https://report-csp.internal.dynatracelabs.com/sso2.0 X-Content-Security-Policy: default-src 'self' https://static.sso-sprint.dynatracelabs.com; script-src 'self' 'unsafe-inline' https://static.sso-sprint.dynatracelabs.com; frame-ancestors 'none'; form-action http: https:; report-uri https://report-csp.internal.dynatracelabs.com/sso2.0 Strict-Transport-Security: max-age=31536000; preload Cache-Control: no-cache, no-store, no-transform Pragma: no-cache {"scope":"storage:events:read storage:events:write","token_type":"Bearer","expires_in":300,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiI2YWUwMmFmNC01NmIwLTRhM2MtODI0OS1mYjc2ZDgyOTYwYTQiLCJhdWQiOiJkdDBzMDIuWFpGNzNMQUwiLCJyZXMiOiJ1cm46ZHRhY2NvdW50OmU3NDk2NjRjLTEzMDItNDM1NS05ZTRiLTdkYTk0Yzg3YzI4MCIsIl9jbGFpbV9uYW1lcyI6eyJncm91cHMiOiIwIn0sInNjb3BlIjoic3RvcmFnZTpldmVudHM6d3JpdGUgc3RvcmFnZTpldmVudHM6cmVhZCBzdG9yYWdlOmxvZ3M6cmVhZCBzdG9yYWdlOm1ldHJpY3M6cmVhZCIsIl9jbGFpbV9zb3VyY2VzIjp7IjAiOnsiZW5kcG9pbnQiOiJodHRwczovL3Nzby1zcHJpbnQuZHluYXRyYWNlbGFicy5jb206NDQzL3Nzby9vYXV0aDIvdXNlcmluZm8ifX0sInByZWZlcnJlZF91c2VybmFtZSI6ImRhbmllbC5tYXJzY2huaWdAZHluYXRyYWNlLmNvbSIsImV4cCI6MTY2MjAwOTYxMiwiaWF0IjoxNjYyMDA5MzEyLCJndCI6ImNjIiwianRpIjoiMzJhMTE3YWItOThkMi00YzY5LWE2OWYtMzJhZDc0YTgwZTQ1IiwiZW1haWwiOiJkYW5pZWwubWFyc2NobmlnQGR5bmF0cmFjZS5jb20ifQ.57JYBhpkK8shV07qEb7_rZOOjonv0pp8h2iwYFWmnnZHp5DWK_ndmpt8ulruIVnBRpQsZ_RKa_HIWj4t-O07Eg","resource":"urn:dtaccount:e749664c-1302-4355-9e4b-7da94c87c280"}

Business event enrichment

When you report business events, Dynatrace enriches them by adding additional context. For example, Dynatrace adds information about your application, geolocation, device, and more.

For details, see Business event enrichment.