</> LBE Tech
← Todos los artículos
OpenTelemetryCollectorObservabilidadOTLPPrometheusElasticsearch

OpenTelemetry Collector Contrib 0.162.0: guía de migración y pruebas

Revisa los cambios incompatibles de OpenTelemetry Collector Contrib 0.162.0 y prepara pruebas aisladas para Elasticsearch, Prometheus, Kafka, tail sampling y firmas.

1 de octubre de 2026 · · 11 min de lectura
Pipeline de OpenTelemetry Collector con etapas de ingestión, procesamiento y exportación señaladas para revisar una actualización

Actualizar un Collector suele parecer una operación de reemplazar una imagen y reiniciar un proceso. En v0.162.0 esa suposición es arriesgada: hay configuraciones que dejan de arrancar, cambios silenciosos en nombres de etiquetas y rutas de exportación que pueden aceptar la configuración pero perder datos.

La release de OpenTelemetry Collector Contrib se publicó el 29 de septiembre de 2026 con la etiqueta v1.1.0/v0.162.0. La distribución de releases publicó sus artefactos v0.162.0 el mismo día. El procedimiento oficial explica que Core y Contrib se liberan con la misma versión y que Contrib usa Core como dependencia; aun así, no son la misma distribución ni contienen los mismos componentes.

La decisión correcta depende de tu binario, del manifiesto de componentes y de las rutas que realmente usa tu configuración. Esta guía propone una migración reproducible para una rama o entorno aislado. No presupone que todos los cambios afecten a todos los Collectors.

Primero identifica qué estás actualizando

Un paquete otelcol, una imagen Contrib y una distribución construida con OpenTelemetry Collector Builder pueden tener nombres y componentes distintos. Antes de comparar versiones, registra:

  • nombre exacto de la imagen o binario y su arquitectura;
  • etiqueta y, si la plataforma lo permite, digest de la imagen;
  • versión anterior, v0.162.0 y hash del artefacto que se probará;
  • archivo de configuración, variables interpoladas y secretos referenciados sin copiar los secretos;
  • receivers, processors, connectors, exporters y extensions incluidos en el binario;
  • versión de Elasticsearch, Kafka y otros destinos que formen parte de la prueba.

La documentación de instalación de Docker muestra imágenes fijadas por versión para Core, por ejemplo otel/opentelemetry-collector:0.162.0. Para Contrib, usa el artefacto Contrib correspondiente, como ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.162.0, y comprueba que el nombre coincida con la distribución que ya utilizas. No cambies Contrib por Core solo porque ambas imágenes usen el mismo número.

Guarda la configuración efectiva en control de versiones, pero elimina tokens, contraseñas y endpoints con credenciales. La configuración declarada puede no ser la que finalmente consume el proceso si hay variables, proveedores de configuración o un generador de distribución.

Cambios que requieren revisión

La siguiente matriz convierte las notas de la release en decisiones y pruebas concretas.

Área Cambio en v0.162.0 Qué revisar Prueba de aceptación
Wavefront Se elimina el receiver wavefront después de su deprecación. Busca wavefront en configuración y en el manifiesto del binario. La ruta equivalente recibe y exporta señales sintéticas antes de retirar la configuración anterior.
Elasticsearch Se eliminan flush y num_workers del exporter. Migra concurrencia a sending_queue.num_consumers y batching a sending_queue.batch. El exporter arranca, mantiene el throughput esperado y no acumula errores ni elementos en cola.
Perfiles en Elasticsearch El modo otel escribe data streams nativos que requieren Elasticsearch 9.6.0 o posterior. Comprueba versión del clúster y mapping.mode/mapping.allowed_modes. Se crean los data streams esperados y se consulta la ausencia de index_not_found_exception.
Prometheus PermissiveLabelSanitization pasa a beta y queda habilitada por defecto. Revisa nombres que empiezan por un solo guion bajo, dashboards y alertas. Compara nombres de series, cardinalidad y reglas con ambas versiones.
Adaptive tail sampling Los selectores raíz exigen prefijos explícitos de origen. Sustituye root.attributes[...] según quieras atributos de span, recurso, scope o unión. Una traza sintética cae en la regla de muestreo prevista y conserva la decisión esperada.
Firmas Los escalares pasan a objetos tipados y las firmas existentes quedan invalidadas. Coordina el procesador firmante y el verificador; separa payloads nuevos de históricos. Un payload nuevo firma y verifica con el formato nuevo; la política para firmas antiguas queda documentada.
Kafka El valor predeterminado documentado de metadata.retry.max cambia de 3 a 20, pero el campo estaba sin cablear y el comportamiento efectivo ya era 20; solo cambian las configuraciones que lo fijaban explícitamente, cuyo valor pasa a respetarse. metadata.full se depreca y no tiene efecto. Busca valores explícitos de reintentos y elimina la falsa expectativa de full. Provoca una indisponibilidad controlada del broker y verifica reintentos, recuperación y duplicados.
Prometheus receiver otel_scope_info ya no sirve para extraer atributos de scope; el feature gate no se puede desactivar. Revisa consultas, dashboards y reglas que dependan de esa métrica. Compara etiquetas otel_scope_ y señales resultantes, no solo el estado del proceso.

Hay además cambios menores, aliases de nombres que pasan a estar deprecados y componentes nuevos en estado de skeleton o desarrollo, como el exporter NATS y telemetry_policy. No los trates como capacidades listas para producción por aparecer en el changelog.

Elasticsearch: migra la cola, no solo el nombre de la opción

El exporter retira flush y num_workers. La migración documentada es:

exporters:
  elasticsearch:
    endpoints: ["https://elasticsearch-prueba:9200"]
    sending_queue:
      num_consumers: 4       # equivalente operativo de num_workers
      batch:
        sizer: bytes
        flush_timeout: 5s    # equivalente de flush.interval
        max_size: 1048576     # equivalente de flush.bytes

Los valores son un ejemplo de prueba, no una recomendación universal. Ajusta num_consumers, flush_timeout y max_size a la memoria, el tamaño de evento y la capacidad del clúster. Revisa la documentación del exporter de Elasticsearch para las opciones de tu distribución.

El caso de perfiles tiene un riesgo distinto. En otel mapping mode, la release escribe data streams como profiling-events-all.otel-default, que requieren Elasticsearch 9.6.0 o posterior. Si el clúster es más antiguo, la propia release advierte de index_not_found_exception y pérdida de datos. Si no puedes actualizar Elasticsearch aún, restringe temporalmente el exporter a ECS:

exporters:
  elasticsearch:
    mapping:
      allowed_modes: [ecs]

Comprueba el modo concreto y la señal concreta: esta advertencia se refiere a perfiles en modo OTel, no significa que cualquier traza o métrica enviada a Elasticsearch vaya a fallar. En la prueba, inspecciona data streams, respuestas del exporter, cola persistente si existe y el destino final. No conectes la prueba a índices de producción.

Prometheus y tail sampling: los cambios silenciosos son los peligrosos

La sanitización permisiva de Prometheus deja de anteponer key_ a etiquetas cuyo nombre empieza por un solo guion bajo. Una aplicación puede seguir arrancando mientras cambian las series que consultan las alertas. Genera o captura una muestra con etiquetas como _team y compara el nombre final, la cardinalidad, las reglas y las consultas de dashboards. Si necesitas conservar temporalmente el comportamiento anterior, la release documenta este feature gate:

--feature-gates=-pkg.translator.prometheus.PermissiveLabelSanitization

Úsalo como compatibilidad acotada y con fecha de retirada; no lo conviertas en una decisión permanente sin entender por qué las etiquetas no cumplen tu convención.

En adaptive_tail_sampling, root. deja de ser un origen implícito. Una expresión como esta ya no es válida:

root.attributes["service.name"]

Elige explícitamente el origen:

root.span.attributes["service.name"]
root.resource.attributes["service.name"]
root.scope.attributes["library.name"]
root.any.attributes["service.name"]

La elección no es cosmética. root.span conserva la lectura de atributos del span raíz; root.resource y root.scope permiten consultar niveles que antes podían quedar fuera, y root.any trabaja con su unión. Valida cada regla con una traza sintética que tenga valores distintos en span, recurso y scope. Comprueba no solo que el Collector acepte el archivo, sino que la traza quede muestreada según el origen elegido.

Prepara una prueba aislada y repetible

1. Congela el escenario

Usa la misma configuración, carga sintética y destino de prueba con la versión anterior y con v0.162.0. La guía oficial de Docker muestra cómo fijar una imagen y montar config.yaml; para Contrib, conserva el path de configuración que espera esa imagen.

Registra la orden de arranque, la imagen completa, el digest, la versión del host, la zona horaria y las variables no secretas que cambian el comportamiento. Si generas telemetría con telemetrygen, fija también su versión: el README oficial describe el generador para trazas, métricas y logs.

Antes del primer arranque, valida la configuración con la orden equivalente que ofrezca tu binario (validate --config o la opción documentada por tu distribución). Haz esa validación con las dos versiones y conserva los errores. Una validación correcta solo indica que la configuración es aceptable para el proceso; no prueba la entrega de señales.

2. Haz búsquedas estáticas

En el repositorio de configuración, busca las claves y expresiones de riesgo:

wavefront
flush:
num_workers
root.attributes
PermissiveLabelSanitization
metadata:
  full:
metadata:
  retry:
otel_scope_info
signing
mapping:

Para cada coincidencia, anota el componente, la señal, el destino, el propietario y la prueba que la cubre. No supongas que una clave ausente en un archivo significa que no existe: revisa plantillas, valores Helm, overlays y configuración generada.

3. Divide la prueba por señales y destinos

Empieza con una ruta mínima OTLP hacia un exporter de depuración o un destino local. Después añade, de forma controlada, los componentes que puedan cambiar:

  • Trazas: una traza con span raíz, recurso y scope diferentes; valida tail sampling y atributos.
  • Métricas Prometheus: una muestra con etiquetas normales y con un solo guion bajo; compara nombres de series y cardinalidad.
  • Logs: valida que un error de un connector signal_to_metrics no descarte un payload OTLP válido: en v0.162.0 el modo de error predeterminado pasa de propagate a ignore.
  • Kafka: detén temporalmente el broker de prueba, mide reintentos y recuperación y confirma si el consumidor puede recibir duplicados. El valor predeterminado documentado de metadata.retry.max cambia de 3 a 20, pero el campo estaba sin cablear y el comportamiento efectivo ya era 20; solo cambian las configuraciones que lo fijaban explícitamente, cuyo valor ahora se respeta. metadata.full se conserva por compatibilidad, pero está deprecado y no cambia el comportamiento.
  • Elasticsearch: prueba trazas y métricas por separado de perfiles; verifica mappings, data streams, respuestas y cola.
  • Firmas: usa un payload sintético sin secretos, firma con el formato nuevo y verifica con el componente correspondiente. Decide si los payloads firmados antes de la actualización se rechazan, se verifican con una ruta anterior o se vuelven a emitir según tu política.

Un Collector que arranca y expone su health check no demuestra que los datos hayan llegado al backend. La prueba debe observar entrada, procesadores, cola, reintentos, exporter y destino final.

Criterios para continuar o pausar

Define antes del rollout qué evidencia permite continuar:

  • la configuración pasa la validación y todos los componentes necesarios existen en la distribución elegida;
  • no quedan referencias a receivers u opciones eliminadas sin una sustitución aprobada;
  • la ingestión conserva conteo y atributos esperados en trazas, métricas y logs;
  • las series y dashboards críticos conservan nombres o tienen una migración explícita;
  • Elasticsearch no devuelve errores de índice y los perfiles llegan al data stream compatible;
  • Kafka recupera la indisponibilidad de prueba con el número de reintentos esperado;
  • el firmante y el verificador acuerdan el payload tipado, y la política de firmas históricas está aplicada;
  • el rollback restaura la imagen y configuración anterior sin mezclar colas o data streams de la prueba.

Pausa si una distribución no contiene un componente requerido, si Elasticsearch es incompatible con perfiles en modo OTel, si las alertas cambian sin explicación, si se pierden señales o si no puedes demostrar cómo volver atrás. En ese caso, fija la versión que ya conoces y abre una tarea de migración para la dependencia concreta. No conviertas un reinicio exitoso en criterio de aprobación.

Rollback y despliegue gradual

Conserva la imagen anterior, el digest, el archivo de configuración y el procedimiento de arranque antes de cambiar el primer nodo. En un despliegue con varios Collectors, actualiza una instancia canaria con tráfico sintético o una fracción explícita, observa las métricas internas y los backends y define por adelantado el umbral que detiene la siguiente instancia.

El rollback debe cambiar de forma coordinada el binario y la configuración. Por ejemplo, volver a una imagen anterior mientras se conserva root.span... puede dejar un archivo incompatible; volver a un exporter antiguo con la nueva configuración de sending_queue puede tener el mismo problema. Guarda dos paquetes completos de configuración y asocia cada uno a su imagen.

La release no exige que todos los equipos actualicen el mismo día. Si una dependencia externa o un dashboard necesita más tiempo, fijar temporalmente la versión anterior con una fecha de revisión es una decisión más segura que desplegar v0.162.0 sin evidencia. La guía de procedimiento de releases del Collector recuerda que el proyecto usa ciclos cortos; revisa las releases y changelogs de la siguiente actualización antes de convertir un workaround en deuda permanente.

Conclusión

v0.162.0 trae cambios concretos que afectan a configuración, nombres de series, compatibilidad de Elasticsearch y verificación de integridad. La migración segura empieza por separar Core, Contrib y distribuciones propias; continúa con búsquedas estáticas y pruebas sintéticas por señal; y termina solo cuando ingestión, exportación, dashboards y rollback tienen evidencia reproducible.

El objetivo no es probar que una imagen nueva «funciona», sino demostrar que las rutas que importan para tu observabilidad siguen entregando los datos correctos. Si una ruta no tiene una prueba o una dependencia no cumple la matriz, aplaza esa ruta y documenta la decisión.

Fuentes primarias

También puede interesarte

Comentarios

Cargando…