Open source · Apache 2.0 · Java 17+
El código es el log.
Deja de escribir sentencias de log.
NarrativeTrace convierte tu código en ejecución en narrativas legibles: trazas de ejecución para quienes depuran, y contexto de ejecución seguro y eficiente en tokens para los agentes de IA que escriben código.
implementation("ai.narrativetrace:narrativetrace-core:0.1.0")
# Customer places order- OrderService.placeOrder("C-42", qty: 5) — 4.2ms - Customers.verifyGoodStanding("C-42") → true - PricingService.calculate(5) → 49.95 - PaymentService.charge(card: [REDACTED]) → PaymentConfirmation(txId="T-9") - OrderRepository.save(Order{…}) → Order{id=ORD-1001, total=49.95} // No se escribió ni una sentencia de log para esto.Antes y después
Borra el log. Conserva la historia.
Las sentencias de log son un tercio de una clase de servicio típica, y aun así se les escapa justo lo que necesitabas. NarrativeTrace captura automáticamente los nombres de los métodos, los parámetros, los valores de retorno y la estructura de llamadas. El código que ya escribiste es la narrativa.
Antes — logs por todas partes
public Order placeOrder(String customerId, int qty) {
log.info("Placing order for {} qty {}", customerId, qty);
customers.verifyGoodStanding(customerId);
log.debug("Customer in good standing");
var price = pricing.calculate(qty);
log.info("Calculated price: {}", price);
var order = repository.save(new Order(customerId, price));
log.info("Order saved: {}", order.getId());
return order;
}Después — el código es el log
public Order placeOrder(String customerId, int qty) {
customers.verifyGoodStanding(customerId);
var price = pricing.calculate(qty);
return repository.save(new Order(customerId, price));
}
// Cero líneas de log.
// NarrativeTrace captura la narrativa
// automáticamente.Traza generada — Markdown, JSON, prosa o diagrama de secuencia
- OrderService.placeOrder("C-42", 5)
- Customers.verifyGoodStanding("C-42") → true
- PricingService.calculate(5) → 49.95
- OrderRepository.save(Order{…}) → Order{id=ORD-1001, total=49.95}Para desarrollo asistido por IA
Tu agente de IA sabe leer el código.
Ahora puede verlo ejecutarse.
El vibe coding funciona hasta que algo se rompe y nadie —ni persona ni agente— sabe qué pasó realmente en tiempo de ejecución. NarrativeTrace les da a los agentes una verdad verificable: el árbol de llamadas real, no una suposición reconstruida leyendo el código estático.
La verdad de la ejecución, no conjeturas
Un agente que depura solo desde el código fuente infiere el comportamiento, y lo infiere mal. Una traza narrativa muestra qué se ejecutó, en qué orden, con qué parámetros y con qué resultados. Pégala en el contexto de cualquier agente, o adjunta los archivos de traza por test que tu CI ya genera.
Más lógica por ventana de contexto
Las sentencias de log son tokens de ruido. Quitarlas hace que leer una clase de servicio le cueste a un agente entre un 15 y un 30 % menos, y cada línea de una traza lleva señal, porque se generó a partir de nombres y no de prosa.
A prueba de inyección por diseño
La separación entre narrativa y valores mantiene los valores de ejecución no confiables estructuralmente aparte de la historia. El enmascaramiento viene incorporado, y el nivel de salida de solo estructura no envía ningún dato de usuario a un modelo: seguridad por construcción, no por filtro.
Cómo funciona la separaciónServidor MCP Pro Próximamente
Claude Code, Cursor y Copilot podrán consultar trazas, grafos de dependencias en tiempo de ejecución y datos de claridad directamente por el Model Context Protocol: solo lectura, con niveles de salida escalonados que por defecto entregan solo la estructura.
Ver el diseño del MCPEste sitio también es amigable con los agentes: apunta tu asistente a llms.txt o llms-full.txt y podrá adoptar NarrativeTrace por ti.
Para modernizar sistemas heredados
Migra el sistema que nadie entiende — con pruebas.
Los agentes de IA abarataron las reescrituras; lo caro es verificarlas. Envuelve un sistema heredado en trazas y obtienes su comportamiento real en ejecución —antes de tocarlo— y la prueba de equivalencia después.
Radiografía la arquitectura que de verdad tienes
Ejecuta los tests que ya existen —o simplemente la aplicación— con NarrativeTrace y lee qué ocurre en realidad, llamada por llamada. Sin arqueología de documentación ni conocimiento tribal. Incluye soporte para JUnit 4, porque heredado quiere decir JUnit 4.
Demuestra que el comportamiento no cambió Pro
Los diffs de migración comparan conjuntos de trazas de antes y después de una refactorización, una portación o una reescritura asistida por IA, detectando las divergencias y clasificando cada una por riesgo. La equivalencia de comportamiento deja de ser una corazonada y se vuelve un informe.
Diffs de migraciónSaca a la luz el acoplamiento oculto Pro
Grafos de dependencias en tiempo de ejecución agregados desde ejecuciones reales: aristas sólidas para las dependencias que siempre se invocan y punteadas para las condicionales, con sus frecuencias. Las dependencias circulares y los «god services» se quedan sin dónde esconderse.
Grafos de dependenciasEncuentra el código que peor se lee
Si la traza no se lee bien, el código está mintiendo sobre sí mismo. La puntuación de claridad califica la calidad de los nombres a partir de la narrativa de ejecución y dirige tu refactorización —o la de tu agente— primero a los peores rincones. Disponible en la edición gratuita.
Diagnóstico de claridadCómo funciona
Tres pasos hasta tu primera narrativa
Agrega dos dependencias
dependencies {
implementation(
"ai.narrativetrace:narrativetrace-core:0.1.0")
implementation(
"ai.narrativetrace:narrativetrace-proxy:0.1.0")
}Envuelve un servicio — o hazlo automático
var context = new ThreadLocalNarrativeContext();
var service = NarrativeTraceProxy.trace(
orderService, OrderService.class, context);
// o con Spring:
@EnableNarrativeTrace(
basePackages = "com.example.app")Lee la historia
service.placeOrder("C-42", 5);
System.out.println(
new IndentedTextRenderer()
.render(context.captureTrace()));
// JUnit 5/4: cada test escribe
// su propio archivo de traza.Ediciones
Gratis para personas. De pago para escala con IA y cumplimiento.
El límite es simple: leer trazas como desarrollador es gratis, para siempre, bajo Apache 2.0. El análisis entre ejecuciones, la integración con IA a escala y la auditoría de nivel de cumplimiento son de pago.
Open Source Disponible ahora
Todo lo que necesita una persona desarrollando, con cero dependencias en tiempo de ejecución en el núcleo.
- Trazas automáticas: proxy, agente Java, Spring, servlet
- Los cinco niveles de captura, conmutables en ejecución
- Anotaciones
@Narrated,@OnError,@NotTraced+ enmascaramiento - Archivos de traza por test en JUnit 5 y JUnit 4
- Salida en Markdown, JSON, prosa y diagrama de secuencia
- Puntuación de claridad y puente SLF4J
Pro Acceso anticipado
Análisis entre trazas, integración con IA y cumplimiento para equipos.
- Resúmenes de flujo y análisis de frecuencia de rutas
- Diffs de migración con clasificación de riesgo
- Grafos de dependencias en tiempo de ejecución
- Eventos de auditoría y SecOps con motor de políticas
- Servidor MCP para agentes de codificación — próximamente
- Niveles escalonados de salida para IA — próximamente
Platform Próximamente
Backend gestionado para las narrativas de cada servicio, entorno y ejecución.
- Ingesta OTLP gestionada para trazas
- Almacenamiento y búsqueda multiinquilino
- Paneles de equipo y políticas de retención
- Informes de claridad y auditoría para toda la organización
La comparación completa está en la descripción general de Pro.
Los artefactos open source están en Maven Central bajo ai.narrativetrace.
Integraciones
Se adapta a tu stack tal como está
Más allá de Java
Una arquitectura, todos los entornos
Captura narrativa, salida de doble consumidor y diagnóstico de claridad: el mismo diseño, portado.
Dale voz a tu código.
Cinco minutos hasta tu primera narrativa. No se escribió ni una sentencia de log para crear esta biblioteca.