GitLab Orbit 및 AI를 사용하여 몇 초 만에 운영 장애의 근본 원인 찾기

새벽 2시입니다. 휴대폰이 울립니다. 운영 환경(Production)이 다운되었고, 결제 서비스(checkout service)가 500 에러를 내뱉고 있으며, 팀원들은 허둥지둥 움직이고 있습니다.

장애(incident) 내용을 확인하는 순간, 진짜 고통이 시작됩니다. 최근 어떤 머지 리퀘스트(merge request)가 이를 망가뜨렸을까요? 결제 서비스였을까요? 할당량(quota) 로직이었을까요? 아니면 파이프라인(pipeline) 설정 문제였을까요? 매출이 줄어드는 동안 당신은 GitLab 이슈(issues), 파일 차이(diffs), CI/CD 로그, 그리고 배포 이력(deployment histories) 사이를 수동으로 오가며 뛰어다닙니다.

이것이 운영 장애의 숨겨진 비용입니다. 무엇을 수정해야 할지 알기도 전에 수 시간 동안 수동으로 포렌식 고고학(forensic archaeology)을 수행해야 한다는 점입니다.

GitLab Transcend Hackathon을 위해, 저는 바로 이 문제를 해결하고 싶었습니다. 저는 Incident Root Cause Flow를 구축했습니다. 이는 GitLab의 Orbit 지식 그래프(knowledge graph)를 네이티브하게 탐색하여 몇 초 만에 원인이 된 커밋(commit)을 찾아내는 오픈 소스 기반의 AI 지원 에이전트(AI-powered agent)입니다.

이것이 어떻게 작동하는지, 어떻게 그래프 탐색(graph traversal)을 활용하는지, 그리고 어떻게 여러분의 GitLab 프로젝트에 설치할 수 있는지 설명하겠습니다.

개념: SDLC 그래프 탐색

이 플로우(flow)는 전적으로 GitLab Duo Agent Platform을 기반으로 구축되었으며 GitLab Orbit에 의해 구동됩니다.

Orbit은 코드 구조(정의, 참조, 호출 그래프(call graphs))를 매핑하고 이를 SDLC 객체(이슈, 머지 리퀘스트, 파이프라인, 배포)와 연결하는 지식 그래프(knowledge graph)입니다. 모든 것이 연결되어 있기 때문에, 우리는 실패를 역추적할 수 있습니다.

새로운 장애(Incident)가 생성되면, 에이전트가 깨어나 다음과 같은 정밀한 탐색 경로를 실행합니다:

1. 후보 찾기(Find Candidates): 그래프를 쿼리하여 최근에 머지된 모든 MR을 찾습니다.
2. 차이점 검사(Inspect Diffs): 각 MR에 대해 변경된 파일을 찾습니다.
3. 코드 매핑(Map the Code): 변경된 특정 함수/정의를 추출합니다.
4. 영향 범위 추적(Trace the Blast Radius): CALLS 엣지(edge)를 따라가 변경된 코드에 의존하는 정확한 다운스트림(downstream) 함수를 찾습니다.
5. CI/CD 교차 참조(Cross-Reference CI/CD): HAS_HEAD_PIPELINE 엣지가 코드가 머지되기 전 실패한 테스트 실행을 나타내는지 확인합니다.

에이전트는 이 그래프 증거를 기반으로 각 MR (Merge Request)에 점수를 매기고, 신뢰도 등급(confidence rating)과 장애를 일으킨 정확한 호출 체인(call-chain)을 포함하여 아름답게 포맷팅된 Markdown 댓글을 인시던트(incident)에 직접 게시합니다.

Incident → Project → MergeRequest (failed pipeline?) → MergeRequestDiffFile → File → Definition ←[CALLS]← callers

무작정 파헤치는 대신, 온콜(on-call) 엔지니어는 30초 이내에 신뢰도 점수가 매겨진 분석 결과와 유력한 원인에 대한 직접적인 링크를 받게 됩니다.

Flow 설치 방법

이것은 네이티브 GitLab Duo Flow이기 때문에 호스팅할 외부 서버, 웹훅(webhook) 또는 Python 스크립트가 필요하지 않습니다. GitLab 환경 내부에서 안전하게 실행됩니다.

1. GitLab 프로젝트로 이동합니다.
2. AI → Flows로 이동합니다 (또는 AI Catalog를 검색합니다).
3. New flow를 클릭합니다.
4. Incident Root Cause Analyzer와 같은 이름을 지정합니다.
5. 오픈 소스 리포지토리에서 config.yaml을 가져와 YAML 구성 편집기에 붙여넣습니다.
6. Save를 클릭합니다.

참고: YAML은 {{project_id}}를 사용하여 프로젝트 ID를 동적으로 주입하므로, 별도의 설정 없이 즉시 사용 가능한 완전한 휴대성을 갖추고 있습니다.

사용 방법 (트리거 연결하기)

Flow가 저장되면, GitLab에 이 Flow를 언제 실행할지 알려주어야 합니다. 우리는 프로덕션 이슈(production issue)가 기록되는 즉시 이 에이전트가 자동으로 작동하기를 원합니다.

1. 여전히 Flows 인터페이스 내에서, Managed 탭으로 전환합니다.
2. 새로 만든 Flow를 찾아 Enable을 클릭합니다.
3. Add triggers 섹션 아래에서 **Work item (Created)**을 선택합니다.
4. 대상(target)으로 프로젝트가 선택되어 있는지 확인합니다.

자동화 테스트하기

실제로 작동하는지 확인하려면:

1. Plan → Issues → New Issue로 이동합니다.
2. Type 드롭다운을 Incident로 변경합니다.
3. checkout-service returning 500s와 같이 현실적인 제목을 입력하고 제출합니다.

약 30초 정도 기다린 후 페이지를 새로고침하면, 에이전트가 장애를 일으킨 정확한 MR과 코드 정의(code definitions)를 격리하여 완전한 근본 원인 분석 내용을 댓글로 게시했을 것입니다.

다음 단계는?

평균 복구 시간 (MTTR)이 인간의 문맥 전환 (context-switching)으로 인해 병목 현상이 발생할 필요는 없습니다. LLM 추론 (reasoning)을 Orbit을 통한 엄격하고 결정론적인 그래프 탐색 (graph traversal)과 결합함으로써, 장애 분류 (incident triage) 과정에서의 추측을 제거할 수 있습니다.

전체 소스 코드, 데모 애플리케이션, 그리고 프롬프트 엔지니어링 (prompt engineering)은 여기 GitLab 저장소에서 확인하실 수 있습니다.

즐거운 해킹 되시길 바라며, 여러분의 온콜 (on-call) 근무가 평온하기를 바랍니다!