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 the API endpoints 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.

  1. Go to Settings > Preferences > OneAgent features.
  2. Find and enable Send W3C Trace Context HTTP headers.

The protocol specification can be found at OpenTelemetry Protocol (OTLP) ingest API.

Export to SaaS and ActiveGate

The SaaS endpoint and ActiveGate instances provide 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 environment, 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 9999. If you changed that port, adjust the port in the URL accordingly.

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 TypeSignal TypeURL

SaaS

Traces

https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/traces

Metrics

https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/metrics

Logs

https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/logs

Environment ActiveGate1

Traces

https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp/v1/traces

Metrics

https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp/v1/metrics

Logs2

https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp/v1/logs

1

Environment ActiveGates listen by default on port 9999. If you changed that port, adjust the port in the URL accordingly.

2

Containerized ActiveGates do not support OTLP log ingest yet.

Information enrichment

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
Content encoding support

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.

  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 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.

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. 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 APIOneAgent endpoint
  • Supports all OpenTelemetry signals (traces, metrics, logs)
  • No automatic information enrichment
  • SSL and authentication
  • Support for content compression (using Content-Encoding)
  • No support for metrics and logs (only traces)
  • Automatic information enrichment
  • No authentication
  • No support for content compression (using Content-Encoding)

Related topics