Extend event observability
Dynatrace provides a dedicated REST API for the ingestion and management of custom events. The API is available in two principal locations:
ActiveGate, for event ingestion and querying of existing events
OneAgent, for event ingestion only
The full API documentation is available at Events API v2.
Manage events with ActiveGate
Dynatrace supports the following API endpoints for querying and ingesting custom events:
| ActiveGate Type | Base URL |
|---|---|
| Dynatrace SaaS | https://{your-environment-id}.live.dynatrace.com/api/v2/events |
| Environment ActiveGate1 | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/events |
| Containerized Environment ActiveGate | https://{your-activegate-domain}/e/{your-environment-id}/api/v2/events |
1 Environment ActiveGates listen by default on port |
Be sure to specify your environment ID at the correct location in the URL.
Authentication
Authentication is handled using an API access token and the Authorization HTTP header.
Authorization: Api-Token dt.....
To obtain an access token, in Dynatrace, go to Access Tokens. Depending on whether you want to query or ingest events, your token needs the scopes events.read or events.ingest, respectively. You can also combine scopes.
For more information on access tokens, see Dynatrace API - Tokens and authentication.
Network requirements
-
Unfiltered network ports
Make sure the TCP ports used by ActiveGate (either 443 or 9999) are not blocked by a firewall or any other network management solution.
-
Up-to-date SSL trust store
To avoid SSL certificate issues with expired or missing root certificates, make sure your system's certificate trust store is up to date.
curl sample commands
See Events API v2 for a full list of ActiveGate examples for the different request types.
Send events to OneAgent
In addition to ActiveGate, OneAgent also provides a dedicated HTTP (not HTTPS) endpoint for local-only event ingestion. The following restrictions apply:
It is a local-only endpoint, exclusively reachable at 127.0.0.1 (localhost)
- Only event ingestion is supported (
POSTrequest)
OneAgent does not support content compression using the HTTP header Content-Encoding yet. If you need to use content compression, please export to ActiveGate.
To send events to OneAgent, you first need to enable the Extension Execution Controller (EEC). You can do this globally for the whole environment, for host groups, or only for specific hosts.
- Go to Settings and select Preferences > Extension Execution Controller.
- Turn on Enable Extension Execution Controller.
- Turn on Enable local HTTP Metric, Log and Event Ingest API.
- Go to Deployment Status and then select OneAgents.
- On the OneAgent deployment page, turn off Show new OneAgent deployments.
- Filter the table by
Host groupand select the host group you want to configure.This displays the OneAgent deployment page filtered by the selected host group. Each listed host has a Host group:The Host group property is not displayed when the selected host doesn't belong to any host group.
<group name>link, where<group name>is the name of the host group that you want to configure. - Select the host group name in any row.
As you have filtered by host group, all displayed hosts go to the same host group.
- In the host group settings, select Extension Execution Controller.
- Turn on Enable Extension Execution Controller.
- Go to Hosts or Hosts Classic (latest Dynatrace).
Find and select your host to display the host overview page.
- In the upper-right corner of the host overview page, select More (…) > Settings.
- In the host settings, select Extension Execution Controller.
- Turn on Enable Extension Execution Controller.
With EEC enabled, the OneAgent installations on the respective hosts will start accepting requests at the URL http://localhost:14499/events/ingest.
OneAgent uses by default the TCP port 14499 for this endpoint. You can change the port with oneagentctl.
The EEC ingestion endpoint is only available with Full-Stack and Infrastructure Monitoring deployments. It is not available with containerized setups. Use ActiveGate as the export endpoint for container applications.
Authentication
Being a local-only endpoint, OneAgent does not require authentication.
Network requirements
-
Unfiltered network ports
Being a local-only endpoint, there should not be much network configuration required unless you have restricted local network communication, in which case you need to make sure any such restrictions do not apply to the used TCP port (default 14499).
curl sample command
The following curl command sends a POST request to the local OneAgent endpoint at /events/ingest, indicates a JSON content type, and provides the JSON event data using the --data parameter.
curl --request POST --url http://localhost:14499/events/ingest --header "Content-type: application/json" --data "{ \"eventType\": \"AVAILABILITY_EVENT\", \"title\": \"Demo title\" }"