Instrumentar veinte microservicios a mano significa veinte Dockerfiles que modificar, veinte agentes que actualizar y otras tantas configuraciones de exportación que divergen. El OpenTelemetry Operator Kubernetes invierte la lógica: declaras una sola vez el Collector y la instrumentación como recursos de Kubernetes, y el Operator los aplica a los pods con una simple anotación.
Objetivo de este tutorial: instalar el Operator, desplegar un Collector pasarela que exporte a Dynatrace, activar la autoinstrumentación de Java y Python mediante anotación y comprobar que llegan las trazas. El contenido vale para Dynatrace SaaS y Dynatrace Managed: solo cambia la URL de OTLP.
No confundas este Operator con Dynatrace Operator, que gestiona OneAgent y ActiveGate (consulta Dynatrace Operator en Kubernetes). Ambos pueden convivir, siempre que no instrumentes dos veces los mismos pods.
Qué gestiona el OpenTelemetry Operator
El Operator es una implementación del patrón Operator de Kubernetes. Gestiona dos cosas: instancias del OpenTelemetry Collector y la autoinstrumentación de los workloads con las bibliotecas de OpenTelemetry. Se apoya en cuatro recursos personalizados:
OpenTelemetryCollector(opentelemetry.io/v1beta1, nombre cortootelcol): un Collector y su configuración, en mododeployment(por defecto),daemonset,statefulsetosidecar.Instrumentation(opentelemetry.io/v1alpha1, nombre cortootelinst): la configuración del SDK inyectado (exportador, propagadores, muestreador, imagen por lenguaje).TargetAllocator: reparte los destinos de scraping de Prometheus entre varios Collectors (modosstatefulsetydaemonset).OpAMPBridge: conecta los Collectors con un servidor OpAMP.
La autoinstrumentación cubre Apache HTTPD, .NET, Go, Java, Nginx, Node.js y Python. Go y Nginx están desactivados por defecto en el Operator (--enable-go-instrumentation, --enable-nginx-instrumentation).
Requisitos previos
- Un clúster de Kubernetes 1.24 o más reciente (requisito del chart de Helm) y
kubectl. - Helm 4.0 o superior para la versión actual del chart, o
kubectl applycon el manifiesto de la release. - Un certificado para los webhooks de admisión: cert-manager (método por defecto) o un certificado autofirmado generado por el chart.
- Un token de Dynatrace con
openTelemetryTrace.ingest,metrics.ingestylogs.ingest, y la URL de OTLP:https://<env-id>.live.dynatrace.com/api/v2/otlpen SaaS,https://<tu-dominio>/e/<env-id>/api/v2/otlpen Managed.
Instalar el OpenTelemetry Operator Kubernetes
Paso 1: desplegar el Operator con 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
Las dos últimas opciones piden a Helm que genere un certificado autofirmado: práctico sin cert-manager. Si cert-manager está instalado, quítalas. Sin Helm, el comando oficial es kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml, con cert-manager obligatorio. Las CRD no se eliminan al desinstalar el chart: tenlo en cuenta al hacer limpieza.
Paso 2: crear el Collector pasarela
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]
Qué hace el Operator: crea el Deployment y, como detecta receptores con puertos en config, una pareja de Services (uno de ellos headless) que exponen el 4317 y el 4318. El Service principal se llama gateway-collector. Atención: el Operator no valida toda la configuración; una configuración inválida puede aceptarse y hacer que el Collector falle al arrancar. otlp_http es el nombre reciente del exportador otlphttp, que se sigue aceptando como alias. La imagen opentelemetry-collector-k8s fijada en el paso 1 incluye cumulative_to_delta (figura en el manifiesto de la distribución de Kubernetes); para otro componente, comprueba ese manifiesto o cambia de imagen con spec.image.
Para un Collector por nodo con enriquecimiento k8sattributes, la variante DaemonSet se detalla en el OpenTelemetry Collector en Kubernetes.
Activar la autoinstrumentación mediante anotación
Paso 3: declarar el recurso Instrumentation
La documentación del repositorio del Operator (licencia Apache 2.0) muestra la forma general del recurso:

Adaptado a nuestra pasarela:
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
Las líneas críticas: propagators alimenta OTEL_PROPAGATORS (tracecontext de W3C para seguir una petición entre servicios); sampler alimenta OTEL_TRACES_SAMPLER y su argumento. La autoinstrumentación de Python (como .NET y Go) exporta en http/protobuf por defecto: debe apuntar al puerto 4318, de ahí la sobrescritura del endpoint.
Paso 4: anotar los workloads
spec:
template:
metadata:
annotations:
instrumentation.opentelemetry.io/inject-java: "true"
El valor "true" toma la Instrumentation del namespace; también puedes dar un nombre ("dynatrace") o "otro-namespace/dynatrace", y "false" excluye de forma explícita. La anotación puede ponerse en el namespace para cubrir todos sus pods. Los demás lenguajes siguen el mismo modelo: inject-python, inject-nodejs, inject-dotnet, inject-go (con otel-go-auto-target-exe y privilegios elevados), inject-apache-httpd, inject-nginx. Para un pod con varios contenedores, instrumentation.opentelemetry.io/container-names indica los contenedores objetivo.
La inyección se produce al crear el pod: relanza el despliegue con kubectl -n boutique rollout restart deployment/panier.
Cómo comprobar que funciona
- Los recursos existen y el Collector está en marcha:
kubectl get otelcol -A kubectl get otelinst -n boutique kubectl -n observability get pods,svc - El pod de la aplicación ha recibido el init container y la variable del agente:
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_" - El Collector exporta sin errores:
kubectl -n observability logs deploy/gateway-collector | grep -iE "error|401|403" - En SaaS, en un Notebook:
fetch spans, from: now() - 15m | filter k8s.namespace.name == "boutique" | summarize spans = count(), by: {service.name}El Operator añade atributos de recurso de Kubernetes según las convenciones semánticas; si el filtro no devuelve nada, filtra por
service.name. - En Managed, abre la vista de trazas distribuidas y busca el servicio
panier.
¿No llega nada? Sigue el diagnóstico de las trazas de OpenTelemetry ausentes.
Convivir con Dynatrace Operator
Si Dynatrace Operator ya inyecta OneAgent en un namespace, no añadas allí la autoinstrumentación de OpenTelemetry: obtendrías spans duplicados (consulta OneAgent y OpenTelemetry: evitar duplicados). Separa los ámbitos: namespaceSelector en la DynaKube, anotaciones inject-* en OpenTelemetry. Ten en cuenta también que Dynatrace Operator sabe configurar automáticamente los exportadores OTLP de los pods (.spec.otlpExporterConfiguration), una alternativa si quieres mantener la instrumentación en la imagen.
Buenas prácticas
- Fija las versiones del Operator, del chart y de las imágenes de instrumentación; una subida de versión cambia los agentes de todos los pods en el siguiente reinicio.
- Una Instrumentation por namespace, versionada en Git junto con los manifiestos de la aplicación.
- Muestreo en el lugar adecuado: 100 % en origen y decisión fina en la pasarela (consulta el tail sampling de OpenTelemetry).
- Límites de recursos en el Collector, alineados con
memory_limiter. - Despliegue progresivo: un namespace piloto, comparación de la latencia antes y después, y después generalización.
Preguntas frecuentes
¿Hace falta cert-manager?
No con Helm: admissionWebhooks.autoGenerateCert.enabled=true genera un certificado autofirmado. El manifiesto kubectl apply de la release, en cambio, presupone cert-manager.
¿Por qué mi pod no está instrumentado?
Lo más habitual es que se creara antes de la anotación o que la Instrumentation no exista en el namespace. Comprueba también que el lenguaje esté activado en el Operator (Go y Nginx están desactivados por defecto).
¿Sidecar o pasarela?
El modo sidecar se inyecta con la anotación sidecar.opentelemetry.io/inject y aísla cada aplicación. La pasarela compartida consume menos y se gestiona en un único punto; empieza por ella.
Conclusión
El OpenTelemetry Operator Kubernetes convierte la instrumentación en configuración declarativa: un recurso Collector, un recurso Instrumentation y una anotación por workload. Ganas trazas homogéneas sin tocar las imágenes, y el toil de actualizar agentes desaparece. Empieza por un namespace, valida los spans en Dynatrace y amplía después.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Las CRD, las opciones del chart y las versiones de las imágenes evolucionan: compruébalas en la documentación del OpenTelemetry Operator y en la de Dynatrace. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión.