Instrumenter vingt microservices à la main, c’est vingt Dockerfiles à modifier, vingt agents à mettre à jour et autant de configurations d’export qui divergent. L’OpenTelemetry Operator Kubernetes inverse la logique : vous déclarez une fois le Collector et l’instrumentation sous forme de ressources Kubernetes, et l’Operator les applique aux pods par simple annotation.
Objectif de ce tutoriel : installer l’Operator, déployer un Collector passerelle qui exporte vers Dynatrace, activer l’auto-instrumentation Java et Python par annotation, puis vérifier que les traces arrivent. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed : seule l’URL OTLP change.
Ne confondez pas cet Operator avec Dynatrace Operator, qui gère OneAgent et ActiveGate (voir Dynatrace Operator sur Kubernetes). Les deux peuvent cohabiter, à condition de ne pas instrumenter deux fois les mêmes pods.
Ce que gère l’OpenTelemetry Operator
L’Operator est une implémentation du modèle Operator de Kubernetes. Il gère deux choses : des instances de l’OpenTelemetry Collector et l’auto-instrumentation des workloads avec les bibliothèques OpenTelemetry. Il s’appuie sur quatre ressources personnalisées :
OpenTelemetryCollector(opentelemetry.io/v1beta1, nom courtotelcol) : un Collector et sa configuration, en modedeployment(par défaut),daemonset,statefulsetousidecar.Instrumentation(opentelemetry.io/v1alpha1, nom courtotelinst) : la configuration du SDK injecté (exporteur, propagateurs, échantillonneur, image par langage).TargetAllocator: répartit les cibles de scraping Prometheus entre plusieurs Collectors (modesstatefulsetetdaemonset).OpAMPBridge: relie les Collectors à un serveur OpAMP.
L’auto-instrumentation couvre Apache HTTPD, .NET, Go, Java, Nginx, Node.js et Python. Go et Nginx sont désactivés par défaut côté Operator (--enable-go-instrumentation, --enable-nginx-instrumentation).
Prérequis
- Un cluster Kubernetes 1.24 ou plus récent (prérequis du chart Helm) et
kubectl. - Helm 4.0 ou plus pour la version actuelle du chart, ou
kubectl applyavec le manifeste de release. - Un certificat pour les webhooks d’admission : cert-manager (méthode par défaut) ou un certificat autosigné généré par le chart.
- Un token Dynatrace avec
openTelemetryTrace.ingest,metrics.ingestetlogs.ingest, et l’URL OTLP :https://<env-id>.live.dynatrace.com/api/v2/otlpen SaaS,https://<votre-domaine>/e/<env-id>/api/v2/otlpen Managed.
Installer l’OpenTelemetry Operator Kubernetes
Étape 1 : déployer l’Operator avec Helm
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
helm install opentelemetry-operator open-telemetry/opentelemetry-operator \
--namespace opentelemetry-operator-system --create-namespace \
--set "manager.collectorImage.repository=ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-k8s" \
--set admissionWebhooks.certManager.enabled=false \
--set admissionWebhooks.autoGenerateCert.enabled=true
Les deux dernières options demandent à Helm de générer un certificat autosigné : pratique sans cert-manager. Si cert-manager est installé, retirez-les. Sans Helm, la commande officielle est kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml, avec cert-manager obligatoire. Les CRD ne sont pas supprimées à la désinstallation du chart : pensez-y lors d’un nettoyage.
Étape 2 : créer le Collector passerelle
kubectl create namespace observability
kubectl -n observability create secret generic dynatrace-otlp \
--from-literal=DT_ENDPOINT='https://<env-id>.live.dynatrace.com/api/v2/otlp' \
--from-literal=DT_API_TOKEN='<token>'
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
name: gateway
namespace: observability
spec:
mode: deployment
replicas: 2
envFrom:
- secretRef:
name: dynatrace-otlp
config:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
memory_limiter:
check_interval: 1s
limit_percentage: 75
spike_limit_percentage: 15
cumulative_to_delta: {}
exporters:
otlp_http:
endpoint: ${env:DT_ENDPOINT}
headers:
Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter]
exporters: [otlp_http]
metrics:
receivers: [otlp]
processors: [memory_limiter, cumulative_to_delta]
exporters: [otlp_http]
logs:
receivers: [otlp]
processors: [memory_limiter]
exporters: [otlp_http]
Ce que fait l’Operator : il crée le Deployment et, parce qu’il repère des récepteurs avec ports dans config, une paire de Services (dont un headless) qui exposent 4317 et 4318. Le Service principal s’appelle gateway-collector. Attention : l’Operator ne valide pas toute la configuration ; une configuration invalide peut être acceptée, puis faire planter le Collector au démarrage. otlp_http est le nom récent de l’exporteur otlphttp, toujours accepté comme alias. L’image opentelemetry-collector-k8s fixée à l’étape 1 inclut cumulative_to_delta (il figure dans le manifeste de la distribution Kubernetes) ; pour un autre composant, vérifiez ce manifeste ou changez d’image via spec.image.
Pour un Collector par nœud avec enrichissement k8sattributes, la variante DaemonSet est détaillée dans le Collector OpenTelemetry sur Kubernetes.
Activer l’auto-instrumentation par annotation
Étape 3 : déclarer la ressource Instrumentation
La documentation du dépôt de l’Operator (licence Apache 2.0) montre la forme générale de la ressource :

Adaptée à notre passerelle :
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: dynatrace
namespace: boutique
spec:
exporter:
endpoint: http://gateway-collector.observability:4317
propagators:
- tracecontext
- baggage
sampler:
type: parentbased_traceidratio
argument: "1"
python:
env:
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: http://gateway-collector.observability:4318
Les lignes critiques : propagators alimente OTEL_PROPAGATORS (W3C tracecontext pour suivre une requête entre services) ; sampler alimente OTEL_TRACES_SAMPLER et son argument. L’auto-instrumentation Python (comme .NET et Go) exporte en http/protobuf par défaut : elle doit viser le port 4318, d’où la surcharge de l’endpoint.
Étape 4 : annoter les workloads
spec:
template:
metadata:
annotations:
instrumentation.opentelemetry.io/inject-java: "true"
La valeur "true" prend l’Instrumentation du namespace ; vous pouvez aussi donner un nom ("dynatrace") ou "autre-namespace/dynatrace", et "false" exclut explicitement. L’annotation peut être posée sur le namespace pour couvrir tous ses pods. Les autres langages suivent le même modèle : inject-python, inject-nodejs, inject-dotnet, inject-go (avec otel-go-auto-target-exe et des privilèges élevés), inject-apache-httpd, inject-nginx. Pour un pod à plusieurs conteneurs, instrumentation.opentelemetry.io/container-names désigne les conteneurs ciblés.
L’injection a lieu à la création du pod : relancez le déploiement avec kubectl -n boutique rollout restart deployment/panier.
Comment vérifier que ça fonctionne
- Les ressources existent et le Collector tourne :
kubectl get otelcol -A kubectl get otelinst -n boutique kubectl -n observability get pods,svc - Le pod applicatif a reçu l’init container et la variable de l’agent :
kubectl -n boutique get pod -l app=panier \ -o jsonpath='{.items[0].spec.initContainers[*].name}' # attendu : opentelemetry-auto-instrumentation-java kubectl -n boutique exec deploy/panier -- env | grep -E "JAVA_TOOL_OPTIONS|OTEL_" - Le Collector exporte sans erreur :
kubectl -n observability logs deploy/gateway-collector | grep -iE "error|401|403" - En SaaS, dans un Notebook :
fetch spans, from: now() - 15m | filter k8s.namespace.name == "boutique" | summarize spans = count(), by: {service.name}L’Operator ajoute des attributs de ressource Kubernetes selon les conventions sémantiques ; si le filtre ne renvoie rien, filtrez sur
service.name. - En Managed, ouvrez la vue des traces distribuées et cherchez le service
panier.
Rien n’arrive ? Suivez le diagnostic des traces OpenTelemetry absentes.
Cohabiter avec Dynatrace Operator
Si Dynatrace Operator injecte déjà OneAgent dans un namespace, n’y ajoutez pas l’auto-instrumentation OpenTelemetry : vous obtiendriez des spans en double (voir OneAgent et OpenTelemetry : éviter les doublons). Séparez les périmètres : namespaceSelector côté DynaKube, annotations inject-* côté OpenTelemetry. Notez aussi que Dynatrace Operator sait configurer automatiquement les exporteurs OTLP des pods (.spec.otlpExporterConfiguration), une alternative si vous voulez garder l’instrumentation dans l’image.
Bonnes pratiques
- Épinglez les versions de l’Operator, du chart et des images d’instrumentation ; une montée de version change les agents de tous les pods au prochain redémarrage.
- Une Instrumentation par namespace, versionnée en Git avec les manifestes applicatifs.
- Échantillonnage au bon endroit : 100 % en tête, et décision fine dans la passerelle (voir le tail sampling OpenTelemetry).
- Limites de ressources sur le Collector, alignées avec
memory_limiter. - Déploiement progressif : un namespace pilote, comparaison de la latence avant/après, puis généralisation.
Questions fréquentes
Faut-il cert-manager ?
Non avec Helm : admissionWebhooks.autoGenerateCert.enabled=true génère un certificat autosigné. Le manifeste kubectl apply de la release, lui, suppose cert-manager.
Pourquoi mon pod n’est-il pas instrumenté ?
Le plus souvent, il a été créé avant l’annotation ou l’Instrumentation n’existe pas dans le namespace. Vérifiez aussi que le langage est activé côté Operator (Go et Nginx sont désactivés par défaut).
Sidecar ou passerelle ?
Le mode sidecar s’injecte avec l’annotation sidecar.opentelemetry.io/inject et isole chaque application. La passerelle partagée consomme moins et se gère en un seul point ; commencez par elle.
Conclusion
L’OpenTelemetry Operator Kubernetes transforme l’instrumentation en configuration déclarative : une ressource Collector, une ressource Instrumentation, une annotation par workload. Vous gagnez des traces homogènes sans toucher aux images, et le toil de mise à jour des agents disparaît. Commencez par un namespace, validez les spans dans Dynatrace, puis étendez.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les CRD, options du chart et versions d’images évoluent : vérifiez-les dans la documentation de l’OpenTelemetry Operator et dans celle de Dynatrace.