OmniTrace가 파이썬 오류를 감지해 로컬에서 수정안을 만든다

OmniTrace는 파이썬 프로그램의 로그에서 런타임 오류를 찾아 로컬에서 실행하는 언어 모델로 원인을 분석하고, 검토와 승인을 거친 뒤 소스 코드 수정안을 적용하는 오픈소스 디버깅 도구다. 제작자는 클라우드 AI API를 사용하지 않는 로컬 중심 작업 흐름을 제시하지만, 정규식 기반 수정은 파이썬 문법을 이해하지 못하므로 변경 사항을 직접 검토하고 테스트해야 한다고 경고한다.

OmniTrace 저장소에는 기능 소개와 사용 절차, 안전상 주의점, 개발 계획이 담겨 있다. 이 도구는 로그 파일 감시, Ollama를 통한 로컬 진단, 수정 전 승인과 백업, SQLite 기록 저장, Flask 대시보드를 제공하는 것으로 소개된다.

기능과 동작 방식

감시 모드에서는 지정한 로그 파일을 확인해 지원되는 파이썬 트레이스백을 발견하면 관련 오류 정보를 추출하고 진단 절차를 시작한다. 예를 들어 다음 명령으로 app.log를 감시한다.

omnitrace --watch app.log

OmniTrace는 Ollama를 통해 선택한 로컬 모델에 진단 맥락을 보내며, 저장소는 Llama 3를 사용 예로 든다. 모델은 오류 설명과 제안 수정안을 생성한다. 제작자는 로컬 Ollama를 사용하면 호스팅 AI API로 디버깅 정보를 보낼 필요가 없다고 설명한다.

수정 기능은 제안된 변경을 개발자에게 보여주고 승인을 요청한다. 승인된 경우 소스 파일을 바꾸기 전에 .bak 백업을 만든다. 제안된 수정은 정규식 기반이어서 의도하지 않은 텍스트를 바꾸거나 유효하지 않은 파이썬 코드를 만들 수 있다. 따라서 적용 전 변경 내용과 대상 파일을 확인하고, 적용 후 관련 코드를 테스트해야 한다. AI가 만든 수정이 정확하다는 보장은 없다.

기록은 SQLite에 저장되며, 과거 오류와 진단을 살펴보는 로컬 웹 대시보드는 Flask, HTMX, Tailwind CSS를 사용한다. 대시보드는 다음 명령으로 실행한다.

omnitrace --ui

기록된 오류와 진단을 살펴보고 반복되는 문제를 조사하는 데 쓸 수 있다. 브라우저에서 열 로컬 주소는 실행 중인 애플리케이션이 출력한다.

설치와 사용

저장소가 제시하는 준비 항목은 Python 3.9 이상, Git, Ollama, Llama 3다. 다만 저장소는 Python 3.9 이상을 자리표시자 요구사항이라고 명시하며, 공개 전 패키지가 실제로 지원하는 최소 버전을 확인하라고 적었다. Ollama를 설치하고 로컬 서비스를 실행한 다음 모델을 내려받는다.

ollama pull llama3

모델을 사용할 수 있는지 확인한다.

ollama list

설정에서 다른 Ollama 모델 식별자를 사용하는 경우에는 해당 식별자를 사용해야 한다. 저장소 복제 예시에는 실제 소유자 대신 YOUR_USERNAME이 들어 있으며, 실제 GitHub 저장소 소유자로 바꾸라고 안내한다.

git clone https://github.com/YOUR_USERNAME/omnitrace.git
cd omnitrace

가상 환경을 만들고 활성화하는 명령은 운영체제별로 다음과 같다.

python3 -m venv .venv
source .venv/bin/activate

python -m venv .venv
.venv\Scripts\Activate.ps1

프로젝트와 의존성을 설치하고 CLI를 확인한다.

pip install -e .
omnitrace --help

명령을 찾을 수 없다면 패키징 설정에 적절한 콘솔 스크립트 진입점이 정의돼 있는지 확인하라고 저장소는 안내한다. 감시 기능을 쓸 때는 애플리케이션이 트레이스백을 app.log에 기록해야 한다.

omnitrace --watch app.log

대시보드를 실행하거나 OmniTrace가 만든 백업에서 파일을 복구할 때는 다음 명령을 사용한다.

omnitrace --ui

omnitrace revert path/to/file.py

복구 동작은 실제 구현 방식에 따른다. 저장소는 자동 수정 전에 Git 작업 트리를 깨끗하게 유지하고 중요한 변경 사항을 커밋하라고 권한다. 백업은 복구를 돕지만 버전 관리의 대체재는 아니다.

안전과 개인정보

로컬 추론을 사용하면 AI 분석 단계에서 소스 코드를 호스팅 AI API로 보낼 필요가 없지만, 이것만으로 개인정보 보호가 보장되지는 않는다. 애플리케이션 설정, 로그, 네트워크 설정과 다른 연동 요소도 영향을 준다. 로그에 자격 증명, API 키, 액세스 토큰 등 민감한 값을 기록하지 말아야 한다.

정규식 기반 소스 코드 변경은 파이썬의 구문 트리나 프로그램 의미를 이해하지 못한다. 제안된 수정 내용을 검토하고, 의도한 파일과 텍스트가 바뀌는지 확인하며, 버전 관리 시점을 남기고, 변경 후 관련 테스트를 실행해야 한다. 예상하지 못한 동작이 생기면 수정 내용을 되돌려야 한다.

.bak 파일은 이전 소스 내용을 복구하는 데 유용하지만 작업의 원자성, 동시 편집 내용의 보존, 모든 실패 상황에서의 안전한 롤백을 보장하지 않는다. 중요한 코드에는 Git과 적절한 테스트를 함께 사용하라고 저장소는 설명한다.

구성 요소와 개발 계획

저장소가 제시한 구성은 다음과 같다.

제시된 처리 흐름은 로그 감시와 트레이스백 식별, 오류 맥락 추출, Ollama를 통한 로컬 모델 호출, 진단 및 수정안 생성, 사람의 승인과 패치 적용, SQLite 기록 저장과 대시보드 조회 순이다. 저장소는 이를 개념적 구조로 설명하며, 실제 구현과 구성 요소의 경계 및 데이터 흐름을 일치시켜야 한다고 덧붙인다.

OmniTrace v1.0은 오류 감지, 로컬 AI 진단 요청, 패치 제안, 디버깅 기록 보존을 핵심 흐름으로 제시한다. 향후 계획에는 여러 파일의 코드와 디버깅 맥락을 검색하는 RAG, Discord 웹훅 알림과 알림 속도 제한, 패치 검증과 선택적 구문 검사 및 표적 테스트 실행, 정규식 대신 구문을 고려하는 패치 방식 탐색, 기록 검색·필터 개선, 로컬 Ollama 모델 선택 설정, 민감 정보 노출을 줄이면서 진단 맥락을 확장하는 작업이 포함된다. 이는 계획된 기능이며 현재 제공된다고 명시된 기능과 구분해야 한다.

저장소는 오픈소스 프로젝트로 소개하며, MIT 라이선스로 공개할 예정이라고 적었다. 다만 실제 MIT 라이선스 파일을 저장소에 추가하기 전에는 해당 라이선스 주장을 게시하지 말라고 안내한다. LICENSE 파일에서 라이선스 전문을 확인할 수 있다.