Cómo diagnosticar una automatización con trazas útiles

Empieza por una pregunta que puedas resolver

Un flujo prepara un borrador comercial, intenta guardarlo y termina con un error. Antes de repetirlo necesitas saber si el destino recibió la escritura. El mensaje «falló la automatización» no permite decidirlo. Necesitas relacionar la solicitud, la versión del borrador, el intento de escritura y el recibo del destino.

Esta guía propone un registro para investigar ese problema. El paquete descargable contiene un esquema JSON y siete eventos inventados. Es un diseño didáctico: no procede de una ejecución, no mide un modelo y no instrumenta un CRM. Las configuraciones actuales del Atlas preparan borradores; el guardado descrito aquí representa un almacén hipotético anterior a la incorporación al CRM.

Separa cuatro identidades

Añade una identidad distinta para cada evento: event_id. Permite reconocer una entrega duplicada al recolector sin confundirla con una segunda escritura. No utilices el email del contacto como identidad de operación: puede aparecer en solicitudes legítimas diferentes.

La documentación de trazas de OpenTelemetry describe unidades de trabajo llamadas spans, con inicio, fin y relaciones entre ellas. Ese modelo ayuda a reconstruir recorridos. Nuestro paquete utiliza campos propios para explicar el caso; no representa spans exportados ni un formato OTLP válido.

Sigue el fallo hasta el destino

La operación ficticia SYN-CRM-017 conserva la misma revisión y huella de contenido durante toda la secuencia:

1. operation_received: el ejecutor recibe la operación.
2. write_started: comienza el intento de escritura número uno.
3. effect_committed: el destino declara que guardó el borrador y su recibo.
4. write_outcome_unknown: el ejecutor agota la espera sin recibir confirmación.
5. reconciliation_started: otro proceso consulta el destino con la identidad original.
6. receipt_matched: encuentra un recibo cuya huella coincide con la esperada.
7. operation_completed: actualiza el estado técnico de la operación.

El contador sigue en uno: consultar un recibo no es repetir una escritura. El evento del destino y el timeout del ejecutor pueden coexistir porque describen observaciones diferentes. Consulta la guía de reintentos para practicar ese fallo con un ejecutor local; sus resultados pertenecen a otro laboratorio y no son el origen de estos eventos.

En una integración real, comprueba qué acredita el recibo. Debe estar vinculado al efecto y al contenido mediante el contrato del destino. Una línea de log escrita antes del commit no acredita que la transacción terminó. Si el recibo no aparece, conserva el estado incierto y sigue la política de reconciliación; la ausencia de un evento tampoco demuestra que nada ocurrió.

Define qué significa cada tiempo

occurred_at representa cuándo el componente declara que ocurrió el evento. recorded_at representa cuándo el recolector lo registró. En el ejemplo, el evento de commit llega al recolector después del timeout, aunque ocurrió antes. Ordenar por llegada produciría una historia engañosa.

OpenTelemetry distingue el instante del evento del instante observado en su modelo de logs. Los nombres y el punto de captura de nuestra plantilla son decisiones propias que debes documentar al adaptarla.

duration_ms mide únicamente el intervalo definido por duration_scope y started_event_id: espera del intento o consulta de reconciliación. Todos sus valores son inventados. En una implementación, mide intervalos dentro de un proceso con un reloj monotónico y registra su ámbito; no restes relojes de máquinas distintas sin conocer su sincronización. La duración total también puede incluir cola, espera humana y recuperación. No equivale a latencia del modelo.

Conserva contexto suficiente para investigar

El esquema incluye versión de configuración, revisión de propuesta, componente emisor y secuencia por proceso. La huella permite contrastar contenidos sin guardar el mensaje completo. Una huella no anonimiza datos por sí sola: evita publicar valores derivados de información personal y conserva las entradas necesarias en un almacén con acceso controlado.

Para una llamada real a un modelo necesitarías añadir versión del modelo, configuración y referencia al artefacto de entrada y salida. El ejemplo no contiene esa llamada ni inventa tokens, costes o razonamientos internos. Una decisión del ejecutor puede registrar su motivo verificable, como «recibo coincidente», sin solicitar una explicación privada del razonamiento del modelo.

El esquema de objetos de JSON Schema permite exigir campos y rechazar propiedades inesperadas. La plantilla declara el dialecto 2020-12. Validar cada línea comprueba estructura; no demuestra que los eventos ocurrieron ni verifica todas las relaciones entre líneas.

Busca discrepancias y comprueba el trabajo final

Al revisar una operación, busca identidades repetidas con contenidos distintos, cambios de revisión durante la escritura, recibos con huella incompatible y cierres sin evidencia del destino. Comprueba también saltos en la secuencia del mismo proceso. Un salto pide investigar pérdida o filtrado de telemetría; no prueba por sí solo un fallo de negocio.

Mantén separadas dos preguntas: «¿terminó el procedimiento técnico?» y «¿el borrador cumple la solicitud?». El último evento declara quality_status: not_evaluated: recuperar una escritura no valida los campos comerciales. Aplica después los criterios de aceptación del registro y la revisión humana.

Para preparar el piloto, toma una operación, reconstruye su recorrido y escribe qué evidencia falta para resolverla. Después instrumenta esos puntos y provoca el fallo de forma controlada. Conserva el estado final del destino junto a la traza: ambos son necesarios para explicar qué pasó.