Es jueves de rebajas y a ratos el carrito de una tienda en línea responde con una página en blanco. El panel está en verde, no ha saltado ninguna alerta, y aun así la traza del ticket muestra una llamada de cuatro segundos. Para entender qué pasó hay que dominar la anatomía de un span OpenTelemetry: cada campo contesta una pregunta concreta, y una respuesta que falta ya es una pista. Esta guía recorre el caso campo por campo y después lo repite con DQL en Dynatrace SaaS.
El alcance es solo SaaS: la documentación de DQL y Grail en la que me apoyo no describe Dynatrace Managed. Y para que quede claro qué está comprobado: no he ejecutado ninguna consulta. El span de abajo es inventado; las consultas salen de la documentación o van marcadas como «no ejecutadas».
Anatomía de un span OpenTelemetry: la ficha de identidad
En la red (formato OTLP, archivo trace.proto) un span es simplemente un registro con unos pocos campos numerados. La especificación de la API de trazas lo resume así: un nombre, un contexto inmutable, un padre opcional, un tipo, dos marcas de tiempo, atributos, vínculos, eventos y un estado. Esta es la tabla que tengo siempre a mano.
| Campo OTLP | Pregunta que responde |
|---|---|
trace_id (16 bytes, obligatorio) |
¿A qué historia pertenece este span? |
span_id (8 bytes, obligatorio) |
¿Cuál es, dentro de esa historia? |
parent_span_id |
¿Quién lo llamó? Vacío en la raíz. |
name (obligatorio) |
¿Qué estaba haciendo? |
kind |
¿En qué lado del intercambio estaba? |
start_time_unix_nano, end_time_unix_nano |
¿Cuándo, en nanosegundos desde la época Unix? |
attributes |
¿En qué condiciones (ruta, método, host)? |
events, links |
¿Qué ocurrió por el camino? ¿Con quién tenía relación? |
status (code, message) |
¿Cómo terminó? |
Dos detalles de la especificación evitan sorpresas. Los identificadores deben tener al menos un byte distinto de cero. Además, el span lleva trace_state (la cabecera W3C tracestate) y tres contadores de elementos descartados: dropped_attributes_count, dropped_events_count y dropped_links_count. Si uno de ellos no es cero, el SDK ha recortado su propia historia.
El sospechoso: el span del carrito
Este es el span que imaginé para el ticket, en JSON OTLP. Esa codificación tiene sus reglas: identificadores en hexadecimal, nombres en lowerCamelCase, enumeraciones como enteros y enteros de 64 bits como cadenas. Los valores son ficticios.

Lectura rápida: el nombre GET /cart/{id} es una ruta y no la URL real, así que el número de valores distintos se mantiene bajo. kind: 2 equivale a SPAN_KIND_SERVER (el proto reserva el 0 para «sin especificar») y el code: 2 del estado, a STATUS_CODE_ERROR. Aquí todo cuadra. Lo interesante es qué pasa cuando no cuadra.
Primera trampa: ¿en qué lado estamos?
El tipo del span indica quién espera a quién. Hay cinco valores:
- SERVER: atiende una petición que llegó de fuera, y alguien espera la respuesta;
- CLIENT: envía una petición y espera él mismo;
- PRODUCER: lanza o programa un trabajo y suele terminar antes de que ese trabajo empiece;
- CONSUMER: ejecuta un trabajo que dejó un productor que no espera el resultado;
- INTERNAL: el valor por defecto, un paso interno del proceso.
En mi escenario el carrito llama a un servicio de inventario, así que espero un span CLIENT en el carrito y un SERVER en el inventario. Si ambos aparecen como INTERNAL, la instrumentación es parcial y los mapas de dependencias pierden las flechas. En Dynatrace la documentación escribe span.kind en minúsculas (server, client, consumer, producer).
Segunda trampa: atributos puestos demasiado tarde
Los atributos cuentan las condiciones de la operación. La especificación recomienda darlos al crear el span, porque un muestreador solo decide con lo que existe en ese momento; y cuando el span ya terminó, nada puede cambiar. Para un span HTTP de servidor, las convenciones semánticas esperan http.request.method, url.path y url.scheme, más http.route y http.response.status_code cuando se conocen. Del lado del cliente: http.request.method, server.address, server.port y url.full.
Para saber qué nombres son estables y cuáles están en transición, consulta las convenciones semánticas de OpenTelemetry; para lo que añade Dynatrace, los atributos de OpenTelemetry en Dynatrace. Otro dato útil: Dynatrace conserva los arrays y las listas clave-valor y los deja consultables en DQL. La página de ingesta menciona un límite habitual de 128 atributos, eventos y vínculos por span, que Dynatrace no impone.
Tercera trampa: el error que no figura como error
Volvamos al carrito en blanco. El span muestra una excepción, pero el panel sigue en verde. La causa probable es el estado: vale Unset por defecto y solo pasa a Ok o Error si alguien lo decide; el mensaje descriptivo solo tiene sentido con Error. La especificación desaconseja que las bibliotecas de instrumentación pongan Ok sin configuración explícita. En HTTP, un 4xx deja el span SERVER sin estado, mientras que un 5xx pide Error.
Eventos y excepciones
Un evento es una nota con marca de tiempo dentro del span. RecordException crea uno llamado exception, con exception.type, exception.message y, si se pide, la pila. Una excepción capturada y tragada deja rastro en events sin tocar nunca el estado: es justo nuestro carrito. Ojo: la página de convenciones sobre excepciones en spans figura como obsoleta a favor de los logs; comprueba qué hace tu SDK.
Vínculos
Un vínculo apunta al contexto de otro span, de la misma traza o de otra, y lleva sus propios atributos. Sustituye a la relación padre-hijo cuando esta no encaja: un proceso por lotes que consume veinte mensajes no puede tener veinte padres.
Repetir la investigación con DQL
En Dynatrace SaaS, fetch spans expone este modelo: trace.id, span.id, span.parent_id (bytes mostrados en hexadecimal), span.kind, start_time, end_time y duration. El estado es span.status_code, presente solo para error u ok, con span.status_message. Eventos y vínculos son arrays: span.events y span.links.
La consulta 1 relee la traza de nuestro sospechoso (no ejecutada); la consulta 2 es la de la documentación de Advanced Tracing Analytics y cuenta las excepciones por tipo.

- Carga la traza con la consulta 1 en un notebook, usando un identificador real y un intervalo que abarque la hora del span.
- Localiza la raíz: es la fila cuyo
span.parent_idestá vacío; las demás apuntan alspan.idde su padre. - Busca los fallos reales con
filter span.status_code == "error"(no ejecutado, según la definición del campo) y compara con el número de spans que llevan una excepción sin estado. - Abre los eventos con la consulta 2:
expand span.eventsy luegofieldsFlattendejan sus atributos listos para filtrar.
Si los comandos te resultan nuevos, empieza por filter, summarize y timeseries.
Cómo comprobar que funciona
Envía un span de prueba: la consulta 1 debe devolver una fila por span, con span.parent_id y duration correctos. El token de ingesta OTLP necesita el ámbito que cita la página «OTLP API» (openpipeline:traces:ingest cuando la leí), y esa API solo acepta HTTP con Protobuf, ni gRPC ni JSON. Otros artículos de este blog mencionan openTelemetryTrace.ingest: valida el ámbito vigente antes de crear el token. Si no aparece nada, sigue trazas OpenTelemetry ausentes en Dynatrace.
Qué hace fracasar la investigación
- Reloj fuera de ventana: según la documentación de ingesta, el final del span no puede ser anterior a 60 minutos ni superar en 10 minutos el futuro.
- Dos padres posibles: OneAgent y OpenTelemetry en la misma traza pueden generar duplicados. La documentación prevé
span.alternate_parent_id, un campo experimental; más detalle en los spans duplicados. - Nombre variable: un identificador de cliente dentro del nombre del span dispara el número de valores distintos.
Mis hábitos de instrumentación
- Nombrar por ruta u operación estable.
- Pasar los atributos necesarios al crear el span.
- Poner
Erroren los fallos reales, también tras una excepción capturada, y dejarUnseten el resto. - Mantener los datos personales fuera de atributos y mensajes de excepción.
Preguntas frecuentes
¿Qué diferencia hay entre un span y una traza?
El span es una operación. La traza es el conjunto de spans que comparten un mismo trace_id, enlazados por sus padres.
¿Conviene un evento o un atributo?
El atributo califica el span completo; el evento fecha un instante concreto, como una excepción o un reintento.
¿Dónde se lee el estado de un span en Dynatrace?
En span.status_code (y span.status_message). El campo no existe cuando el estado es Unset, lo que explica muchos errores invisibles.
Conclusión
Ante un span sospechoso, haz siempre las mismas preguntas y en el mismo orden: de qué historia es, quién lo llamó, en qué lado estaba, en qué condiciones, qué ocurrió y cómo terminó. En Dynatrace SaaS, fetch spans responde a cada una. Toma una traza real, relee con la consulta 1 y compara con lo que emite tu SDK. Referencia: la especificación de la API de trazas de OpenTelemetry.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión.