Export with OTLP
While automatic ingestion with OneAgent is the preferable and most convenient approach for traces, Dynatrace also supports OTLP natively, which can be useful if automatic ingestion is not possible for your use case (for example, for metrics and logs or when using unsupported languages).
Dynatrace provides OTLP endpoints in two principal locations
ActiveGate (the SaaS backend, Managed setups, and individual Environment ActiveGates)
OneAgent
OTLP details
Calls to either endpoint (ActiveGate or OneAgent) need to adhere to the following protocol details:
Use of HTTP—gRPC is not yet supported
Use of the binary format of Protocol Buffers—JSON is not yet supported
Also, make sure Send W3C Trace Context HTTP headers is enabled.
- Go to Settings > Preferences > OneAgent features.
- Find and enable Send W3C Trace Context HTTP headers.
The protocol specification can be found at OpenTelemetry Protocol (OTLP) ingest API.
Export to ActiveGate
ActiveGate provides endpoints for all three signal types (traces, metrics, and logs) under OpenTelemetry's default paths.
| Signal Type | Path |
|---|---|
| Traces | /v1/traces |
| Metrics | /v1/metrics |
| Logs | /v1/logs |
Using these paths, you only need to prepend one of the following base URLs, applicable to the type of ActiveGate, and specify your environment ID.
| ActiveGate Type | Base URL |
|---|---|
| Dynatrace SaaS | https://{your-environment-id}.live.dynatrace.com/api/v2/otlp |
| Environment ActiveGate1 | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp |
| Containerized Environment ActiveGate2 | https://{your-activegate-domain}/e/{your-environment-id}/api/v2/otlp |
1 Environment ActiveGates listen by default on port 2 Containerized ActiveGates do not support OTLP log ingest yet. |
The following example URLs illustrate combinations of base URLs and paths for signal types.
| ActiveGate Type | Signal Type | URL |
|---|---|---|
SaaS | Traces |
|
Metrics |
| |
Logs |
| |
Environment ActiveGate1 | Traces |
|
Metrics |
| |
Logs2 |
| |
1 Environment ActiveGates listen by default on port 2 Containerized ActiveGates do not support OTLP log ingest yet. | ||
Vanilla OTLP exports to ActiveGate require manual enrichment of Dynatrace host information to count towards any included OneAgent DDU quota. When using OneAgent, this happens automatically.
To do so, please make sure your traces have the correct mapping resource attributes set. The list of applicable attributes can be found in (or imported from) the file dt_metadata.properties (in /var/lib/dynatrace/enrichment/ on Unix, %ProgramData%\dynatrace\enrichment\ on Windows), as well as from dt_metadata_e617c525669e072eebe3d0f08212e8f2.
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. Use the following access scopes for the signals you are exporting.
| Signal Type | Access Scope |
|---|---|
| Traces | openTelemetryTrace.ingest |
| Metrics | metrics.ingest |
| Logs | logs.ingest |
Of course, you can also combine scopes. For more information on access tokens, see Dynatrace API - Tokens and authentication.
Network requirements
Verify that the following are true:
-
TCP port is not blocked
Because OTLP communication with ActiveGate takes place over the ports 443 (for SaaS and Managed) or 9999 (for Environment ActiveGates), make sure that the TCP port in question is not blocked by a firewall or any other network management solution you might be using.
-
Your system's certificate trust store is up to date
To avoid any possible SSL certificate issues with expired or missing default root certificates, make sure that your system's certificate trust store is up to date.
Export to OneAgent (traces-only)
In addition to automatic OpenTelemetry instrumentation, OneAgent provides a dedicated HTTP endpoint for local-only and traces-only OTLP exports.
- Local-only means OneAgent provides the endpoint exclusively at
127.0.0.1(localhost) Traces-only means OneAgent only accepts tracing information, not metrics or logs
OneAgent does not support content compression using the HTTP header Content-Encoding yet. Pay particular attention to that when instrumenting a Ruby application as the OpenTelemetry SDK for Ruby uses by default Content-Encoding: gzip.
If you need to use content compression, please export to ActiveGate.
To send traces to OneAgent, you first need to enable the Extension Execution Controller. 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 the EEC enabled, the OneAgent installations on the respective hosts will start accepting OTLP traces on URL http://localhost:14499/otlp/v1/traces.
OneAgent uses the TCP port 14499 as default port 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. Please use ActiveGate as export endpoint for container applications.
Authentication
Because it's a local-only endpoint, OneAgent does not require authentication.
Network requirements
-
Make sure there are no local restrictions for the used TCP port (default: 14499)
Because the OTLP communication is exclusively local, there should not be much network configuration to consider unless you have restricted local network communication, in which case you need to make sure there are no local restrictions on the used TCP port (default: 14499).
Comparison of ingestion API and OneAgent endpoint
| Ingestion API | OneAgent endpoint |
|---|---|
|
|