Detrix

Depurador agentivo

GitHub

Experimente este MCPPatrocinado

Documentação

Detrix

Dê olhos ao seu agente de IA dentro de qualquer programa em execução.

Observe qualquer variável em qualquer linha — o agente define um ponto de observação em segundos, zero alterações de código durante a depuração
Local ou nuvem — o mesmo fluxo de trabalho para contêineres Docker e hosts remotos
Python, Go, Rust — pontos de observação capturam valores sem pausar, sem reiniciar
Feito para agentes — observe, consulte e gerencie observações via linguagem natural; Claude Code, Cursor, Windsurf

Veja em Ação

Demonstração de 1 minuto: um serviço Go em Docker começa a reportar números errados. Nada no código do cliente mudou. Claude observa ao vivo e encontra a causa.

Veja como é a sessão:

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

Nenhum código foi modificado para instrumentação. Sem reinicializações. O fluxo de trabalho antigo — adicionar uma linha de log, recompilar, reimplantar, esperar o bug se reproduzir — foi substituído por observação ao vivo.

Você também não precisa saber o número da linha — descreva o comportamento e o agente encontra onde procurar.

Por que Detrix?

Você encontrou um bug. O fluxo de trabalho antigo: adicionar um print, reiniciar, reproduzir, remover o print, repetir. Se estiver em produção, reimplantar. Se estiver em um contêiner Docker, entrar no contêiner. Se for intermitente, esperar.

Com Detrix, você apenas pede ao agente. Ele encontra a linha certa, planta um ponto de observação e informa o que vê — ao vivo, sem reiniciar nada.

Aquele bug que custou horas na semana passada — reimplantação após reimplantação, ainda sem conseguir reproduzir — seu agente pode investigá-lo em minutos, enquanto seu aplicativo continua rodando.

	`print()` / `logging`	Detrix
Velocidade de iteração	Horas (editar → recompilar → implantar)	Minutos
Adicionar nova observação	Editar código → reiniciar	Peça ao agente — sem código, sem reinício¹
Seguro para produção	Poluição de saída, risco de desempenho	Pontos de observação não intrusivos
Eventos	Fluxo efêmero	Armazenados, consultáveis por métrica e tempo
Controle de captura	Toda ocorrência, sem filtragem	Throttle, amostragem, primeira ocorrência, intervalo
Limpeza	Manual (fácil de esquecer, vai para produção)	Um comando — ou expiração automática
Dados sensíveis	Segredos podem vazar via saída de log	Variáveis com nomes sensíveis bloqueadas por padrão; blacklist + whitelist configuráveis em `detrix.toml`

¹ Incorpore detrix.init() uma vez para zero reinícios para sempre. Ou reinicie uma vez para anexar o depurador (--debugpy, dlv, lldb-dap) — a partir daí, o agente adiciona e remove observações sem mais reinícios.

Início Rápido

Experimente em 2 minutos. Seu agente cuida de tudo após o passo 3.

1. Instale o 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 a partir do código-fonte:

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

Em seguida, inicialize (cria a configuração e configura o armazenamento local):

detrix init

2. Adicione ao seu aplicativo

Uma linha — o depurador fica em espera até seu agente precisar dele, zero sobrecarga quando ocioso:

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

Go e Rust funcionam da mesma forma — veja Integração de Aplicativos.

3. Conecte seu agente

Claude Code:

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

Cursor / Windsurf — adicione ao .mcp.json na raiz do seu projeto:

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

Para configuração em nuvem e outros editores, veja o guia de configuração.

É isso. Peça ao seu agente para observar qualquer linha no seu aplicativo em execução — sem reinícios, nada vai para produção.

Alternativa: conectar sem incorporar

Não quer adicionar uma dependência? Inicie seu aplicativo diretamente sob um 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

Escuta em 127.0.0.1 — apenas local. Veja o guia de configuração de linguagem para remoto e Docker.

Como Funciona

Detrix é um daemon que roda localmente ou na nuvem e conecta seu agente de IA a qualquer processo em execução via 29 ferramentas MCP. Internamente, ele se comunica com o depurador do seu aplicativo via Debug Adapter Protocol (DAP). Ele define logpoints — breakpoints que avaliam uma expressão e registram o resultado em vez de pausar. Seu aplicativo roda em velocidade total; Detrix captura os 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.                   │

O daemon roda localmente ou junto ao seu serviço em Docker — mesmo protocolo em ambos os casos. No modo nuvem, os arquivos-fonte são buscados automaticamente para que o agente encontre as linhas certas sem que estejam na sua máquina. Veja o Guia de Instalação para configuração em nuvem.

Integração de Aplicativos

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

Linguagem	Instalação	Documentação
Python	`pip install detrix-py`	Cliente Python
Go	`go get github.com/flashus/detrix/clients/go`	Cliente Go
Rust	`detrix-rs = "1.2.0"` no Cargo.toml	Cliente Rust

Padrão de produção: Crie uma instância do serviço com símbolos de depuração e um cliente Detrix. Roteie tráfego suspeito para ela via Kafka, sidecar ou seu balanceador de carga. O restante da sua frota roda sem impacto — velocidade total, sem sobrecarga de instrumentação. Você obtém observabilidade profunda em uma instância sem tocar na produção.

Veja o Manual de Clientes para documentação completa.

Configuração de Build para Observabilidade

Detrix usa logpoints do depurador para observar variáveis. Para que as expressões sejam avaliadas com sucesso, o binário precisa de símbolos de depuração (informação DWARF). A boa notícia: você não precisa de um build de depuração. Cada linguagem tem uma estratégia amigável à produção que preserva a maior parte da visibilidade de variáveis com impacto mínimo de desempenho.

Go

O go build padrão do Go já produz um binário otimizado com símbolos de depuração DWARF. Delve anexa-se a ele e avalia expressões de logpoint na maioria das variáveis — especialmente campos de struct alocados no heap. Nenhuma flag especial é necessária.

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

Se o otimizador ocultar uma variável local específica (<optimized out>), use flags de depuração por pacote para desabilitar otimizações apenas onde você precisa de visibilidade:

# 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

Build	Desempenho	Visibilidade de variáveis
`go build` (padrão)	Velocidade total	Alta — campos de struct, maioria dos locais
`go build -gcflags="pkg=-N -l"`	Um pacote mais lento	~100% nesse pacote
`go build -gcflags="all=-N -l"`	Todos os pacotes mais lentos	100% em todo lugar (apenas dev)

Remover símbolos (-ldflags="-s -w") elimina a informação DWARF e torna a depuração impossível. Se você remover símbolos para produção, mantenha uma instância com símbolos para Detrix.

Rust

Builds de depuração do Rust (cargo build) são 10-100x mais lentos que release — inutilizáveis em produção. Em vez disso, use um perfil Cargo personalizado que compila suas dependências com otimização total (O3) e seu código em um nível mais baixo (O1) que preserva a maior parte da visibilidade de variáveis:

# 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	Seu código	Dependências	Desempenho vs release	Visibilidade de variáveis
`release`	O3, sem debug	O3, sem debug	Linha de base	Não é possível observar
`release` + `debug = 2`	O3, DWARF	O3, sem debug	~0-2% de sobrecarga	Baixa — muitos locais otimizados
`detrix` (recomendado)	O1, DWARF	O3, sem debug	~5-15% de sobrecarga	Alta — maioria das variáveis visíveis
`dev` (debug)	O0, DWARF	O0, DWARF	10-100x mais lento	100% (apenas dev)

Ressalva sobre genéricos: Código genérico de dependências (serde, tokio, axum) é monomorfizado no seu crate e compilado no seu nível de otimização (O1), não no da dependência (O3). Para a maioria dos serviços isso é desprezível, já que I/O domina, mas caminhos críticos com muita serialização podem ver um impacto maior.

Para funções que você quer manter totalmente visíveis independentemente da otimização:

#[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

Nenhuma configuração especial de build é necessária. CPython é sempre depurável — debugpy anexa-se ao interpretador em execução como está.

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

Veja o Manual de Clientes para documentação completa.

Recursos

Sem alterações de código. O agente instrumenta seu código em execução via pontos de observação — nada é commitado, nada vai para produção.

Sem pausas. Pontos de observação avaliam expressões em velocidade total de execução, sem interrupção estilo breakpoint. Para caminhos de código de alta frequência, use modos de amostragem ou throttle para controlar o volume de eventos.

Sem limpeza esquecida. Métricas expiram automaticamente via TTL, ou remova tudo com um comando.


Ferramentas do agente	29 ferramentas MCP — observe qualquer linha, consulte eventos, habilite/desabilite grupos de observação e faça limpeza; sem necessidade de número de linha
Instrumentação sem downtime	Adicione métricas sem reiniciar seu aplicativo
Captura multi-variável	Capture múltiplas variáveis por ponto de observação
Modos de captura	Stream, amostragem, throttle, primeira ocorrência, amostragem periódica (a cada N seg)
Introspecção em tempo de execução	Stack traces, snapshots de memória, inspeção de variáveis, avaliação de expressões
Multi-linguagem	Python (debugpy), Go (delve), Rust (lldb-dap)
Depuração em nuvem	Observe contêineres Docker e hosts remotos — sem VPN, sem encaminhamento de porta
Armazenamento durável	Eventos armazenados em SQLite no host do daemon. Rode Detrix em um servidor remoto, conecte seu agente pela manhã e pergunte o que aconteceu durante a noite. O daemon reconecta-se automaticamente ao adaptador de depuração se ele reiniciar.
Extensível	Novos frontends via API aberta; novo suporte a linguagens implementando um adaptador de linguagem — Adicionando Linguagens
Validação de segurança	Nomes de variáveis sensíveis (`password`, `api_key`, `token`, `secret`, `private_key`, etc.) bloqueados antes da captura. Blacklist + whitelist configuráveis para nomes de variáveis e funções em `detrix.toml`. Ative o modo seguro por conexão para permitir apenas observação de variáveis — sem execução de expressões, sem stack traces, sem snapshots de memória. Operações bloqueadas retornam um erro nomeado claro para que o agente possa explicar a restrição.
Autenticação	Controle de acesso multi-tenant: tokens estáticos por usuário ou JWT/JWKS, autorização baseada em papéis (Admin/User), isolamento de métricas por agente — Guia de Autenticação
Streaming de eventos	Encaminhe eventos capturados para Graylog
4 protocolos de API	MCP (stdio), gRPC, REST, WebSocket

Documentação


Guia de Instalação	Instalação, configuração de linguagem, configuração do agente, depuração em nuvem
Modo Agente Autônomo	Observação centralizada Linux/Go/eBPF com agentes autenticados
Autenticação	Modos de autenticação, tokens por usuário, JWT/JWKS, controle de acesso
Referência da CLI	Interface de linha de comando
Manual de Clientes	Bibliotecas de cliente Python, Go, Rust
Arquitetura	Clean Architecture com 13 crates Rust
Adicionando Linguagens	Estenda Detrix para novas linguagens

Contribuindo

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

Faça um fork do repositório
Crie um branch de funcionalidade
Execute as verificações acima
Envie um Pull Request

Licença

Licença MIT — veja LICENSE.

Encontrou um bug? Abra uma issue. Encontrou em minutos o que levava dias? Conte-nos nas Discussões.