Convenciones semánticas de OpenTelemetry: estabilidad e impacto en tus atributos

Convenciones semánticas de OpenTelemetry: niveles de estabilidad, renombrados HTTP y migración con OTEL_SEMCONV_STABILITY_OPT_IN sin romper tus alertas.
Conventions sémantiques OpenTelemetry : stabilité et impact sur vos attributs

Las convenciones semánticas de OpenTelemetry fijan los nombres y las unidades de los atributos, los spans y las métricas: http.request.method, server.address, http.server.request.duration. Cada nombre tiene un nivel de estabilidad, y es ese nivel el que decide si tus dashboards y tus alertas sobrevivirán a la próxima actualización de un SDK.

Este artículo explica los niveles (development, stable, deprecated), lo que la especificación promete y prohíbe, y cómo migrar sin romper tus consultas con la variable OTEL_SEMCONV_STABILITY_OPT_IN. Vale para cualquier back-end OpenTelemetry, Dynatrace SaaS y Dynatrace Managed incluidos: la migración se hace en la instrumentación y en el Collector, antes de que lleguen los datos.

En breve

  • Un atributo o una métrica empieza en development: su nombre todavía puede cambiar.
  • Una vez stable, un cambio de nombre debe pasar por un periodo en el que conviven el nombre antiguo y el nuevo.
  • Las convenciones HTTP son estables: los nombres antiguos (http.method, http.status_code) han sido sustituidos.
  • El cambio se controla con OTEL_SEMCONV_STABILITY_OPT_IN: http/dup emite los dos conjuntos, http solo los nuevos.

Convenciones semánticas de OpenTelemetry: qué cubre la estabilidad

Según la página Versioning and stability de la especificación, la estabilidad de las convenciones semánticas afecta a las claves de atributos, a los nombres y tipos de spans, a los nombres, tipos y unidades de métricas y a las claves de atributos de logs. Los valores de los atributos en general no están cubiertos, salvo las listas de valores conocidos, en las que se pueden añadir valores nuevos.

Para un equipo SRE, la consecuencia es concreta. Una alerta sobre http.server.duration o un filtro sobre http.status_code se apoya exactamente en esos nombres. Si la instrumentación cambia de nombre, la serie o el campo desaparece de tus consultas sin ningún error visible: el gráfico simplemente queda vacío.

Los niveles de estabilidad, uno por uno

La página Semantic convention groups enumera los niveles de un grupo: development, alpha, beta, release_candidate y stable. Un grupo está en development por defecto. Un grupo estable ya no puede cambiar de nivel.

Development

Según la especificación, pueden producirse cambios incompatibles y no conviene crear dependencias a largo plazo. Este nivel se llamaba antes «Experimental». Si construyes un dashboard sobre un atributo en development, cuenta con tener que reescribirlo.

Stable

Una señal estable permite una dependencia a largo plazo. La especificación limita los cambios autorizados: añadir atributos a una convención existente siempre está permitido, y los renombrados solo se admiten si pueden describirse mediante un archivo de esquema. Añade que existe una moratoria sobre el uso de transformaciones de esquema para la estabilidad de la telemetría. Otra garantía: los atributos de recurso service.* no deben cambiar nunca.

Deprecated

Una señal solo puede declararse obsoleta si su sustituta es estable. Los grupos no se eliminan nunca: el nombre antiguo sigue documentado, lo que ayuda a leer código de instrumentación antiguo.

Estable e inestable en un mismo grupo

Un grupo estable puede añadir atributos inestables, siempre que sean opt_in, pero no puede retirar atributos estables. Del mismo modo, una instrumentación estable no debe emitir telemetría inestable por defecto, aunque pueda ofrecerla como opción.

El ejemplo HTTP: qué nombres han cambiado

La guía de migración HTTP de la especificación enumera los renombrados. La página HTTP spans indica que las convenciones de spans HTTP de cliente y de servidor están marcadas como Stable, mientras que las recomendaciones sobre el estado del span siguen en Development.

Tabla de renombrados de atributos HTTP: http.method pasa a http.request.method, http.url a url.full, net.peer.name a server.address, entre otros

Las métricas también cambian: según la misma guía, http.server.duration pasa a ser http.server.request.duration, y la unidad pasa del milisegundo al segundo. Un umbral de alerta escrito en milisegundos queda por tanto equivocado por un factor de 1000 si no lo corriges. Los nombres de los spans también evolucionan: un span de servidor con ruta pasa de {http.route} a {summary} {http.route}.

Migrar sin romper: OTEL_SEMCONV_STABILITY_OPT_IN

La especificación prevé una variable de entorno para pasar de una convención experimental a su primera versión estable. Se describen tres comportamientos:

  • http: emite las convenciones estables y deja de emitir las antiguas;
  • http/dup: emite los dos conjuntos, para un despliegue progresivo;
  • variable ausente: la instrumentación sigue emitiendo las convenciones antiguas.
Variable OTEL_SEMCONV_STABILITY_OPT_IN con los valores http/dup y http, y renombrado de la métrica http.server.duration a http.server.request.duration

Precisión importante: la página HTTP spans indica que http/dup prevalece sobre http si ambos están presentes. Los autores de instrumentación también deben mantener la versión mayor anterior, como mínimo con correcciones de seguridad, durante al menos seis meses después de empezar a emitir los dos conjuntos. Esta variable solo afecta a las instrumentaciones que ya emitían convenciones HTTP experimentales: una instrumentación reciente no la necesita.

Plan de migración en cinco pasos

  1. Inventario. Enumera los atributos y las métricas que usan tus dashboards, alertas, SLO y reglas de enrutamiento. Busca los nombres antiguos: http.method, http.status_code, http.url, net.peer.name.
  2. Doble emisión. Define OTEL_SEMCONV_STABILITY_OPT_IN=http/dup en un servicio piloto. Llegan los dos conjuntos de atributos y nada se rompe.
  3. Reescritura de las consultas. Pasa tus dashboards y alertas a los nombres nuevos, corrigiendo la unidad de las duraciones (segundos).
  4. Cambio. Sustituye http/dup por http cuando ya ninguna consulta use los nombres antiguos.
  5. Vigilancia. Comprueba que el tráfico por servicio y las tasas de error no hayan caído después del cambio.

Para los servicios que no puedes migrar de inmediato, el Collector puede renombrar al vuelo. El procesador transform del repositorio opentelemetry-collector-contrib ejecuta instrucciones OTTL; el ejemplo siguiente copia y luego elimina un atributo. La sintaxis de las rutas (span.attributes) corresponde a la documentación actual del procesador: adáptala a la versión de tu Collector.

Extracto de configuración del Collector: procesador transform que copia http.method a http.request.method y luego elimina http.method
processors:
  transform/semconv:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - set(span.attributes["http.request.method"], span.attributes["http.method"]) where span.attributes["http.method"] != nil
          - delete_key(span.attributes, "http.method")

Este parche arregla el nombre, no la unidad ni el nombre de las métricas: sigue siendo un puente temporal. Para la configuración general de los atributos de recurso, consulta el artículo sobre los atributos de OpenTelemetry en Dynatrace.

Qué cambia para tu plataforma

Incluye la migración en el mismo proyecto que la elección de versión de los SDK: una subida de versión puede cambiar los nombres si la variable no está fijada. En una cadena con Collector, la configuración del Collector en Kubernetes es el lugar natural para centralizar las transformaciones y evitar repetirlas por servicio. Si haces muestreo, comprueba que tus reglas de tail sampling no filtren por un nombre de atributo antiguo. Para la base conceptual, consulta OpenTelemetry y Prometheus.

Por el lado de Dynatrace, aquí no se afirma nada automático: comprueba en la documentación de tu plataforma (Managed o SaaS) qué atributos usan tus vistas y reglas, y prueba con la doble emisión antes de cualquier cambio.

Buenas prácticas

  • Fija explícitamente la variable de estabilidad en tus manifiestos, en lugar de depender del valor por defecto de un SDK.
  • Trata todo atributo en development como provisional: aíslalo en una sola capa de consultas.
  • Mantén una lista versionada de los nombres de atributos que usan tus alertas.
  • Prueba los umbrales de duración después de cada cambio de unidad.

Preguntas frecuentes

¿Qué significa «stable» para una convención semántica?

Es posible una dependencia a largo plazo. La especificación solo autoriza ya la adición de atributos y los renombrados descritos por un esquema, y los grupos estables no vuelven a cambiar de nivel.

¿Hay que activar OTEL_SEMCONV_STABILITY_OPT_IN?

Solo si tu instrumentación emitía convenciones HTTP experimentales y quieres pasar a las estables. Usa http/dup para migrar sin interrupción y después http.

¿Pueden cambiar los atributos service.*?

No: la especificación indica que los atributos de recurso service.* no deben cambiar nunca.

Conclusión

Los niveles de estabilidad indican qué nombres son seguros. Haz el inventario, duplica la emisión, reescribe las consultas y después cambia: la migración sigue siendo un trabajo ordinario de plataforma, no una urgencia.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Dynatrace es una marca de Dynatrace LLC. Las marcas citadas pertenecen a sus propietarios. La información procede de la documentación oficial de OpenTelemetry (versión 1.44.0 de las convenciones semánticas consultada el 31 de octubre de 2026); compruébala para tu versión.

Total
0
Shares
Leave a Reply

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

Previous Post
DQL timeframe : from, to et pourquoi peu de lignes

DQL timeframe: from, to y por qué una consulta devuelve pocas filas

Next Post
Injection de prompt MCP : limiter le rayon d'action de l'agent

Inyección de prompts MCP: limitar el radio de acción del agente

Related Posts