LogSage

장애 원인 탐지 및 순위 매기기

LogSage는 로그에서 의미 있는 신호를 추출하고, OutOfMemory, CrashLoopBackOff, ImagePullBackOff, ConnectionRefused, DNSFailure, TLSFailure, MissingEnvVar, PermissionDenied, DiskFull, DependencyTimeout, Panic, PortBindingFailure 등 12가지 알려진 장애 클래스와 매칭합니다. 각 후보 원인에 대해 신뢰도(높음/중간/낮음)를 계산하고 순위를 매겨 가장 가능성 높은 원인을 먼저 보여줍니다.

증거 및 권장 디버깅 단계 제공

탐지된 각 원인에 대해 LogSage는 해당 원인을 뒷받침하는 구체적인 증거(예: 종료 코드 137, OOMKilled 이유)를 나열하고, 문제 해결을 위한 권장 조치를 제시합니다. 예를 들어, 메모리 한도 확인 또는 증가를 위한 kubectl 명령어를 제안합니다.

다양한 출력 형식 지원

기본 분석 외에도 LogSage는 machine-readable JSON 출력(–json), 간결한 클래스와 신뢰도만 출력(–quiet), 상위 N개 결과만 제한(–top 3)하는 플래그를 제공합니다. 이는 스크립트 자동화나 CI 파이프라인 통합에 유용합니다.

Windows 사용자를 위한 설치 방법

Windows에서 LogSage를 설치하려면 공식 릴리스 페이지에서 logsage_1.0.1_windows_amd64.zip 파일을 다운로드합니다. 다운로드 후 압축을 해제하고, logsage.exe 파일을 PATH에 포함된 폴더(예: %USERPROFILE%bin)로 이동시킵니다. 그런 다음 명령 프롬프트나 PowerShell에서 logsage.exe version을 실행하여 설치를 확인할 수 있습니다.

Scoop을 통한 설치 (권장)

Scoop 패키지 관리자를 사용하는 경우, 다음 명령어로 LogSage 저장소를 추가하고 설치할 수 있습니다:
scoop bucket add logsage https://github.com/UreaLaden/scoop-logsage
scoop install logsage
설치 후 logsage version로 버전을 확인할 수 있습니다.

Chocolatey를 통한 로컬 설치

Chocolatey를 사용하는 경우, 로컬 패키지 소스를 지정하여 설치할 수 있습니다:
choco install logsage --source pathtochocolatey-logsage
참고: 이 Chocolatey 패키지는 커뮤니티 피드에 게시되지 않았으며, UreaLaden/chocolatey-logsage에서 유지 관리됩니다.

로그 파일 분석

로그 파일을 분석하려면 다음 명령을 실행합니다:
logsage analyze server.log
이 명령은 server.log 파일을 읽고 장애 원인을 분석하여 결과를 출력합니다.

표준 입력으로부터 로그 분석

파이프를 통해 로그를 전달하여 분석할 수 있습니다. 예를 들어, Kubernetes pod의 로그를 실시간으로 분석하려면:
kubectl logs my-pod | logsage analyze --stdin
이 방식은 로그를 파일에 저장하지 않고 바로 분석하고자 할 때 유용합니다.

CI 로그 분석 (요약 모드)

CI 시스템의 빌드 로그를 간결하게 분석하려면 --ci-summary 플래그를 사용합니다:
logsage ci --ci-summary build.log
이 모드는 CI 주석이나 풀 리퀘스트 댓글에 적합한 간결한 텍스트 출력을 생성하며, JSON이나 조용한 모드와 동시에 사용할 수 없습니다.

Kubernetes pod 로그 직접 분석

LogSage는 Kubernetes 클러스터에서 실행 중인 pod의 로그와 설명 정보를 가져와 통합 분석할 수 있습니다:
logsage k8s pod my-pod --namespace production
이 명령은 kubectl logs와 kubectl describe pod의 출력을 모두 가져와 하나의 입력으로 분석하여 더 정확한 진단을 제공합니다.

이런 경우에 유용합니다

프로덕션 서비스에서 장애가 발생했을 때, 수천 줄의 로그를 수동으로 뒤지지 않고 신속히 원인을 파악해야 하는 경우 LogSage가 유용합니다. 특히 Kubernetes 환경에서 실행 중인 서비스의 장애를 진단하는 DevOps 엔지니어나 SRE가 로그 분석 시간을 줄이고, 정확한 증거 기반의 조치를 빠르게 내릴 때 도움이 됩니다. CI 파이프라인에서 빌드 실패 원인을 자동으로 분석하여 풀 리퀘스트에 코멘트로 달고자 하는 개발팀에도 적합합니다.

지원 환경·시스템 요구사항

LogSage는 Windows, Linux, macOS에서 실행 가능한 사전 빌드된 바이너리를 제공합니다. Windows에서는 windows_amd64 아키텍처용 ZIP 파일을 통해 logsage.exe를 실행할 수 있습니다. 별도의 런타임 의존성 없이 실행 가능한 단일 실행 파일로 제공되며, Go로 컴파일되어 추가적인 라이브러리 설치가 필요하지 않습니다.

최신 버전·업데이트

현재 버전은 1.0.1이며, 공식 GitHub 저장소의 releases 페이지에서 최신 버전과 업데이트 내역을 확인할 수 있습니다. 버전 업데이트는 주로 장애 탐지 정확도 향상, 새로운 로그 형식 지원, 성능 개선 등을 포함합니다.

제한 사항·확인 사항

LogSage는 사전 정의된 12가지 장애 클래스에 대해서만 원인을 탐지할 수 있습니다. 해당 클래스에 해당하지 않는 새로운 또는 비정상적인 장애 패턴은 탐지하지 못할 수 있으며, 이 경우 원인 탐지 결과가 나오지 않거나 낮은 신뢰도로 표시될 수 있습니다. 또한, 로그 형식이 일반 텍스트, JSON, logfmt 중 하나가 아닌 경우 정상적으로 파싱되지 않을 수 있습니다.