OpenTelemetry Operator Kubernetes: Collector y autoinstrumentación paso a paso

OpenTelemetry Operator Kubernetes: instálalo con Helm, declara un Collector hacia Dynatrace e instrumenta Java o Python con una simple anotación.
OpenTelemetry Operator Kubernetes : Collector et auto-instrumentation pas à pas

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 corto otelcol): un Collector y su configuración, en modo deployment (por defecto), daemonset, statefulset o sidecar.
  • Instrumentation (opentelemetry.io/v1alpha1, nombre corto otelinst): la configuración del SDK inyectado (exportador, propagadores, muestreador, imagen por lenguaje).
  • TargetAllocator: reparte los destinos de scraping de Prometheus entre varios Collectors (modos statefulset y daemonset).
  • 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 apply con 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.ingest y logs.ingest, y la URL de OTLP: https://<env-id>.live.dynatrace.com/api/v2/otlp en SaaS, https://<tu-dominio>/e/<env-id>/api/v2/otlp en 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:

Extracto del README de autoinstrumentación del repositorio opentelemetry-operator: recurso Instrumentation v1alpha1 con exporter endpoint, propagadores tracecontext, baggage y b3, sampler parentbased_traceidratio a 0.25 e imagen de Python

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

  1. Los recursos existen y el Collector está en marcha:
    kubectl get otelcol -A
    kubectl get otelinst -n boutique
    kubectl -n observability get pods,svc
  2. 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_"
  3. El Collector exporta sin errores:
    kubectl -n observability logs deploy/gateway-collector | grep -iE "error|401|403"
  4. 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.

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

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
OpenTelemetry vs Prometheus (OTel vs Prometheus) : complémentaires ou concurrents ?

OpenTelemetry vs Prometheus (OTel vs Prometheus): ¿complementarios o rivales?

Next Post
Serveur MCP STDIO : contenir le risque d'exécution de commandes

Servidor MCP STDIO: cómo contener el riesgo de ejecución de comandos

Related Posts