Observabilidad, auditoría y confiabilidad

En un servicio web, una línea de log como "pedido creado, 34 ms" suele bastar, porque el código explica el resto. El código del loop de un agenteAgente Sistema en el que un modelo, dentro de un bucle, elige la siguiente acción hasta decidir que terminó o alcanzar una condición de parada. es el mismo en cada ejecución; lo que cambia es lo que decidió el modelo. "Turno terminado, falló, 212 s" no explica nada. Para saber por qué un agente falló, borró un archivo o se comió los tokensToken Pedacito de texto, a menudo parte de una palabra, que el modelo lee y escribe y por el que cobran los proveedores., hay que reconstruir su trayectoria: la secuencia de decisiones y acciones que tomó.

Esta lección cubre tres disciplinas que suelen confundirse: la observabilidadObservabilidad Poder responder preguntas nuevas sobre el sistema a partir de los eventos, trazas y métricas que emite. (entender qué pasó), la auditoría (probar quién autorizó qué) y la confiabilidad (que las fallas, los reintentos y las paradas dejen el sistema en un estado consistente).

Rastrear lo que hizo un agente

Observabilidad es poder responder preguntas nuevas sobre un sistema a partir de los datos que ya registra; en un agente, poder reconstruir cualquier ejecución. El vocabulario viene de los sistemas distribuidos: una traza agrupa todo lo que ocurrió en una operación, y un span es un paso dentro de ella, con inicio, fin y un paso padre. En un agente eso se traduce en tarea, luego turno, luego cada llamada al modelo y cada uso de herramienta.

Esta es una ejecución vista como traza. Mira la cuarta línea: lo que la hizo lenta fue una persona aprobando un comando, no el modelo.

run 123  "arreglar el test de login"          tokens   tiempo
├─ llamada al modelo #1 → buscar en el código  3 100   2.1 s
├─ herramienta búsqueda  permitida  ok                 0.1 s
├─ llamada al modelo #2 → correr los tests     4 900   2.8 s
├─ herramienta shell  pide aprobación → aprobada tras 38 s
├─ herramienta shell  ejecutada  falló                 9.4 s
├─ llamada al modelo #3 → editar archivo auth  7 400   3.5 s
└─ resultado ok  terminó con un mensaje final  total 81 s

Una traza responde lo que un log plano no puede: por qué la ejecución tardó, por qué costó lo que costó y qué archivos tocó.

Qué registrar

Registra el modelo que respondió de verdad, no solo el que se pidió. Es la defensa más barata contra un proveedor o un gateway que sirve en silencio otro modelo bajo el mismo nombre.

Auditoría no es observabilidad

Cuatro términos suenan parecido, pero hacen preguntas distintas:

• Observabilidad: ¿por qué se comportó así?
• Audit trail (rastro de auditoría): ¿quién hizo o autorizó qué, bajo qué regla?
• Tamper-evidentTamper-evident Registro cuya modificación se puede detectar, lo que no equivale a que sea imposible modificarlo o borrarlo. (que deja en evidencia las alteraciones): si alguien alteró el registro, ¿lo notaríamos? Detecta cambios.
• Inmutable: ¿se puede alterar el registro? Impide cambios.

Una traza puede guardar solo una muestra de las ejecuciones y seguir siendo útil. Un audit trail no, porque la acción que falta es justo la que alguien va a preguntar. En un agente, "¿quién hizo esto?" es una cadena: un modelo, el harnessHarness El software alrededor del modelo que ejecuta su loop, lleva a cabo las herramientas que pide, prepara lo que ve y aplica límites. que lo ejecutó, una tarea en cola, una política y quizá la aprobación de una persona. Si falta un eslabón, nadie responde.

Cadenas de hashes

Un hash es una huella corta calculada a partir de unos datos; cambia un carácter y la huella cambia por completo. En una hash chain (cadena de hashes), cada entrada del log guarda también la huella de la anterior. Si se edita o borra una entrada intermedia, se rompe el vínculo con la siguiente.

Conviene ser preciso con lo que eso compra. Sin clave secreta y sin nada guardado en otro lado, una cadena atrapa ediciones torpes o accidentales, pero no a alguien con permiso de escritura que sabe cómo está construida: puede recalcular todas las huellas, o cortar las últimas entradas, y nada lo mostrará. Los siguientes escalones son una huella que requiere una clave guardada en otra máquina, copiar cada cierto tiempo la última huella a otro sistema, almacenamiento de una sola escritura en una cuenta separada y, por último, separación de funciones: quien opera los agentes no controla el almacén de auditoría.

Hay que saber dónde vive cada evidencia. docket audita toda decisión que no sea un simple "permitir": denegaciones, pedidos de aprobación, aprobaciones y cancelaciones. Las acciones permitidas quedan en la traza, que no está encadenada y expira a los 30 días (README).

Reintentos y hacer las cosas dos veces

No todo error merece un reintento:

La receta habitual: esperar más después de cada falla, agregar un poco de azar para que los clientes no reintenten todos al mismo tiempo, y respetar la indicación del proveedor de "vuelve a intentar después de". Un circuit breaker (cortacircuitos) deja de llamar a un proveedor que falla una y otra vez.

Los reintentos implican que la misma acción puede ejecutarse dos veces, y el modelo también se repite. Por eso toda herramienta que cambia algo afuera, como cobrar una tarjeta o enviar un correo, debería ser idempotente: ejecutarla dos veces tiene el mismo efecto que una. Una forma común es una idempotency key (clave de idempotenciaIdempotencia Propiedad de una operación cuya repetición tiene el mismo efecto que ejecutarla una vez.), una etiqueta única en cada pedido para reconocer las repeticiones.

Detener un agente de forma segura

Detener un agente no es matar su proceso. Un cierre forzado puede dejar un pedido de herramienta sin respuesta en el historial, procesos hijos corriendo, efectos a medio hacer y ningún registro de quién detuvo qué.

La cancelación cooperativa separa pedir que se detenga de detenerse. El pedido se guarda de forma durable al instante; el trabajo en curso lo revisa en puntos seguros y se detiene con su estado consistente. El precio es que no es inmediata.

Tack llega a la misma conclusión desde el otro lado: las herramientas de código que ejecuta lanzan sus comandos en sus propias sesiones de procesos, así que Tack rechaza cualquier adaptador que afirme poder cancelarlas (Agent Runners & Fleet Execution).

En la práctica

• Nombra la amenaza antes de elegir un mecanismo de auditoría. Un bug, un operador descuidado y un administrador hostil requieren niveles de protección distintos.
• Decide dónde se guardarán los promptsPrompt Todo lo que se envía al modelo en una llamada: instrucciones, mensajes de la conversación y las definiciones de herramientas, si las hay. antes de adoptar una plataforma de trazas.
• Mide cuánto tarda de verdad "cancelar" antes de confiar en el botón.
• Exige que toda herramienta con efectos externos declare si es seguro ejecutarla dos veces.

Para profundizar

La documentación de docket y de Tack muestra trazas, auditoría y cancelación en un sistema que funciona (en inglés):

• Security model describe qué registra el log de auditoría de docket, cómo la rotación mantiene verificable la cadena un archivo hacia atrás y qué no puede ver el log.
• Workflow guide muestra cómo leer la traza de una tarea, seguir una ejecución en vivo y cancelarla, incluido qué significa "cancel requested" mientras el trabajo todavía se está deteniendo.
• Architecture explica, en su sección sobre el despacho, los estados por los que pasa una tarea, qué fallas se reintentan y cómo la cancelación llega al trabajo en curso.
• Agent runners and fleet execution cubre los pedidos de ejecución idempotentes de Tack, los intentos numerados, por qué cancelar es siempre solo un pedido y la recuperación que espera a una persona.

Para llevar

• A un agente se lo depura por su trayectoria, no por sus líneas de log: registra decisiones, tokens medidos, el modelo que respondió y por qué se detuvo.
• Observabilidad, audit trail, tamper-evident e inmutable son requisitos distintos; usa la palabra precisa.
• Una cadena de hashes local atrapa ediciones torpes, no a alguien con permiso de escritura que sabe cómo funciona.
• Reintenta solo fallas temporales, con esperas crecientes, y haz que las acciones con efectos externos se puedan repetir sin daño.
• Detenerse es cooperativo: un pedido guardado, puntos de control seguros y un registro de cuándo paró de verdad el trabajo.

Comprueba lo aprendido