Dynatrace OTel Collector: migrating from Contrib safely

Your Collector runs the Contrib image, and someone has asked you to move to the Dynatrace OTel Collector. Before you touch a line of configuration, one question matters: what actually changes? This article skips the tour of Contrib, which our Contrib components guide already covers. It looks only at the gap between the two builds and at the migration path.

What I read: the introduction and deployment pages of the Dynatrace documentation, then the README of the GitHub repository, on 9 November 2026. Version numbers are those shown on those pages that day. I did not run the binary, so anything about runtime behaviour is flagged as unverified.

Dynatrace OTel Collector: a curated subset, not a fork

The documentation is explicit. The distribution keeps the standard configuration model and component semantics, with no proprietary abstractions and no hidden defaults. In practice, a YAML file written for Contrib stays readable as it is. The difference lies in what is compiled into the binary.

Contrib ships a very large number of third-party receivers, processors and exporters. Dynatrace advises against it in production and keeps it for testing, because it uses more storage and memory than a targeted build. The Dynatrace distribution contains only components the vendor says it has verified for common use cases. The full list lives in the GitHub repository, not in the documentation.

What the distribution removes: read the list before you switch

This is where migrations go wrong. A component missing from the binary stops the Collector from starting, because it rejects a configuration that names an unknown component. Here is what I found in the README’s Components section.

Source : github.com

• Receivers: otlp, filelog, hostmetrics, prometheus, statsd, syslog, fluentforward, jaeger, zipkin, kafka, kafka_metrics and four Kubernetes receivers (k8sobjects, k8scluster, kubelet_stats, k8sevents). Journald and netflow are alpha.
• Processors: batch, memory_limiter, attributes, resource, resource_detection, transform, k8sattributes, cumulativetodelta, metricstarttime, probabilistic_sampler, tail_sampling and groupbytrace, plus filter, redaction and genainormalizer in alpha.
• Exporters: otlp, otlphttp, debug and kafka, plus load_balancing in alpha.
• Extensions and connectors: bearertokenauth, oidcauth, healthcheck, zpages, k8sleaderelector and filestorage; forward and, in alpha, spanmetrics.

I could not find a Prometheus Remote Write exporter, a file exporter, a SQL receiver or a Docker receiver in that list. If your pipelines rely on one of them, you need another route. That absence comes from my reading of the README. I did not compile the binary to confirm it.

What you get in return

The distribution adds no hidden feature. It adds guarantees around the binary.

• Bounded vendor support: x86-64 and ARM64 builds are covered by Dynatrace Support. Each minor version is supported for three months, with fixes shipped as a patch on the latest supported minor or in the next minor.
• Independent security patches: Dynatrace says it receives them without waiting for upstream Collector releases.
• Signed images: they are signed with cosign from version 0.49.0 and published on GHCR, Amazon ECR Public and Docker Hub.
• Limited support for everything else: for Contrib, Dynatrace only covers the components and versions present in its own distribution. GitHub issues are handled on a best-effort basis, with no contract or SLA.

So the trade is fewer components for a supported perimeter. For an SRE team, it also means less surface to patch, and therefore less toil with every CVE.

Migrating from Contrib in five steps

This is the route I would follow. It starts from your real configuration, not from the documentation.

1. List the components you use. With yq (version 4), print what your pipelines name, then the extensions:

yq '.service.pipelines[] | .receivers[], .processors[], .exporters[]' config.yaml \
  | sed 's#/.*##' | sort -u
yq '.service.extensions[]' config.yaml | sed 's#/.*##' | sort -u

1. Compare with the repository list. Each missing component falls into one of three cases: drop it, replace it, or keep it in a second Contrib or OCB Collector upstream.
2. Wire up the Dynatrace exporter. The deployment page gives the example below, reading the endpoint and token from the environment:

Source : docs.dynatrace.com

1. Change the image or package. The deployment page points to version 0.60.0 (dynatrace/dynatrace-otel-collector:0.60.0 on Docker Hub). Pin an exact version rather than latest.
2. Switch gradually. Move one gateway first, compare, then extend to the agents.

One detail to test: the documentation example names the exporter otlp_http, while many Contrib configurations write otlphttp. I do not know whether version 0.60.0 accepts both names. Run the validation before you roll out widely.

How to check that it works

Validate the file first, then watch the signals. One command covers the first part:

./dynatrace-otel-collector validate --config=config.yaml

That subcommand exists in the upstream Collector, but I did not test it on this binary. It catches unknown components before deployment. After that, on the operations side:

• Temporarily add the debug exporter to watch data go by.
• Enable the healthcheck extension: the Helm examples in the documentation expose it on port 13133.
• Compare received and exported volumes before and after, signal by signal.
• In Dynatrace, confirm that traces arrive, for example using the attributes described in the anatomy of an OpenTelemetry span.

Deploying: three routes on Kubernetes

The deployment page separates agent mode (a Collector next to the application) from gateway mode (a standalone service, often one per cluster). On Kubernetes, three routes exist:

• the Dynatrace Operator, from version 1.11.0, which resolves the Collector image by itself (see our Dynatrace Operator guide);
• the OpenTelemetry Operator, which requires cert-manager (see the OpenTelemetry Operator article);
• the open-telemetry/opentelemetry-collector Helm chart, with the alternateConfig block that replaces the default configuration.

Credentials go in a Kubernetes secret, named dynatrace-otelcol-dt-api-credentials in the examples, holding DT_ENDPOINT and DT_PLATFORM_TOKEN. The examples cap memory at 512 Mi, so adjust it to your load. Outside Kubernetes, the documentation also covers Docker, plain binaries and DEB and RPM packages.

Managed or SaaS: what I could not confirm

The examples I read use a platform token, which matches a SaaS environment. I did not verify the endpoint and token to use on Dynatrace Managed. For Managed, start from our step-by-step guide to the Collector and Dynatrace and check the ingest address on your own cluster. The exact token scopes are not in the pages I read either.

Best practices

• Version the list of components you use next to the configuration: it becomes a check at every upgrade.
• Plan one minor upgrade per quarter, since a minor version is supported for three months.
• Treat alpha components as unstable: the repository says they may change significantly.
• Keep a second, chained Collector for exotic sources rather than giving up the supported distribution.
• Never put the token in the file: use an environment variable or a secret.

Frequently asked questions

Is the Dynatrace OTel Collector compatible with a Contrib configuration?

For the format, yes: the documentation states that the configuration model stays standard. For components missing from the binary, no, and they block startup. Check the list before you switch.

Can you send data to Dynatrace with Contrib?

Yes, the protocol is OTLP either way. The difference is support: for Contrib, it is limited to the components and versions included in the Dynatrace distribution.

What if a component is missing?

Build a custom Collector with the OpenTelemetry Collector Builder, or chain two Collectors: the custom build for the exotic source, the Dynatrace distribution as the exit towards the platform.

Conclusion

The Dynatrace OTel Collector does not change how you write a configuration. It changes what the binary accepts and what the vendor agrees to support. List your components, compare them with the repository, then switch one Collector at a time. The payoff is a smaller surface and faster fixes.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. Brands mentioned belong to their owners. Tools change quickly: check versions, components and commands in the official documentation and the GitHub repository.

---

Originally published on span.observer. French version: https://span.observer/fr/dynatrace-otel-collector-migrer-contrib/.