FaultLens

개발자와 CI/CD를 위한 로컬 기반, 설명 가능한 로그 인시던트 진단.

잡음이 많은 애플리케이션 로그를 구조화된 인시던트, 증거 기반의 근본 원인 가설, 그리고 실행 가능한 권장 사항으로 변환합니다.

클라우드 서비스 없음. 데이터베이스 없음. 텔레메트리 없음. LLM API 없음.

🌐 언어: English | 简体中文

Go Version

CI

Release

Go Report Card

PRs Welcome

목차

• 데모
• Why FaultLens
• 기능
• 빠른 시작
• 설치
• 지원되는 로그 형식
• 진단 규칙
• 사용자 정의 규칙
• 다중 파일 분석
• GitHub Actions
• HTML 보고서
• Diff
• 작동 방식
• 아키텍처
• 예제
• 개발
• 기여
• 보안
• 로드맵
• 라이선스

🎬 데모

faultlens examples/basic/app.log

FaultLens
────────────────────────────────────────────

...

💡 Why FaultLens

로그 파일에는 이미 인시던트의 이야기가 담겨 있지만, 잡음이 많고,
구조화되어 있지 않으며,
반복되는 오류로 가득 차 있습니다. FaultLens는 이를 설명 가능한 진단으로 변환합니다:

• 로컬 우선 및 오프라인 지원 (Local-first & offline) — 모든 것이 사용자의 장치에서 실행되며, 외부로 아무것도 전송되지 않습니다.
• 설명 가능 (Explainable) — 모든 진단에는 증거(evidence), 규칙(rule), 그리고 로그 라인으로 추적 가능한 신뢰도 점수(confidence score)가 함께 제공됩니다.
• 빠름 (Fast) — 스트리밍 파이프라인을 통해 약 2 MB의 상주 힙(resident heap)만으로 500 MiB의 로그를 몇 분 만에 처리합니다.
• CI/CD 친화적 (CI/CD friendly) — 안정적인 JSON 출력과 모든 파이프라인에 통합 가능한 HTML 아티팩트를 제공합니다.
• 확장 가능 (Extensible) — YAML에서 자체 진단 규칙을 정의할 수 있으며, 소스 코드 변경이 필요 없습니다.

✨ 주요 기능 (Features)

• 🔍 9가지 로그 형식 파서 (log format parsers) — 일반 텍스트(plain text), JSON, Java/Spring Boot (스택 트레이스를 하나의 이벤트로 병합), Nginx, Apache, Python, Syslog (RFC 3164 + 5424), Docker JSON, Kubernetes; 콘텐츠 기반 자동 감지 기능을 지원합니다.
• 🧹 동적 값 정규화 (Dynamic value normalization) — IP 주소, 포트, UUID, 숫자, 타임스탬프, URL, 경로 및 헥스 ID가 안정적인 플레이스홀더로 변환되며, HTTP 상태 코드는 원래의 의미를 유지합니다.
• 🗂️ 오류 클러스터링 (Error clustering) — 동일한 오류는 SHA-256 지문(fingerprint)으로 병합되고 발생 빈도에 따라 순위가 매겨집니다.
• 📈 이상 탐지 (Anomaly detection) — 설명 가능한 기준선(explainable baseline, 평균 + z-score) 대비 분당 버킷을 비교하며, 머신러닝은 사용하지 않습니다.
• 🧠 14가지 내장 진단 규칙 (built-in diagnosis rules) — 데이터베이스, redis, OOM(Out Of Memory), 타임아웃, HTTP 5xx, 충돌(crash), 디스크 가득 참(disk full), 인증서, MQ, 연결 풀(connection pool), 네트워크 파티션, CPU 포화(CPU saturation), 느린 쿼리(slow queries), 교착 상태(deadlocks) 등입니다.
• ⚙️ YAML을 사용한 사용자 정의 규칙 (Custom rules in YAML) — Go 코드를 작성하지 않고도 진단을 확장할 수 있습니다.
• 📁 다중 파일 분석 (Multi-file analysis) — 디렉토리, glob 패턴, --exclude 옵션을 지원합니다.
• 🖥️ 보고서 형식 (Report formats) — 터미널, JSON, Markdown, SVG 타임라인이 포함된 오프라인 HTML을 제공합니다.
• 🔀 차이 분석 (Diff) — 두 번의 분석 실행(배포 전/후)을 비교할 수 있습니다.
• 🤖 GitHub Actions — CI에서 로그를 분석하고 JSON 및 HTML 아티팩트를 게시합니다.

🚀 빠른 시작 (Quick Start)

go install github.com/MangoGreenTeaz/FaultLens/cmd/faultlens@latest

faultlens app.log                # 전체 보고서 출력
...

또는 stdin으로부터 로그를 파이프합니다:

cat app.log | faultlens
docker logs some-container | faultlens incident

📦 설치 (Installation)

요구 사항: Go 1.22+
최신 버전을 설치하세요:

go install github.com/MangoGreenTeaz/FaultLens/cmd/faultlens@latest

사전 빌드된 바이너리는 Releases 페이지에서 이용 가능합니다: amd64 및 arm64용 Linux, macOS, Windows (Windows의 경우 raw .exe 파일로 제공됩니다).

또는 소스에서 빌드할 수 있습니다:

git clone https://github.com/MangoGreenTeaz/FaultLens.git
cd FaultLens
go build -o faultlens ./cmd/faultlens

확인하기:

faultlens version

📊 지원하는 로그 형식 (Supported Log Formats)

🧠 진단 규칙 (Diagnosis Rules)

증거(evidence)에 점수를 매겨 신뢰도(confidence)를 계산하는 14개의 내장 규칙이 있습니다:

⚙️ 사용자 정의 규칙 (Custom Rules)

소스 코드를 변경하지 않고 진단을 확장하세요 — YAML 형식으로 규칙을 정의합니다:

custom_rules:
  - id: database_connection_failure
    root_cause: "Database connection failure"
...

필드 (Fields):

faultlens config init       # .faultlens.yaml 생성
faultlens config show       # 병합된 유효 설정 출력
faultlens config validate   # 설정 파일 검증

설정 소스 순서 (낮음 → 높음): 내장 기본값(built-in defaults) → .faultlens.yaml (프로젝트) → ~/.config/faultlens/config.yaml (사용자) → --config <file>.

실행 가능한 예시는 examples/custom-rule을 참조하세요.

📁 다중 파일 분석 (Multi-file Analysis)

여러 로그를 하나의 인시던트(incident)로 분석합니다:

faultlens logs/ # 재귀 디렉토리 (*.log, .jsonl)
faultlens 'logs/**/.log' # glob
faultlens app.log database.log nginx.log # 명시적 파일
...

모든 파일의 이벤트가 하나의 타임라인으로 병합되어 그룹화 및 진단이 이루어지며, 각 오류 예시는 원래 출처 파일을 유지합니다.

🤖 GitHub Actions

CI에서 FaultLens를 실행하고 보고서를 아티팩트로 게시하세요:

name: FaultLens

on:
...

이 저장소는 또한 공식 통합 액션(composite action)을 제공합니다:

- uses: ./.github/actions/faultlens
  with:
    log-file: testdata/incidents/mysql-outage.log
...

이 통합 액션은 호스팅 서비스가 필요 없이 GitHub Actions 내부에서 FaultLens를 실행합니다. 전체 실행 가능한 워크플로우는 .github/workflows/ci-analysis.yml에 있습니다.

🖥️ HTML 보고서

독립적이고 오프라인으로 사용할 수 있는 인시던트 보고서를 생성하세요:

faultlens app.log --output html -o report.html

• CDN 없음, 외부 JavaScript 없음, 백엔드 없음, 네트워크 의존성 없음
• 인라인 CSS + 인라인 SVG 오류 타임라인 (이상 징후가 있는 버킷 강조)
• 섹션: 요약(summary), 타임라인(timeline), 오류 그룹(error groups), 진단(diagnosis), 증거(evidence), 권장 사항(recommendations), 출처 파일(source files)

CI 아티팩트, 인시던트 공유 및 사후 검토(postmortems)에 적합합니다.

🔀 Diff

두 분석 실행 결과를 비교하세요:

faultlens incident app.log --output json -o before.json
# ... 로그를 배포하거나 변경 ...
faultlens incident app.log --output json -o after.json
...

추가/제거/변경된 오류 그룹, 진단 변화, 신뢰도(confidence) 변화를 보여주며, 배포 회귀(deploy regressions)에 이상적입니다.

🔬 작동 방식 (How It Works)

input → parser → normalize → grouping → timeline → anomaly → diagnosis → report

1. 원본 로그 라인을 통합된 LogEvent 모델로 **파싱(Parse)**합니다.
2. 동적 값들을 **정규화(Normalize)**하여 Connection refused 10.0.0.1:3306과
   Connection refused 10.0.0.2:3306이 동일한 형태가 되도록 합니다.
3. 지문(fingerprint)별로 동일 오류들을 **그룹화(Group)**하고 개수를 계산합니다.
4. 분당 버킷을 **구축(Build)**하고 설명 가능한 기준선(explainable baseline) 대비 이상 징후 급증을 **감지(detect)**합니다.
5. 증거와 신뢰도에 따라 모든 후보 근본 원인(root cause)을 점수화하여 **진단(Diagnose)**하며, 증상(HTTP 5xx)은 결코 상위 유발 원인을 이기지 못합니다.
6. 원하는 형식으로 **보고서(Report)**를 생성합니다.

🏗️ 아키텍처 (Architecture)

input (파일 / stdin / 디렉토리 / glob)
        ↓
parser (9가지 포맷, 콘텐츠 기반 자동 감지)
...

cmd/faultlens/       CLI 진입점 (Cobra)
internal/engine/     분석 파이프라인 (input → … → diagnosis)
internal/model/      공유 데이터 모델 (LogEvent, Diagnosis, …)
...

핵심 분석 패키지들은 CLI와 독립적이므로, 향후 GitHub Actions나 API 통합에 의해 재사용될 수 있습니다. 전체 설계는 docs/architecture.md를 참조하십시오.

📂 예시 (Examples)

모든 예시는 실행 가능하며 실제 CLI에서 출력을 생성합니다:

🛠️ 개발 (Development)

go build ./...
go test ./...
go vet ./...
...

🤝 기여 (Contributing)

기여자들은 환영합니다 — 파서, 진단 규칙, 테스트 데이터(fixtures), 문서. good first contributions를 포함하여 CONTRIBUTING.md를 참조하십시오.

🔒 보안 (Security)

취약점 보고 방법은 SECURITY.md를 참조하십시오.

🗺️ 로드맵 (Roadmap)

미래 아이디어 (아직 구현되지 않음): 실시간 테일링(real-time tail), 데몬 모드, 웹 UI, 규칙 학습, 크로스 호스트 타임라인 정렬.

📄 라이선스 (License)

FaultLens는 MIT License에 따라 배포됩니다.

FaultLens에 기여하는 것은 귀하의 기여가 동일한 MIT License 하에 라이선스가 부여됨에 동의함을 의미합니다.