Detrix

Depurador agéntico

GitHub

Prueba este MCPPatrocinado

Documentación

Detrix

Dale a tu agente de IA ojos dentro de cualquier programa en ejecución.

Observa cualquier variable en cualquier línea — el agente establece un punto de observación en segundos, sin cambios de código durante la depuración
Local o en la nube — el mismo flujo de trabajo para contenedores Docker y hosts remotos
Python, Go, Rust — los puntos de observación capturan valores sin pausar, sin reiniciar
Diseñado para agentes — observa, consulta, gestiona observaciones mediante lenguaje natural; Claude Code, Cursor, Windsurf

Véalo en acción

Demo de 1 minuto: Un servicio Go en Docker comienza a reportar números incorrectos. Nada en el código del cliente cambió. Claude lo observa en vivo y encuentra la causa.

Así es como se ve la sesión:

You:    "The order-service in Docker is reporting wildly inflated revenue.
         Daily total is in the thousands when transactions should be $20-200."

Agent:  → reads the source, spots dead unit-conversion code
        → wakes the service via Detrix
        → observes txn.Amount, txn.Unit, total
          (no line number — find_variable locates it in the running container)

        "Found it. The pricing API changed what it's returning.

        txn.Amount = 8957, txn.Unit = "cents" → should be $89.57, summed as $8957

        In calculateRevenue, the unit field is fetched and discarded:

        unit := txn.Unit
        _ = unit          // ← conversion was intended, never implemented
        total += amount   // ← adds cents as if they were dollars

        This didn't matter before. It matters now."

        → fixed the client code
        → reported the API contract change upstream

No se modificó código para instrumentar. Sin reinicios. El flujo de trabajo antiguo — agregar una línea de log, recompilar, redesplegar, esperar a que el bug se reproduzca — reemplazado por observarlo en vivo.

Tampoco necesitas saber el número de línea — describe el comportamiento y el agente encuentra dónde mirar.

¿Por qué Detrix?

Encontraste un bug. El flujo de trabajo antiguo: agregar un print, reiniciar, reproducir, quitar el print, repetir. Si está en producción, redesplegar. Si está en un contenedor Docker, entrar al contenedor. Si es intermitente, esperar.

Con Detrix, solo le pides al agente. Encuentra la línea correcta, planta un punto de observación y te dice lo que ve — en vivo, sin reiniciar nada.

Ese bug que te costó horas la semana pasada — redespliegue tras redespliegue, sin poder reproducirlo — tu agente puede investigarlo en minutos, mientras tu aplicación sigue funcionando.

	`print()` / `logging`	Detrix
Velocidad de iteración	Horas (editar → recompilar → desplegar)	Minutos
Agregar nueva observación	Editar código → reiniciar	Pídele al agente — sin código, sin reinicio¹
Seguro para producción	Contaminación de salida, riesgo de rendimiento	Puntos de observación no intrusivos
Eventos	Flujo efímero	Almacenados, consultables por métrica y tiempo
Control de captura	Cada acierto, sin filtrado	Límite, muestreo, primer acierto, intervalo
Limpieza	Manual (fácil de olvidar, llega a producción)	Un comando — o expiración automática
Datos sensibles	Los secretos pueden filtrarse a través de la salida de logs	Variables con nombres sensibles bloqueadas por defecto; lista negra + lista blanca configurable en `detrix.toml`

¹ Incrusta detrix.init() una vez para cero reinicios para siempre. O reinicia una vez para adjuntar el depurador (--debugpy, dlv, lldb-dap) — a partir de ese punto, el agente agrega y elimina observaciones sin más reinicios.

Inicio rápido

Pruébalo en 2 minutos. Tu agente se encarga de todo después del paso 3.

1. Instalar Detrix

macOS (Homebrew):

brew install flashus/tap/detrix

macOS / Linux (script de shell):

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/flashus/detrix/releases/latest/download/detrix-installer.sh | sh

Windows (PowerShell):

irm https://github.com/flashus/detrix/releases/latest/download/detrix-installer.ps1 | iex

Docker (linux/amd64, linux/arm64):

docker pull ghcr.io/flashus/detrix:latest

Compilar desde el código fuente:

cargo install --git https://github.com/flashus/detrix detrix

Luego inicializa (crea la configuración y configura el almacenamiento local):

detrix init

2. Agregar a tu aplicación

Una línea — el depurador duerme hasta que tu agente lo necesite, cero sobrecarga cuando está inactivo:

import detrix
detrix.init(name="my-app")

Go y Rust funcionan de la misma manera — consulta Integración de aplicaciones.

3. Conecta tu agente

Claude Code:

claude mcp add --scope user detrix -- detrix mcp

Cursor / Windsurf — agrega a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "detrix": {
      "command": "detrix",
      "args": ["mcp"]
    }
  }
}

Para configuración en la nube y otros editores, consulta la guía de configuración.

Eso es todo. Pídele a tu agente que observe cualquier línea en tu aplicación en ejecución — sin reinicios, nada llega a producción.

Alternativa: conectar sin incrustar

¿No quieres agregar una dependencia? Inicia tu aplicación directamente bajo un depurador:

# Python
python -m debugpy --listen 127.0.0.1:5678 app.py

# Go
dlv debug --headless --listen=127.0.0.1:5678 --api-version=2 main.go

# Rust
lldb-dap --port 5678

Escucha en 127.0.0.1 — solo local. Consulta la guía de configuración de lenguajes para remoto y Docker.

Cómo funciona

Detrix es un demonio que se ejecuta localmente o en la nube y conecta tu agente de IA a cualquier proceso en ejecución mediante 29 herramientas MCP. Internamente, habla con el depurador de tu aplicación a través del Protocolo de Adaptador de Depuración (DAP). Establece logpoints — puntos de interrupción que evalúan una expresión y registran el resultado en lugar de pausar. Tu aplicación se ejecuta a toda velocidad; Detrix captura los valores.

  AI Agent                 Detrix Daemon              Debugger (DAP)         Your App
  (Claude Code, Cursor,    (local or Docker/cloud)    debugpy / dlv /        (Python/Go/Rust,
    Windsurf, local)                                  lldb-dap               local/cloud)
      │                         │                          │                      │
      │── "observe line 127" ──▶│                          │                      │
      │                         │── set logpoint ─────────▶│                      │
      │                         │                          │── captures value ───▶│
      │                         │◀────────────── captured values ─────────────────│
      │◀── structured events ───│                          │                      │
      │                         │                          │                      │
      │         App never pauses. No code changes. No restarts.                   │

El demonio se ejecuta localmente o junto a tu servicio en Docker — el mismo protocolo en ambos casos. En modo nube, los archivos fuente se obtienen automáticamente para que el agente pueda encontrar las líneas correctas sin tenerlos en tu máquina. Consulta la Guía de instalación para la configuración en la nube.

Integración de aplicaciones

import detrix
detrix.init(name="my-app")   # That's it. Agent controls the rest.

Lenguaje	Instalación	Documentación
Python	`pip install detrix-py`	Cliente Python
Go	`go get github.com/flashus/detrix/clients/go`	Cliente Go
Rust	`detrix-rs = "1.2.0"` en Cargo.toml	Cliente Rust

Patrón de producción: Construye una instancia de servicio con símbolos de depuración y un cliente Detrix. Enruta el tráfico sospechoso hacia ella mediante Kafka, un sidecar o tu balanceador de carga. El resto de tu flota se ejecuta sin verse afectada — a toda velocidad, sin sobrecarga de instrumentación. Obtienes observabilidad profunda en una instancia sin tocar producción.

Consulta el Manual de clientes para documentación completa.

Configuración de compilación para observabilidad

Detrix utiliza logpoints del depurador para observar variables. Para que las expresiones se evalúen correctamente, el binario necesita símbolos de depuración (información DWARF). La buena noticia: no necesitas una compilación de depuración. Cada lenguaje tiene una estrategia amigable para producción que preserva la mayoría de la visibilidad de variables con un impacto mínimo en el rendimiento.

Go

El go build predeterminado de Go ya produce un binario optimizado con símbolos de depuración DWARF. Delve se adjunta a él y evalúa expresiones de logpoint en la mayoría de las variables — especialmente campos de struct asignados en el heap. No se necesitan banderas especiales.

# This is already debuggable. Nothing to change.
go build -o myservice ./cmd/myservice

Si el optimizador oculta una variable local específica (<optimized out>), usa banderas de depuración por paquete para desactivar optimizaciones solo donde necesitas visibilidad:

# Disable optimizations in the payments package only.
# net/http, encoding/json, and all other packages stay fully optimized.
go build -gcflags="myservice/internal/payments=-N -l" -o myservice ./cmd/myservice

Compilación	Rendimiento	Visibilidad de variables
`go build` (predeterminado)	Velocidad completa	Alta — campos de struct, la mayoría de locales
`go build -gcflags="pkg=-N -l"`	Un paquete más lento	~100% en ese paquete
`go build -gcflags="all=-N -l"`	Todos los paquetes más lentos	100% en todas partes (solo desarrollo)

Eliminar símbolos (-ldflags="-s -w") elimina la información DWARF y hace imposible la depuración. Si eliminas símbolos para producción, mantén una instancia con símbolos para Detrix.

Rust

Las compilaciones de depuración de Rust (cargo build) son 10-100 veces más lentas que las de release — inutilizables en producción. En su lugar, usa un perfil de Cargo personalizado que compile tus dependencias con optimización completa (O3) y tu código a un nivel más bajo (O1) que preserve la mayoría de la visibilidad de variables:

# Cargo.toml — add a "detrix" profile for observable production builds

[profile.detrix]
inherits = "release"
opt-level = 1              # Your code: light optimization, most variables visible
debug = 2                  # Full DWARF debug info
codegen-units = 16         # Default parallelism

[profile.detrix.package."*"]
opt-level = 3              # All dependencies: full optimization
debug = false              # No debug info needed for deps (smaller binary)

cargo build --profile detrix

Perfil	Tu código	Dependencias	Rendimiento vs release	Visibilidad de variables
`release`	O3, sin depuración	O3, sin depuración	Línea base	No se puede observar
`release` + `debug = 2`	O3, DWARF	O3, sin depuración	~0-2% de sobrecarga	Baja — muchos locales optimizados
`detrix` (recomendado)	O1, DWARF	O3, sin depuración	~5-15% de sobrecarga	Alta — la mayoría de variables visibles
`dev` (depuración)	O0, DWARF	O0, DWARF	10-100 veces más lento	100% (solo desarrollo)

Advertencia sobre genéricos: El código genérico de dependencias (serde, tokio, axum) se monomorfiza en tu crate y se compila con tu nivel de optimización (O1), no con el de la dependencia (O3). Para la mayoría de los servicios esto es insignificante ya que domina la E/S, pero los caminos calientes con mucha serialización pueden ver un impacto mayor.

Para funciones que quieras mantener completamente visibles independientemente de la optimización:

#[inline(never)]  // Prevents inlining — always visible as a separate stack frame
fn process_order(order: &Order) -> Result<ProcessedOrder> {
    // Detrix can always set logpoints here
}

Python

No se necesita configuración especial de compilación. CPython siempre es depurable — debugpy se adjunta al intérprete en ejecución tal cual.

import detrix
detrix.init(name="my-app")  # Works on any Python 3.10+ installation

Consulta el Manual de clientes para documentación completa.

Características

Sin cambios de código. El agente instrumenta tu código en ejecución mediante puntos de observación — nada se confirma, nada llega a producción.

Sin pausas. Los puntos de observación evalúan expresiones a velocidad de ejecución completa, sin detenciones tipo breakpoint. Para rutas de código de alta frecuencia, usa modos de muestreo o límite para controlar el volumen de eventos.

Sin limpieza olvidada. Las métricas expiran automáticamente mediante TTL, o elimina todo con un comando.


Herramientas del agente	29 herramientas MCP — observa cualquier línea, consulta eventos, habilita/deshabilita grupos de observación y limpia; no se necesita número de línea
Instrumentación sin tiempo de inactividad	Agrega métricas sin reiniciar tu aplicación
Captura de múltiples variables	Captura múltiples variables por punto de observación
Modos de captura	Flujo, muestreo, límite, primer acierto, muestreo periódico (cada N segundos)
Introspección en tiempo de ejecución	Trazas de pila, instantáneas de memoria, inspección de variables, evaluación de expresiones
Multilenguaje	Python (debugpy), Go (delve), Rust (lldb-dap)
Depuración en la nube	Observa contenedores Docker y hosts remotos — sin VPN, sin reenvío de puertos
Almacenamiento duradero	Eventos almacenados en SQLite en el host del demonio. Ejecuta Detrix en un servidor remoto, conecta tu agente por la mañana y pregunta qué pasó durante la noche. El demonio se reconecta automáticamente al adaptador de depuración si se reinicia.
Extensible	Nuevos frontends mediante API abierta; nuevo soporte de lenguajes implementando un adaptador de lenguaje — Agregar lenguajes
Validación de seguridad	Nombres de variables sensibles (`password`, `api_key`, `token`, `secret`, `private_key`, etc.) bloqueados antes de la captura. Lista negra + lista blanca configurable para nombres de variables y funciones en `detrix.toml`. Habilita el modo seguro por conexión para permitir solo observación de variables — sin ejecución de expresiones, sin trazas de pila, sin instantáneas de memoria. Las operaciones bloqueadas devuelven un error claro con nombre para que el agente pueda explicar la restricción.
Autenticación	Control de acceso multiinquilino: tokens estáticos por usuario o JWT/JWKS, autorización basada en roles (Admin/Usuario), aislamiento de métricas por agente — Guía de autenticación
Transmisión de eventos	Reenvía eventos capturados a Graylog
4 protocolos API	MCP (stdio), gRPC, REST, WebSocket

Documentación


Guía de instalación	Instalación, configuración de lenguajes, configuración de agentes, depuración en la nube
Modo agente independiente	Observación centralizada en Linux/Go/eBPF con agentes autenticados
Autenticación	Modos de autenticación, tokens por usuario, JWT/JWKS, control de acceso
Referencia de CLI	Interfaz de línea de comandos
Manual de clientes	Bibliotecas de cliente para Python, Go, Rust
Arquitectura	Arquitectura limpia con 13 crates de Rust
Agregar lenguajes	Extiende Detrix a nuevos lenguajes

Contribuciones

cargo fmt --all && cargo clippy --all -- -D warnings && cargo test --all

Haz un fork del repositorio
Crea una rama de características
Ejecuta las verificaciones anteriores
Envía una solicitud de extracción (Pull Request)

Licencia

Licencia MIT — consulta LICENCIA.

¿Encontraste un bug? Abre un issue. ¿Encontraste en minutos lo que te tomó días? Cuéntanos en Discussions.