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.
- From the Dynatrace menu, go to Settings > Preferences > OneAgent features.
- Find and enable Send W3C Trace Context HTTP headers.
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 indicate the base URL specific to your Dynatrace deployment and your environment ID.
| Installation Type | Base URL |
|---|---|
| Dynatrace SaaS | https://{your-environment-id}.live.dynatrace.com/api/v2/otlp |
| Dynatrace Managed | https://{your-domain}/e/{your-environment-id}/api/v2/otlp |
| Local Environment ActiveGate | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp |
The following example URLs show combinations of installation and signal types.
-
To send traces to a SaaS deployment, send it to:
https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/traces -
To send metrics to a Managed deployment, send it to:
https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/metrics -
To send logs to a (local) Environment ActiveGate, send it to:
https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp/v1/logs
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 the Dynatrace web UI, 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
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.
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 |
|---|---|
|
|