Get business events via OneAgent

Latest Dynatrace
How-to guide
Published Oct 24, 2022

OneAgent version 1.253+

OneAgent Full-Stack Monitoring mode is mandatory for the hosts in which you want to capture business events.

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

Go to Settings > Collect and Capture > General monitoring settings > OneAgent features.
Filter by Business events to see supported technologies.
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 it.

Supported technologies

Supported technologies for data extraction from HTTP requests are listed in the tables below.

Data extraction from incoming HTTP requests

Agent	OneAgent feature	Min. version	Technologies supported	Min. version	Compressed body	Full body	Min. version	Compressed body	Full body
	Enablement (event capture)	Enablement (event capture)	Enablement (event capture)	application/json (payload capture)	application/json (payload capture)	application/json (payload capture)	Header: XML (payload capture)¹	Header: XML (payload capture)¹	Header: XML (payload capture)¹
Webserver	Webserver business events	1.253	Apache NGINX IIS	1.253			1.275
.NET	.NET business events	1.253		1.253			1.279
Java	Java business events (incoming HTTP)	1.253	Servlet Tomcat² Jetty JBoss Wildfly Websphere Liberty WebLogic Undertow GlassFish Netty³	1.253			1.275
Node.js	Node.js business events	1.259		1.259			n/a
Golang	Go business events	1.263		1.263	(1.265)		n/a

Supported content types for XML capture on Java are application/xml.

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

Supported from OneAgent version 1.323+. FileRegions aren't supported.

Data extraction from outgoing HTTP requests

Agent	OneAgent feature	Min. version	Technologies supported	Min. version	Compressed body	Full body	Min. version	Compressed body	Full body
	Enablement (event capture)	Enablement (event capture)	Enablement (event capture)	application/json (payload capture)	application/json (payload capture)	application/json (payload capture)	Header: XML (payload capture)¹	Header: XML (payload capture)¹	Header: XML (payload capture)¹
Webserver	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a
.NET	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a
Java	Java business events (outgoing HTTP)	1.297+	HTTP Clients Apache HTTP Client 4.x OK HTTP Client 3.4+	1.297+			1.297+
Node.js	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a
Golang	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a	n/a

Configure business event sources on OneAgent

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.provider`	string	Source of the event. For example, the name of the component or system that generated the event	`easyTrade.com`, `easyTravel.com`
`event.type`	string	The unique type identifier of a given event	`buy-asset`, `sell-asset`, `login`
`event.category`	string	Standard categorization based on the significance of an event according to the ITIL event management standard	`Availability`

To configure business event sources on OneAgent

Go to Settings > Collect and Capture > Business events.
Select between Incoming or Outgoing tab, depending on the type of requests you want to capture:
- Incoming tab captures incoming HTTP requests.
- Outgoing tab captures outgoing HTTP requests.
All rules configured are displayed under these tabs for the appropriate type of request.

To add a new rule, select Add new incoming/outgoing rule and name your rule. To successfully configure a rule, complete the following steps:

1. Definition

Configure your definition by adding the event.provider, event.type, and event.category:

event.provider identifies the source of the event, such as www.easytrade.com.
event.type describes the nature of the event emitted by the source, such as Asset-purchase.
Optional event.category provides additional classification to help add context, for example, add a stock exchange name such as NASDAQ.

2. Triggers

Triggers define the condition that must be met for a business event to be created.

To define a trigger, select:

Data source, such as Request body, Path, or HTTP header
An operator
The value that fulfills the trigger logic OneAgent compares the extracted value from the HTTP request to the condition you define. When the trigger matches, a business event is generated.

Available data sources and use cases:

Data source	Description	Example
Request Path	Defined by the URL path. Use when the endpoint itself identifies the business action.	To capture completed bookings: Data source: `Request - Path`, Operator: `starts with`, Value: `/booking/confirm`
Request - HTTP Method	The HTTP method (GET, POST, PUT, DELETE). Useful for when the same path is used for different semantics depending on method.	For new trade submissions come via POST: Data source: `Request - HTTP Method`, Operator: `equals`, Value: `POST`
Request - HTTP Header	Any request header (single header or wildcard (`*`))	Identify specific host traffic: Data source: `Request - HTTP Header`, Path: `Host`, Operator: `equals`, Value: `10.176.64.156:8079`
Request - Query String Parameters	Named query parameters in the request URL. Use to detect mode/operation that's encoded into query strings.	Capture promotional booking flows: Data source: `Request - Query String Parameters`, Path: `promo`, Operator: `equals`, Value: `summer21`
Request - Request Body	Full request payload (JSON/XML). Can be used for content-based business triggers, such as `order.amount` or `user.id`.	Flag specific purchase types: Data source: `Request - Request Body`, Path: `order.type`, Operator: `equals`, Value: `buy-asset`
Response - Body	Can be used when the server response determines whether an event should be created. For example, success payload contains IDs/flags.	Capture only when backend services confirm booking: Data source: `Response - Body`, Path: `order.status`, Operator: `equals`, Value: `confirmed`
Response - HTTP Header	Any header returned in the response. For example, `Order-Status` or `Set-Cookie`.	Data source: `Response - HTTP Header`, Path: `content-type`, Operator: `equals`, Value: `application/javascript`
Response - HTTP Status Code	Numeric HTTP status code (2xx/4xx/5xx)	Capture based on record created trades: Data source: `Response - HTTP Status Code`, Operator: `equals`, Value: `201`

Default Trigger values are case-insensitive by default. Enable Case-sensitive if the trigger should consider letter casing.
Recommended 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.

Tips

Triggers within the same rule are connected by AND logic within a rule; if you set multiple triggers, all conditions need to be fulfilled to capture a business event.
Avoid creating triggers with value of /. This can lead to overloading and shutting down your application environment.

3. Data fields

Data fields can be used to add event attributes for more granular insights. Attributes are data fields extracted from the event JSON or XML payload.

Select Add data field.
Provide a field name and select the data source type and path 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:
- How many accounts purchased a particular asset?
- Which assets are purchased most often?
- Which accounts make the largest asset purchases?

Example buy-asset request JSON file

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

Select Save.
Ensure that the rule is set to Enabled.

Once a rule is enabled, verify that it's capturing business events by checking the Status column on the Incoming or Outgoing tab.

The Status column shows the number of business events the rule generated over the last 6 hours, allowing you to confirm the rule is actively capturing events.

The first matching rule is executed per OneAgent request. Capture rules are evaluated by all OneAgents deployed across your environment until a OneAgent detects a match. Once a rule matches the HTTP request, that rule is executed and the capture process stops.

Scope capture rules with OneAgent

Capture rules can also be defined at the host or host-group level to limit the scope of data collection. Scoping reduces noise and the processing overhead on OneAgent by limiting which agents evaluate and apply the rule. To change the scope, switch the entity under the environment selector:

Go to Settings and switch the Environment selector from the global environment to the target entity.
Select the host group or individual host you want the rule to apply to.
Follow the same capture-rule configuration steps by going into Collect and Capture > Business events and adding a new capture rule.

After saving the capture rule, it will be evaluated only by OneAgents that belong to that host or host-group.

Capturing variants feature

This feature is available for OneAgent version 1.309+ on .NET. For all other technologies, apply the technology support table.

Use capturing variants to define how incoming and outgoing business events should be parsed according to their Content-Type header. Dynatrace applies a set of default parsing rules, which:

Can be overridden or extended per environment.
Are processed in a top-down order, with the first matching rule taking precedence.

Content-type	Parser
`*/json`	JSON
`*/xml`	XML
`application/x-www-form-urlencoded`	URL encoded
`text/plain`	Text
`application/octet-stream`	Raw/Binary

Capturing variants apply on the global level and are therefore used for all deployed agents on supported technologies.

Example of data extraction from JSON payloads

The following table shows additional examples of how to extract data from 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.

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

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

Example of header wildcard capture

Field name: RequestHeaders
Source: Request – HTTP header
Path: *
Description: Capture all header attributes
Result: All header attributes as a string, separated by spaces

Example of query string wildcard capture

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

Limits in business events

OneAgent enforces practical safeguards to protect performance and stability when capturing business events. Environment defaults include safeguards on the number of capture rules per environment which are commonly configured at 100 rules and request/response body capture sizes of approximately 64 KiB. These safeguards aren't immutable platform blocks and can be adjusted to fit your environment.

Contact your customer success representative. As an alternative to increasing these safeguards, consider using API ingestion for large events or using OpenPipeline.