🚀 debug2ai

Trợ lý Debug AI đa ngôn ngữ — Tự động gom toàn bộ Runtime Context (Frontend → Backend → DB) thành prompt chuẩn cho AI. Hỗ trợ Java, Node.js, Python, Go, PHP. Mỗi ngôn ngữ là một agent độc lập, cấu hình bằng 1 dòng lệnh.

😩 Vấn đề

Khi app lỗi, quy trình debug thông thường tốn rất nhiều thời gian:

Mở DevTools trình duyệt → copy Network log, Console error
SSH vào server → tìm dòng exception trong backend log
Kết nối database → kiểm tra query nào bị slow hoặc fail
Tự tay ghép tất cả lại thành một đoạn text mạch lạc
Paste vào ChatGPT/Claude → AI vẫn trả lời chung chung vì thiếu context

→ 15–30 phút chỉ để chuẩn bị câu hỏi, chưa kể AI thường bịa code sai vì không thấy dữ liệu thực tế.

Vấn đề nhân lên gấp bội với Microservices: log nằm ở 5–10 service khác nhau, không biết request đi qua đâu, chết ở đâu.

💡 Giải pháp

debug2ai là một daemon nhẹ viết bằng Go, hoạt động như một OpenTelemetry Collector tối giản kết hợp AI Prompt Generator.

Kiến trúc modular: mỗi ngôn ngữ backend có một Agent folder riêng chứa script cấu hình và wrapper. Chỉ cần chỉ định ngôn ngữ trong file config — tool tự biết cách thu thập đúng loại trace.

Chỉ 1 click → Prompt hoàn chỉnh gồm:
  🖱️  Hành vi user trên Frontend (click nào, API nào)
  🌐  HTTP request/response đầy đủ (headers, body, status)
  ⚙️  Flame Graph thực thi Backend (lỗi ở class nào, dòng nào)
  🗄️  Câu SQL thực tế đã chạy (detect N+1, Deadlock)
  🐰  Async job (RabbitMQ / Kafka) nếu có
  🛡️  Tự động ẩn JWT, password, email nhạy cảm

🗂️ Cấu trúc Project

debug2ai/
│
├── cmd/
│   └── debug2ai/
│       └── main.go          # Entry point — khởi động daemon
│
├── internal/                # Go packages (chỉ dùng nội bộ)
│   ├── config/
│   │   └── config.go        # Load config.yaml + env overrides
│   ├── store/
│   │   └── store.go         # In-memory trace store (TTL, max cap)
│   ├── sanitizer/
│   │   └── sanitizer.go     # Redact JWT, email, sensitive fields
│   ├── otel/
│   │   └── handler.go       # OTLP HTTP protobuf handler
│   ├── prompt/
│   │   └── generator.go     # Build E2E debug prompt từ trace
│   └── mcp/
│       └── server.go        # MCP server + 4 tools
│
├── agents/                  # 📦 Agent cho từng ngôn ngữ backend
│   ├── java/
│   │   ├── README.md        # Hướng dẫn tích hợp Java
│   │   ├── run.sh           # Script khởi động kèm OTel agent
│   │   ├── run.bat          # Script cho Windows
│   │   └── otel-config.yaml # Cấu hình OTel cho Java
│   │
│   ├── nodejs/
│   │   ├── README.md
│   │   ├── setup.sh         # Cài @opentelemetry/auto-instrumentations-node
│   │   ├── otel-init.js     # File khởi tạo OTel Provider
│   │   └── package.patch.json
│   │
│   ├── python/
│   │   ├── README.md
│   │   ├── setup.sh         # Cài opentelemetry-distro + bootstrap
│   │   ├── run.sh           # Wrapper dùng opentelemetry-instrument
│   │   └── requirements.otel.txt
│   │
│   ├── go/
│   │   ├── README.md
│   │   ├── otel_provider.go # Code mẫu khởi tạo OTel Provider
│   │   └── middleware/      # Middleware cho Gin / Fiber / Chi
│   │       ├── gin.go
│   │       ├── fiber.go
│   │       └── chi.go
│   │
│   └── php/
│       ├── README.md
│       ├── setup.sh
│       └── otel-config.ini
│
├── sdk/
│   └── frontend/
│       └── trace2prompt.js  # Script nhúng vào Frontend
│
├── static/                  # Web UI (localhost:4319)
│   └── index.html
│
├── config.yaml              # Cấu hình chính
├── Dockerfile
├── docker-compose.yaml
├── .env.example
└── README.md                # File này

🗺️ Kiến trúc hoạt động

sequenceDiagram
    actor Dev as Developer
    participant FE as Frontend<br/>(trace2prompt.js)
    participant BE as Backend<br/>(Agent tương ứng)
    participant DB as Database / Queue
    participant Core as debug2ai Core<br/>(localhost:4318)
    participant UI as Web UI<br/>(localhost:4319)
    participant AI as AI<br/>(Claude / ChatGPT)

    Dev->>FE: 1. Thao tác (VD: bấm "Thanh toán")

    rect rgba(100,100,200,0.1)
        Note over FE,Core: Thu thập ngầm — không ảnh hưởng app
        FE->>BE: 2. Gọi API (tự gắn TraceID)
        BE->>DB: 3. Query SQL / Publish event
        DB-->>BE: 4. Lỗi (Exception / Timeout / Deadlock)
        BE-->>FE: 5. HTTP 500

        FE-->>Core: 6. Gửi UI Journey (clicks, headers, response)
        BE-->>Core: 7. Gửi OTLP (traces, logs, flame graph)
        Core->>Core: 8. Nối E2E trace + ẩn dữ liệu nhạy cảm
    end

    alt Dùng Web UI (thủ công)
        Dev->>UI: 9a. Mở localhost:4319, bấm "Copy Prompt"
        Dev->>AI: 10a. Paste prompt → nhận fix chính xác
    else Dùng MCP (tự động)
        AI->>Core: 9b. Claude Code / Cursor tự gọi MCP tool
        AI-->>Dev: 10b. AI tự đọc context, tự đề xuất fix
    end

⚙️ Cấu hình (`config.yaml`)

# debug2ai — File cấu hình chính

server:
  otlp_port: 4318 # Port nhận trace từ Backend agent
  ui_port: 4319 # Port Web UI và Frontend SDK

# Chỉ định ngôn ngữ backend đang dùng
# Các giá trị hợp lệ: java | nodejs | python | go | php | auto
agent:
  language: java # Tool sẽ load agent tương ứng từ agents/java/

# Cấu hình bảo mật — tự động ẩn các field này trong prompt
privacy:
  redact_fields:
    - Authorization
    - Cookie
    - password
    - token
    - email
    - phone

# Giới hạn lưu trữ trace (tránh tốn RAM)
storage:
  max_traces: 100 # Giữ tối đa 100 trace gần nhất
  ttl_minutes: 60 # Xóa trace cũ hơn 60 phút

# MCP Server (cho Cursor / Claude Code)
mcp:
  enabled: true
  port: 4318

🚀 Cài đặt & Khởi chạy

Yêu cầu hệ thống

Hệ điều hành: Windows 10+, macOS 11+, Linux (Ubuntu 20.04+, Debian 11+)
RAM: tối thiểu 50MB
Không cần cài thêm runtime (binary tự đóng gói)

Cách 1 — Binary sẵn (Khuyến nghị, không cần cài gì)

Tải file tại Releases:

OS	File
Windows (64-bit)	`debug2ai-windows-amd64.exe`
macOS Intel	`debug2ai-darwin-amd64`
macOS Apple Silicon	`debug2ai-darwin-arm64`
Linux (64-bit)	`debug2ai-linux-amd64`
Linux (ARM)	`debug2ai-linux-arm64`

# Linux / macOS
chmod +x ./debug2ai-linux-amd64
./debug2ai-linux-amd64

# Windows — double-click hoặc chạy trong PowerShell
.\debug2ai-windows-amd64.exe

Cách 2 — Docker Compose (Khuyến nghị cho team)

git clone https://github.com/dev1sme/debug2ai.git
cd debug2ai

cp .env.example .env
# Chỉnh sửa .env theo môi trường của bạn

docker compose up -d

Cách 3 — Build từ source (Cần Go 1.21+)

git clone https://github.com/dev1sme/debug2ai.git
cd debug2ai

go build -o debug2ai ./cmd/debug2ai/
./debug2ai

Sau khi khởi động:

Web UI: http://localhost:4319
OTLP Receiver: http://localhost:4318
MCP Server: http://localhost:4318/mcp

🔌 Tích hợp Backend

Sau khi debug2ai đang chạy, chỉ cần kích hoạt agent tương ứng với ngôn ngữ của bạn.

Cấu hình ngôn ngữ

Mở config.yaml và set:

agent:
  language: java # đổi thành ngôn ngữ bạn dùng

Hoặc dùng biến môi trường:

AGENT_LANGUAGE=nodejs ./debug2ai

☕ Java / Spring Boot / Quarkus

Xem hướng dẫn đầy đủ tại agents/java/README.md

Tóm tắt nhanh:

# Tải OTel Java Agent
curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

# Chạy app với agent (Linux/macOS)
./agents/java/run.sh your-application.jar

# Windows
agents\java\run.bat your-application.jar

Hoặc tự thêm vào lệnh chạy:

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=my-app \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -jar your-application.jar

IntelliJ: Thêm vào Run Configuration → VM Options. VS Code: Thêm vào launch.json → vmArgs.

🟢 Node.js / NestJS / Express

Xem hướng dẫn đầy đủ tại agents/nodejs/README.md

# Setup một lần
cd agents/nodejs && ./setup.sh

# Chạy app
OTEL_SERVICE_NAME=my-app \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
node --require @opentelemetry/auto-instrumentations-node/register app.js

NestJS: Thêm otel-init.js từ agents/nodejs/ vào entry point.

// main.ts — thêm dòng này trước tất cả import khác
import "./otel-init";

🐍 Python / FastAPI / Django / Flask

Xem hướng dẫn đầy đủ tại agents/python/README.md

# Setup một lần
cd agents/python && ./setup.sh

# Chạy app
OTEL_SERVICE_NAME=my-app \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
opentelemetry-instrument python main.py

FastAPI với uvicorn:

opentelemetry-instrument uvicorn main:app --host 0.0.0.0 --port 8000

🐹 Go / Gin / Fiber / Chi

Xem hướng dẫn đầy đủ tại agents/go/README.md

Go cần khởi tạo OTel Provider trong code. Copy file mẫu:

cp agents/go/otel_provider.go ./internal/telemetry/otel_provider.go

Sau đó gọi trong main.go:

import "your-module/internal/telemetry"

func main() {
    shutdown := telemetry.InitOtelProvider("my-service")
    defer shutdown()

    // ... khởi động server như bình thường
}

Middleware sẵn cho các framework phổ biến:

// Gin
import "your-module/agents/go/middleware"
r := gin.Default()
r.Use(middleware.OtelGin())

// Fiber
app := fiber.New()
app.Use(middleware.OtelFiber())

🐘 PHP / Laravel / Symfony

Xem hướng dẫn đầy đủ tại agents/php/README.md

cd agents/php && ./setup.sh

⚛️ Frontend (Mọi framework)

Hoạt động với React, Vue, Next.js, Nuxt, Angular, Vanilla JS — bất kỳ framework nào dùng HTTP request.

Thêm vào <head> của file HTML gốc (index.html / _document.tsx / app.blade.php...):

<script type="module" src="http://localhost:4319/trace2prompt.js"></script>

SDK tự động bắt:

Mọi click của user (element, trang, thời điểm)
Mọi HTTP request (fetch / axios / XMLHttpRequest)
Console error / warning
Viewport, browser, network info

⚠️ Chỉ dùng ở môi trường development. Không nhúng vào production build.

🖥️ Sử dụng Web UI

Mở trình duyệt vào http://localhost:4319:

Danh sách trace — mỗi request là một dòng, màu đỏ = có lỗi
Click vào trace — xem chi tiết E2E từ frontend đến database
"Copy Prompt" — tạo và copy prompt hoàn chỉnh vào clipboard
Paste vào Claude/ChatGPT — AI nhận đủ context, trả lời chính xác

🤖 Tích hợp MCP (Cursor / Claude Code)

Thêm vào file cấu hình MCP của IDE:

Claude Code (~/.claude.json hoặc .mcp.json):

{
  "mcpServers": {
    "debug2ai": {
      "command": "npx",
      "args": ["-y", "debug2ai"]
    }
  }
}

Hoặc nếu chạy binary local:

{
  "mcpServers": {
    "debug2ai": {
      "command": "/path/to/debug2ai",
      "args": ["mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json): cấu hình tương tự.

Sau khi kết nối, AI tự động gọi các tool:

Tool	Mô tả
`get_latest_error_trace`	Lấy trace lỗi gần nhất
`get_trace_by_id`	Lấy trace theo TraceID cụ thể
`list_recent_traces`	Liệt kê N trace gần nhất
`get_slow_queries`	Lấy các SQL query chậm nhất

🏗️ Microservices

Với hệ thống đa service, chỉ cần:

Chạy một instance của debug2ai (có thể trên máy dev hoặc server chung)
Trỏ tất cả backend service về cùng một OTLP_ENDPOINT
Đặt tên riêng cho từng service qua OTEL_SERVICE_NAME

# Service A (Java)
OTEL_SERVICE_NAME=order-service ./agents/java/run.sh order-service.jar

# Service B (Node.js)
OTEL_SERVICE_NAME=payment-service node --require ... payment/app.js

# Service C (Python)
OTEL_SERVICE_NAME=notification-service opentelemetry-instrument python notify/main.py

debug2ai tự động nối các trace từ các service lại thành một luồng E2E dựa vào TraceID được propagate qua HTTP headers.

🛡️ Bảo mật & Privacy

Các field sau tự động bị ẩn thành [REDACTED] trước khi tạo prompt:

Authorization header (JWT, Bearer token)
Cookie (chỉ hiện key, không hiện value)
Field có tên chứa: password, token, secret, email, phone, ssn, credit

Tùy chỉnh danh sách trong config.yaml:

privacy:
  redact_fields:
    - my_custom_sensitive_field
    - internal_api_key

Dữ liệu không bao giờ rời khỏi máy của bạn. Không có server trung gian, không analytics, không telemetry về chính tool này.

📊 Output mẫu (Prompt thực tế)

Xem ví dụ prompt được tạo ra

Please analyze the system error based on the E2E Runtime Context below:

=================================================
TraceID: `abc123def456`
Service: `order-service` (Java 17 / Spring Boot 3.2)
Timestamp: 2026-04-08 14:32:15 +07:00

### 🌐 HTTP REQUEST
- Method: POST
- URL: /api/v1/orders/checkout
- Status: 500 Internal Server Error
- Duration: 3,241ms
- Auth: [BEARER TOKEN PRESENT]

### 👣 FRONTEND JOURNEY
- [14:32:10] CLICK "ĐẶT HÀNG" button at /checkout
- [14:32:11] POST /api/v1/orders/checkout → 500 (3241ms)
  - Request body: {"cartId": "cart_789", "paymentMethod": "MOMO"}
  - Response: {"error": "Internal Server Error"}

### 🛑 BACKEND EXCEPTION
java.lang.NullPointerException: Cannot invoke "String.length()" because "str" is null
  at com.example.OrderService.validateCart(OrderService.java:142)
  at com.example.OrderController.checkout(OrderController.java:67)
  ...

### ⏳ FLAME GRAPH & SQL
- [3241ms] POST /api/v1/orders/checkout
  - [12ms]  CartRepository.findById
    - [11ms] SELECT * FROM carts WHERE id = ?  ← OK
  - [3ms]   UserRepository.findByEmail
    - [2ms]  SELECT * FROM users WHERE email = ?  ← OK
  - [3226ms] PaymentService.initTransaction  ← SLOW
    - [3225ms] HTTP POST https://payment-gateway.com/init  ← TIMEOUT
=================================================

🗺️ Roadmap

Core

Core daemon (Go) — nhận OTLP HTTP, tạo prompt
In-memory trace store với TTL và max cap
Tự động redact dữ liệu nhạy cảm (JWT, email, credit card)
Web UI — xem danh sách trace, copy prompt
MCP server — 4 tools cho Cursor / Claude Code
Frontend events handler (/v1/frontend-events)
Graceful shutdown
Prometheus metrics endpoint (/metrics)

Agents

DevOps

Dockerfile (multi-stage Go build)
docker-compose.yaml
GitHub Actions CI (lint → test → build → release)
Release binaries cho Windows / macOS / Linux

Tính năng nâng cao

Export prompt ra file .md
Tích hợp trực tiếp gửi vào Claude API
Dark mode Web UI
Docker Compose template cho từng ngôn ngữ

🤝 Đóng góp

Mọi contribution đều được hoan nghênh, đặc biệt là:

Thêm agent cho ngôn ngữ mới trong agents/
Cải thiện chất lượng prompt được tạo ra
Bug report và feature request qua Issues

git clone https://github.com/[username]/debug2ai.git
cd debug2ai

git checkout -b feat/agent-ruby
# ... code ...
git commit -m "feat(agents): add Ruby on Rails agent"
git push origin feat/agent-ruby
# Tạo Pull Request

📄 License

MIT License — dùng thoải mái, kể cả thương mại.

👤 Tác giả

[dev1sme]

GitHub: @dev1sme

Nếu tool này giúp ích cho bạn, cho tôi một ⭐ nhé!

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.claude		.claude
.github/workflows		.github/workflows
agents		agents
cmd/debug2ai		cmd/debug2ai
internal		internal
sdk/frontend		sdk/frontend
static		static
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
config.yaml		config.yaml
docker-compose.local.yaml		docker-compose.local.yaml
docker-compose.yaml		docker-compose.yaml
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🚀 debug2ai

😩 Vấn đề

💡 Giải pháp

🗂️ Cấu trúc Project

🗺️ Kiến trúc hoạt động

⚙️ Cấu hình (`config.yaml`)

🚀 Cài đặt & Khởi chạy

Yêu cầu hệ thống

Cách 1 — Binary sẵn (Khuyến nghị, không cần cài gì)

Cách 2 — Docker Compose (Khuyến nghị cho team)

Cách 3 — Build từ source (Cần Go 1.21+)

🔌 Tích hợp Backend

Cấu hình ngôn ngữ

☕ Java / Spring Boot / Quarkus

🟢 Node.js / NestJS / Express

🐍 Python / FastAPI / Django / Flask

🐹 Go / Gin / Fiber / Chi

🐘 PHP / Laravel / Symfony

⚛️ Frontend (Mọi framework)

🖥️ Sử dụng Web UI

🤖 Tích hợp MCP (Cursor / Claude Code)

🏗️ Microservices

🛡️ Bảo mật & Privacy

📊 Output mẫu (Prompt thực tế)

🗺️ Roadmap

🤝 Đóng góp

📄 License

👤 Tác giả

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🚀 debug2ai

😩 Vấn đề

💡 Giải pháp

🗂️ Cấu trúc Project

🗺️ Kiến trúc hoạt động

⚙️ Cấu hình (config.yaml)

🚀 Cài đặt & Khởi chạy

Yêu cầu hệ thống

Cách 1 — Binary sẵn (Khuyến nghị, không cần cài gì)

Cách 2 — Docker Compose (Khuyến nghị cho team)

Cách 3 — Build từ source (Cần Go 1.21+)

🔌 Tích hợp Backend

Cấu hình ngôn ngữ

☕ Java / Spring Boot / Quarkus

🟢 Node.js / NestJS / Express

🐍 Python / FastAPI / Django / Flask

🐹 Go / Gin / Fiber / Chi

🐘 PHP / Laravel / Symfony

⚛️ Frontend (Mọi framework)

🖥️ Sử dụng Web UI

🤖 Tích hợp MCP (Cursor / Claude Code)

🏗️ Microservices

🛡️ Bảo mật & Privacy

📊 Output mẫu (Prompt thực tế)

🗺️ Roadmap

🤝 Đóng góp

📄 License

👤 Tác giả

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

⚙️ Cấu hình (`config.yaml`)

Packages