Ingest business events via API
powered by Grail
You can configure external business or IT systems to send business events to Dynatrace via API. Additionally, you can query data using DQL via API. For both API approaches, you need a valid bearer token for authentication, which you request by setting up OAuth for API access.
- Latest Dynatrace Business Analytics offers the Business events API to ingest JSON-format data into Dynatrace via the
/bizevents/ingest
endpoint. - Latest Dynatrace The Grail - DQL Query API enables you to access records stored in Grail by making DQL queries via API.
Set up and use OAuth for API access
Before you begin, you need to set up OAuth for API access.
Create an OAuth client
Create an IAM policy
Bind the policy to a group
Obtain a bearer token
Authenticate
Create an OAuth client
You can create new OAuth clients on the Account Management page of your Dynatrace environment.
-
From the user menu, select Account settings (previous Dynatrace) or Account Management (latest Dynatrace).
If you have access to multiple Dynatrace environments, be sure to select the correct one.
-
From the top navigation bar, select Identity & access management > OAuth clients.
-
Select Create client.
-
Provide the email address of the user who will own the client.
-
Provide a description for the new client.
-
Ensure that your client has the required permissions by selecting one or more options during client setup. For reading and writing business events, you require:
- Read bizevents: (
storage:bizevents:read
) - Read buckets: (
storage:buckets:read
) - Write/edit events (
storage:events:write
) (only necessary for ingesting data via the Business events API)
- Read bizevents: (
-
Select Create client.
-
Save the generated client secret to a password manager for future use. You will also require the generated client ID when obtaining a bearer token.
The client secret is only displayed once upon creation, after which it's stored encrypted and can't be revealed.
Create an IAM policy
To use the OAuth client, you need to ensure that the right IAM policy is assigned to your user.
To set up the policy
-
From the user menu, select Account settings (previous Dynatrace) or Account Management (latest Dynatrace).
If you have access to multiple Dynatrace environments, be sure to select the correct one.
-
From the top navigation bar, select Identity & access management > Policies.
-
Select Create policy and set up the policy name and description. You'll need this information when bind this policy to a user group later. Read more about policy management in Manage IAM policies.
-
Add the following policy statements for writing and querying business events.
ALLOW storage:buckets:read WHERE storage:table-name = "bizevents"; ALLOW storage:bizevents:read; ALLOW storage:events:write;
-
Select Create policy.
Bind the policy to a group
You can assign the policy you created to a group that your user belongs to or add your user to a new group. See Manage group permissions with IAM policies for instructions on binding policies to groups.
Obtain a bearer token
You can use the OAuth client to obtain an OAuth 2.0 bearer token. Use the information below send a request to the bearer token URL. Use the token you receive in the response to authenticate to the Business events API or the Grail - DQL Query API.
-
Endpoint URL for requesting a token—
https://sso.dynatrace.com/sso/oauth2/token
-
Method—POST
-
Content-Type
header—application/x-www-form-urlencoded
-
Headers—You can send the following keys or parameters in the request body. Make sure to URL encode all values.
Key/Parameter Value Required grant_type
client_credentials
required
client_id
dt0s02.****
—This is the client ID generated when you created an OAuth client.required
client_secret
dt0s02.***.****
—This is the client secret generated when you created an OAuth client.required
scope
A list of required scopes separated by a whitespace, for example,
storage:bizevents:read storage:buckets:read storage:events:write
You can assign multiple scopes to a single token, or you can generate several tokens, each with different access levels and use them accordingly—check your organization's security policies for the best practice.
required
resource
urn:dtaccount:{your-account-UUID}
optional if not defined in the client
required if defined in the client, with the same value as in the client
Authenticate
To authenticate a call, attach the token to the Authorization
HTTP header preceding the Bearer
realm.
--header 'Authorization: Bearer abcdefjhij1234567890'
Business events API: /bizevents/ingest
endpoint
Latest Dynatrace Business Analytics offers the Business events API to ingest JSON data into Dynatrace via the POST method of the /bizevents/ingest
endpoint.
To view Swagger documentation and try out this API in the latest Dynatrace
- Search for "API" or "Dynatrace API."
- From the dropdown list in the top-right corner of the page, select Classic Environment API v2.
- Expand Business events, then /bizevents/ingest.
In the previous Dynatrace
- From the user menu, select Environment API v2.
- Expand Business events, then /bizevents/ingest.
- Endpoint URL
- Latest Dynatrace
https://{your-environment-id}.apps.dynatrace.com/platform/classic/environment-api/v2/bizevents/ingest
- Previous Dynatrace
https://{your-environment-id}.live.dynatrace.com/api/v2/bizevents/ingest
- Latest Dynatrace
- Method—POST
- Authentication—OAuth
Content-Type
header—varies based on the payload format.- Pure JSON:
application/json
- CloudEvents:
application/cloudevent+json
- CloudEvents batch:
application/cloudevent-batch+json
- Pure JSON:
- Request body—
{your event}
—see the examples below.
Note that when ingesting business events, Dynatrace stores ingested top-level fields as top-level fields in Grail but converts complex JSON objects into strings—see the customer
field in the example Grail event below.
Supported request formats and examples
In addition to the pure JSON format, Dynatrace offers the CloudEvents and CloudEvents batch payload formats, specified in the Content-Type
request header.
All three formats support the same request payloads. The Business events API limits payload size to 1 MB per request.
-
Pure JSON
There are no mandatory fields.
-
CloudEvents
In the CloudEvents standard, these required fields can be enriched by additional data fields.
specversion
source
—Automatically converted toevent.provider
type
—Automatically converted toevent.type
id
—Automatically converted toevent.id
Provide additional data in the
data
object fields. In the example below, the additional data ispaymentId
,orderId
, andperson
. -
CloudEvents batch
The CloudEvents batch mode enables the ingestion of multiple events at a time. As in the previous example, required fields can be enriched by additional data fields, such as
paymentId
andorderId
.
Business event enrichment
When you report business events, Dynatrace enriches them by adding more context. For example, Dynatrace adds information about your application, geolocation, device, and more. Pertains only data ingested via Business events API.
For details, see Business event enrichment.
DQL queries via API
Latest Dynatrace The Dynatrace Grail - DQL Query API enables third-party applications to retrieve data from Grail by executing DQL queries via API. You can only query data, not ingest it via this API.
To view Swagger documentation and try out this API in the latest Dynatrace
- Search for "API" or "Dynatrace API."
- From the dropdown list in the top-right corner of the page, select Grail - DQL Query.
- Expand Query Execution to view its methods.
To run a query and to retrieve its result, you need to make two requests via separate methods.
- To query Grail, execute the POST
/query:execute
request. - To retrieve the result, execute the GET
/query:poll
request.
POST /query:execute method
- Endpoint URL—
https://{your-environment-id}.apps.dynatrace.com/platform/storage/query/v1/query:execute
- Method—POST
- Authentication—OAuth
Content-Type
header—application/json
- Request body—
{your DQL query}
Request body example
{
"query": "fetch bizevents | summarize Count()"
}
Response body example
You will need to use the requestToken
value from this response in the /query:poll
request.
{
"state": "SUCCEEDED",
"requestToken": " +kuSj8qvRvq64GkG5CEHag==",
"progress": 100
}
GET /query:poll method
- Endpoint URL—
https://{your-environment-id}.apps.dynatrace.com/platform/storage/query/v1/query:poll
- Method—GET
- Authentication—OAuth
Content-Type
header—application/json
(Pure JSON)- GET parameter—
request-token
, used to identify the executed POST query
Request URL example
https://mySampleEnv.apps.dynatrace.com/platform/storage/query/v1/query:poll?request-token=%2BkuSj8qvRvq64GkG5CEHag%3D%3D
Response body example
{
"state": "SUCCEEDED",
"progress": 100,
"result": {
"records": [
{
"count()": "0"
}
],
"types": [
{
"indexRange": [
0,
0
],
"mappings": {
"count()": {
"type": "long"
}
}
}
],
"metadata": {
"grail": {
"canonicalQuery": "fetch bizevents\n| summarize count()",
"timezone": "Z",
"query": "fetch bizevents | summarize Count()",
"scannedRecords": 0,
"dqlVersion": "V1_0",
"scannedBytes": 0,
"analysisTimeframe": {
"start": "2023-07-11T07:28:11.068767000Z",
"end": "2023-07-11T09:28:11.068767000Z"
},
"locale": "",
"executionTimeMilliseconds": 4155,
"notifications": [],
"queryId": "fa4b928f-caaf-46fa-bae0-6906e421076a",
"sampled": false
}
}
}
}