OTTL llega a la v1: la sintaxis de tus reglas del OTel Collector queda congelada en 1.x

Las reglas que escribes en el transform processor para borrar una cabecera o reetiquetar un span ya tienen contrato: desde opentelemetry-collector-contrib v0.164.0, publicada el 26 de octubre de 2026, el OpenTelemetry Transformation Language (OTTL) es estable para trazas, métricas y logs. Una sentencia que hoy parsea seguirá parseando y comportándose igual en cualquier 1.x.

Hasta ahora OTTL era beta, aunque ya lo usan 14 componentes del Collector: los procesadores transform, filter, tail sampling o log deduplication, los conectores routing, count y signal to metrics, y un par de exportadores. Es decir, buena parte del filtrado y el enriquecimiento de cualquier pipeline de telemetría serio. Con la v1 deja de ser una apuesta.

01Qué garantiza OTTL 1.x

La sintaxis queda congelada: rutas (span.attributes[...]), literales, operadores, llamadas a funciones y cláusulas where, tal y como las describe la referencia del lenguaje. Las versiones menores pueden añadir sintaxis, pero no quitar ni cambiar el significado de la existente. Lo mismo con la biblioteca estándar de funciones: no se eliminan ni cambian de firma de forma incompatible. Y la API de Go, para quien mantiene componentes propios sobre OTTL, también pasa a ser compatible hacia atrás.

Para un equipo de plataforma esto cambia cómo se gestionan las actualizaciones del Collector. Hasta ahora, subir de versión obligaba a revisar el changelog de pkg/ottl por si una función se renombraba o una ruta cambiaba de contexto. A partir de aquí, las reglas de transformación se pueden tratar como configuración estable y versionada, igual que el resto del pipeline.

02Lo que se queda fuera del contrato

No todo entra en la v1, y es justo lo que más tienta a usar:

• Las funciones con lambdas (Filter, MapEach, MapKeys, Any, All, Find, Reduce, When) siguen siendo experimentales y necesitan el feature gate ottl.functions.enableLambda.
• El soporte de profiles vive en el módulo xprofile, todavía en 0.x.
• Las funciones nuevas nacen en xottl, pueden cambiar o desaparecer en cualquier versión y se activan con --feature-gates=pkg.ottl.functions.enableExperimental, sin compilar un Collector a medida.

Para pasar al conjunto estándar, una función experimental necesita al menos dos versiones menores en ese estado, tests y documentación completos, ninguna propuesta de cambio abierta y demanda real de usuarios. Al promocionarla, su firma se congela. Mi recomendación: si una regla crítica (por ejemplo, la que elimina datos personales de los logs) depende de una función experimental o de una lambda, reescríbela con funciones estándar antes de dar el pipeline por estable.

03Qué se rompe al actualizar a v0.164.0

La estabilización se ha aprovechado para limpiar. El proyecto ha retirado funciones deprecadas desde hace tiempo, como Base64Decode y las antiguas funciones de profiles, y feature gates que ya eran estables (ottl.PanicDuplicateName y ottl.contexts.enableOTelColContext). La propia v0.164.0 elimina además:

• El gate ottl.set.allowNil de pkg/ottl.
• El gate processor.filter.defaultErrorModeIgnore del filter processor.

Si alguno de esos gates sigue en tus flags de arranque, quítalo antes de actualizar. En el transform processor, la opción flatten_data pasa a estar deprecada en favor de flatten.log y se eliminará en una versión futura: buen momento para cambiarla.

04Cómo actualizar el Collector

La imagen de la distribución contrib, que es la que trae los procesadores con OTTL, está en Docker Hub con la etiqueta de la versión:

docker pull otel/opentelemetry-collector-contrib:0.164.0

Antes de desplegar, valida la configuración con el subcomando validate del binario de tu distribución:

otelcol validate --config=customconfig.yaml

Una regla típica, como la del ejemplo de la documentación que marca como correctas las respuestas 400, sigue igual en la v1:

transform:
  error_mode: ignore
  trace_statements:
    - set(span.status.code, STATUS_CODE_OK) where span.attributes["http.request.status_code"] == 400

Checklist antes de llevarlo a producción:

1. Busca en la configuración y en los argumentos del contenedor los cuatro gates retirados y elimínalos.
2. Si vienes de varias versiones atrás, revisa las entradas de pkg/ottl del changelog de contrib entre tu versión y la v0.164.0, y busca Base64Decode en tus reglas.
3. Inventaria qué sentencias usan lambdas o funciones de xottl: esas no tienen garantía.
4. Pasa validate en CI con la nueva imagen y compara en un entorno de staging el volumen de spans y logs a la salida del filter processor: un cambio en el modo de error se nota ahí antes que en ningún otro sitio.

05Lo siguiente: el transform processor

La estabilidad del lenguaje no implica la de todos los componentes que lo usan. El transform processor está en proceso de promoción a estable, con las revisiones de tests, documentación, configuración y observabilidad ya completadas. Las lambdas y su API de Go se están evaluando para entrar en la garantía v1, y xprofile podría unirse cuando se estabilicen los profiles.

06Fuentes

• OpenTelemetry Transformation Language reaches v1 (OpenTelemetry blog)
• opentelemetry-collector-contrib v0.164.0 (GitHub)
• Transforming telemetry (documentación de OpenTelemetry)
• Collector configuration (documentación de OpenTelemetry)