Export with OTLP

The OpenTelemetry Protocol (OTLP) is the principal network protocol for the exchange of telemetry data between OpenTelemetry-backed services and applications.

Dynatrace provides native OTLP endpoints with the following services:

  • The SaaS platform
  • ActiveGate instances
  • OneAgent setups

Additionally, you can deploy the Collector as intermediary service application, to batch requests and improve network performance or transform requests before forwarding them to Dynatrace (for example, mask sensitive data).

otlp

Default ingest paths

The ingest paths used by Dynatrace for the individual signal types follow the standard OpenTelemetry paths.

Signal Type
Path
Traces
/v1/traces
Metrics
/v1/metrics
Logs
/v1/logs

Depending on the configuration, you may need to append these paths individually to the base URLs of the following service endpoints when specifying the export URLs. This can happen either in-code, when using manual instrumentation, or using the standard environment variables.

Export to SaaS and ActiveGate

The following addresses provide the base URLs for your OTLP ingest configuration. Use the URL applicable to your type of environment and replace the relevant part with 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 have the proper topology information. When exporting to OneAgent, this happens automatically.

To do so, make sure your traces have the correct mapping resource attributes set. The list of applicable attributes can be found in (or imported from) the enrichment files.

Export details

Calls to these 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

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 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 the Collector

Using the Collector as an intermediate gateway allows you to streamline and optimize your telemetry data and requests centrally. See Collector use cases for more information and sample configurations for popular Collector use cases.

See Dynatrace Collector for more details on how to configure a Collector instance.

gRPC conversion

As Dynatrace currently requires OTLP exports with HTTP, you can use the Collector to convert gRPC exports to HTTP.

See Transform OTLP gRPC for more details.

Authentication and TLS

Whether you need to use TLS and authenticate your requests against the Collector depends on your particular Collector setup/configuration. By default, the OTLP receiver is configured for plain-text HTTP and does not require authentication.

The eventual outbound connection from the Collector to Dynatrace always requires authentication and TLS.

Network requirements

Verify that the following are true:

  • Network ports not blocked

    Make sure the network ports required by the configured receiver instances are not blocked by a firewall or any other network management solution used as part of your infrastructure.

Export to OneAgent (traces-only)

OneAgent provides a dedicated OTLP endpoint for localhost-only and traces-only OpenTelemetry 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 SaaS, the Collector, or 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.

Export details

Calls to these 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
  • Does not support content compression using the Content-Encoding header

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 endpoints

Ingestion APIOneAgent endpointCollector
  • 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)
  • Support for signal transformation, data redaction, and batching
  • Support for gRPC and JSON

Related topics