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 9999. If you changed that port, adjust the port in the URL accordingly.

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 (POST request)
Content encoding support

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.

  1. Go to Settings and select Preferences > Extension Execution Controller.
  2. Turn on Enable Extension Execution Controller.
  3. Turn on Enable local HTTP Metric, Log and Event Ingest API.
  1. Go to Deployment Status and then select OneAgents.
  2. On the OneAgent deployment page, turn off Show new OneAgent deployments.
  3. Filter the table by Host group and select the host group you want to configure.

    The Host group property is not displayed when the selected host doesn't belong to any host group.

    This displays the OneAgent deployment page filtered by the selected host group. Each listed host has a Host group: <group name> link, where <group name> is the name of the host group that you want to configure.
  4. Select the host group name in any row.
    As you have filtered by host group, all displayed hosts go to the same host group.
  1. In the host group settings, select Extension Execution Controller.
  2. Turn on Enable Extension Execution Controller.
  1. Go to Hosts or Hosts Classic (latest Dynatrace).
  2. Find and select your host to display the host overview page.
  3. In the upper-right corner of the host overview page, select More (…) > Settings.
  1. In the host settings, select Extension Execution Controller.
  2. 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/v2/events/ingest.

OneAgent uses by default the TCP port 14499 for this endpoint. You can change the port with oneagentctl.

EEC unavailable on container setups

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 /v2/events/ingest, indicates a JSON content type, and provides the JSON event data using the --data parameter.

curl --request POST --url http://localhost:14499/v2/events/ingest --header "Content-type: application/json" --data "{ \"eventType\": \"AVAILABILITY_EVENT\", \"title\": \"Demo title\" }"

Related topics