이 글은 Agents of SigNoz Hackathon의 Blog 트랙에 제출하는 저의 결과물입니다. 이 해커톤의 참가자들은 AI 시스템을 관측 가능하게(observable) 만들기 위해 OpenTelemetry와 SigNoz를 사용하여 실제 애플리케이션을 계측(instrument)합니다.

GitIntel 소개

GitIntel은 Gemini 2.5 Flash를 사용하여 저장소(repository)를 평가하고 종합적인 개발자 평가를 생성하는 AI 기반 GitHub 저장소 분석기입니다. GitHub 사용자 이름과 선택된 저장소(최대 5개)가 주어지면, 아키텍처(architecture), 보안(security), 테스트(testing), 문서화(documentation), 복잡성(complexity), 엔지니어링 관행(engineering practices) 등 8가지 엔지니어링 차원에서 코드를 분석하여 저장소 수준의 통찰력과 전반적인 개발자 프로필을 구축합니다.

아이디어는 간단했습니다. GitHub 데이터와 LLM(대규모 언어 모델)을 결합하여 코드가 무엇을 하는지뿐만 아니라, 그 뒤에 있는 개발자에 대해 무엇을 말해주는지를 이해하는 것이었습니다.

관측 가능성(Observability)이 필수적이 된 이유

GitIntel이 발전함에 따라, 모든 분석은 GitHub API 요청, 비동기 파일 가져오기(asynchronous file fetching), 프롬프트 구성(prompt construction), 여러 번의 Gemini API 호출, 응답 집계(response aggregation), 그리고 보고서 생성(report generation)을 포함하는 다단계 워크플로(workflow)가 되었습니다.

사용자의 관점에서는 단지 하나의 Analyze 버튼일 뿐이었습니다.

애플리케이션의 관점에서는 분산된 파이프라인(distributed pipeline)이었습니다.

이러한 불일치는 빠르게 문제가 되었습니다.

어떤 저장소 분석은 거의 40,000개의 Gemini 토큰을 소비하는 반면, 다른 분석은 4,000개 미만으로 완료되었습니다. 엔드 투 엔드 지연 시간(end-to-end latency)은 유사해 보이는 저장소임에도 불구하고 8초에서 52초까지 다양했습니다.

제 애플리케이션 로그는 이미 유용한 정보를 제공하고 있었습니다. 총 토큰 사용량, 전체 분석 소요 시간, GitHub 속도 제한(rate-limit) 상태, 그리고 요청이 성공하거나 실패한 시점 등을 확인할 수 있었습니다.

하지만 다음과 같은 다른 많은 질문에는 답할 수 없었습니다:

• 분석 과정 중 어떤 단계에서 가장 오랜 시간이 걸렸는가?
• 어떤 Gemini 배치(batch)가 지연 시간(latency) 급증을 유발했는가?
• GitHub API 시간과 Gemini 처리 시간을 비교하면 어떠한가?
• 어떤 저장소(repository)가 토큰 사용량을 주도하고 있는가?
• 장애가 발생하기 직전에 애플리케이션은 무엇을 하고 있었는가?

저는 결과(outcomes)는 알고 있었습니다.

하지만 실행 과정의 이야기(execution story)는 알지 못했습니다.

터미널 로그는 무슨 일이 일어났는지는 알려주었습니다. 하지만 전체 파이프라인(pipeline)이 어떻게 동작했는지, 혹은 시간이 실제로 어디에서 소비되고 있는지는 보여줄 수 없었습니다. 모든 최적화 작업에는 여전히 어느 정도의 추측이 포함되어야 했습니다.

그때 저는 GitIntel에 OpenTelemetry를 적용하여 계측(instrument)하고, SigNoz를 관측성(observability) 백엔드로 사용하기로 결정했습니다.

OpenTelemetry 및 SigNoz를 활용한 GitIntel 계측 (Instrumenting)

GitIntel을 관측 가능하게 만들기 위해, 애플리케이션에 OpenTelemetry를 적용하여 계측하고 이를 셀프 호스팅(self-hosted)된 SigNoz 인스턴스에 연결했습니다.

애플리케이션을 블랙박스(black box)로 취급하는 대신, 이제 GitHub API 호출부터 Gemini 상호작용에 이르기까지 모든 요청을 엔드 투 엔드(end-to-end)로 추적(trace)할 수 있으며, 추적(traces), 메트릭(metrics), 로그(logs)를 한 곳에서 상관관계(correlating)를 분석할 수 있게 되었습니다. 그 결과 지연 시간(latency), 토큰 사용량, 실패, 재시도(retries), 그리고 전체적인 실행 흐름에 대한 완전한 가시성을 확보할 수 있었습니다.

이 글에서는 설정 방법, 계측(instrumentation) 과정, 제가 직면했던 문제점들, 관측성을 통해 발견한 통찰(insights), 그리고 Ubuntu에서 동일한 환경을 재현하는 방법을 공유하겠습니다.

프로젝트 링크

라이브 데모: GitIntel

소스 코드 (Source Code):

GitHub logo Divya4879 / Github-Analyzer

어떤 GitHub 사용자 이름이든 점수가 매겨진 개발자 프로필로 변환하세요. AI 기반의 즉각적이고 공유 가능한 서비스입니다.

GitIntel

AI 기반 GitHub 프로필 분석기입니다. 사용자 이름을 입력하고 최대 5개의 저장소(repo)를 선택하면, Gemini 2.5 Flash를 통해 심층적인 코드 평가를 받을 수 있습니다. OpenTelemetry와 SigNoz를 통해 완전한 관측성 (Observability)을 제공합니다.

라이브 데모 (Live demo): gitintel-2kh2.onrender.com

Agents of SigNoz Hackathon — 블로그 트랙을 위해 제작되었습니다.

주요 기능 (Features)

• AI 코드 평가 (AI code assessment) — 코드 품질, 아키텍처, 보안, 테스트 커버리지, 문서화, 복잡도, 엔지니어링 관행, 그리고 종합 점수 등 8가지 차원에서 각 저장소를 평가합니다.
• 개발자 프로필 (Developer profile) — 숙련도 수준(Junior → Staff), 강점, 약점 및 성장 영역을 포함한 저장소 간 교차 분석을 제공합니다.
• 나란히 비교 (Side-by-side comparison) — 두 개의 GitHub 프로필을 서로 비교할 수 있습니다.
• 다운로드 가능한 평가 카드 (Downloadable assessment card) — GitHub 프로필 사진과 모든 점수가 포함된 결과를 PNG 파일로 내보낼 수 있습니다.
• 실시간 스트리밍 (Real-time streaming) — 분석 진행 상황이 SSE를 통해 실시간으로 스트리밍되어 페이지 새로고침이 필요 없습니다.
• 완전한 관측성 (Full observability) — OpenTelemetry를 통해 추적 (Traces), 메트릭 (Metrics), 로그 (Logs)를 수집하여 SigNoz로 내보냅니다.
  • 저장소별 Gemini 토큰 사용량 추적 (gemini.tokens.total, gemini.tokens.prompt, gemini.tokens.completion…)

GitHub에서 보기

개발 환경 (Development Environment)

사전 요구 사항 (Prerequisites)

시작하기 전에 다음 사항들이 준비되었는지 확인하십시오:

• 시스템 (System): Ubuntu 24.04, Python 3.12, Docker, 그리고 Docker Compose v2.
• GitHub 개인 액세스 토큰 (GitHub Personal Access Token): https://github.com/settings/tokens를 방문하여 Classic Personal Access Token을 생성하고, repo 및 read:user 스코프 (scope)를 활성화하십시오. GitIntel은 저장소 내용과 공개 프로필 정보를 가져오기 위해 이 토큰을 사용합니다.
• Gemini API 키 (Gemini API Key): https://aistudio.google.com/apikey에서 생성하십시오. GitIntel은 빠르고 비용 효율적인 **gemini-2.5-flash**를 사용하므로 무료 티어(free tier)로도 충분합니다. 다만, 무료 할당량을 사용하는 경우 여러 개의 대규모 저장소를 연속해서 분석하는 것은 피하십시오.

계속하기 전에 환경이 올바르게 설정되었는지 확인하십시오:

python3 --version    # 3.12.x여야 함
docker --version     # 20 이상이면 괜찮음
docker compose version

만약 docker compose version 명령이 실패한다면, 레거시 버전인 **docker-compose (v1)**를 사용 중일 가능성이 높습니다. 다음 명령어로 Docker Compose v2를 설치하십시오:

sudo apt-get install docker-compose-plugin

파트 1: 포크 및 실행 (Part 1: Fork and Run)

1. GitHub에서 저장소를 포크 (fork)한 다음, 로컬에 포크한 저장소를 클론 (clone)하는 것으로 시작합니다:

   git clone https://github.com/YOUR_USERNAME/Github-Analyzer
   cd Github-Analyzer

2. 가상 환경 (virtual environment)을 생성하고 프로젝트 의존성 (dependencies)을 설치합니다:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. 다음으로, 환경 파일 (environment file)을 생성합니다:

   cp .env.example .env
   nano .env

4. GitHub 토큰, Gemini API 키, 그리고 OpenTelemetry 설정을 입력하여 업데이트합니다:

   GITHUB_TOKEN=ghp_yourtokenhere
   GEMINI_API_KEY=AIzaSy_yourkeyhere
   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
...

OTEL_EXPORTER_OTLP_ENDPOINT는 파트 2에서 설정할 SigNoz OpenTelemetry Collector를 가리킵니다. 아직 실행 중이 아니더라도 걱정하지 마십시오. 애플리케이션은 해당 설정 없이도 완벽하게 작동합니다.

5. 이제 애플리케이션을 시작합니다:

   uvicorn main:app --reload

6. **http://localhost:8000**을 열고, 아무 GitHub 사용자 이름을 입력한 뒤, 몇 개의 저장소(repository)를 선택하고 Analyze를 클릭하십시오.

그러면 저장소 점수, 개발자 프로필, 강점, 약점 및 생성된 보고서를 포함한 완전한 개발자 평가 결과를 얻게 됩니다.

이 시점에서 애플리케이션은 완전히 기능합니다.

하지만 한 가지 문제가 있습니다.

무슨 일이 백그라운드에서 일어났는지 여전히 알 수 없다는 점입니다. 터미널 로그에는 총 토큰 수와 전체 소요 시간(duration)이 표시되지만, 어떤 배치(batch)에 얼마의 비용이 들었는지, 단계별 타이밍(per-step timing)은 어떠한지, 40초 중 어느 API 호출이 30초를 차지했는지, 그리고 왜 어떤 저장소는 다른 저장소보다 5배나 더 오래 걸렸는지에 대한 정보는 없습니다.

결과는 있습니다. 하지만 '이유'는 없습니다.

애플리케이션은 결과는 제공하지만, 해답은 제공하지 않습니다.

그것이 바로 Part 2가 해결하고자 하는 문제입니다.

Part 2: SigNoz 셀프 호스팅 (Self-Hosting)

제가 SigNoz를 선택한 이유 중 하나는 이것이 오픈 소스(Open Source)이며, OpenTelemetry 네이티브(native)이고, 단 몇 분 만에 셀프 호스팅(self-hosted)이 가능하기 때문입니다. 이는 제가 GitIntel을 개발하는 동안 제3자 SaaS에 의존하지 않고도 전체 관측성 스택(observability stack)을 로컬에서 계속 실행할 수 있음을 의미했습니다.

해당 리포지토리(repo)에는 이미 pours/deployment/compose.yaml 아래에 완전한 Docker Compose 설정이 포함되어 있습니다. 이를 실행하면 GitIntel이 텔레메트리(telemetry)를 수집, 처리, 저장 및 시각화하는 데 필요한 모든 것이 시작됩니다.

1. SigNoz UI & API: 8080 포트에서 실행되며, 트레이스(traces), 메트릭(metrics), 로그(logs) 및 대시보드(dashboards)를 탐색하기 위한 웹 인터페이스를 제공합니다.
2. OpenTelemetry Collector: 4317 (gRPC) 및 4318 (HTTP)에서 대기하며, GitIntel에서 내보내는 텔레메트리를 수신합니다.
3. ClickHouse: 트레이스, 메트릭 및 로그를 저장하는 고성능 데이터베이스입니다.
4. ClickHouse Keeper: ClickHouse 클러스터의 조정(coordination)을 처리합니다.
5. Postgres: SigNoz 메타데이터 및 구성을 저장합니다.

전체 스택을 다음 명령어로 시작하십시오:

cd pours/deployment
docker compose up -d

...

ClickHouse가 초기화되는 데 약간의 시간이 필요하므로, 첫 실행에는 보통 약 60초가 소요됩니다.

모든 준비가 완료되면, **http://localhost:8080**을 여세요.

이 시점에서 SigNoz 대시보드가 로드되지만, 내용은 비어 있을 것입니다. 이는 GitIntel이 아직 아무런 텔레메트리 (Telemetry)를 내보내지 않았기 때문에 발생하는 정상적인 현상입니다.

이제 GitIntel이 OpenTelemetry Collector에 연결할 수 있도록 다시 시작하세요:

cd ../..
source venv/bin/activate
uvicorn main:app --reload

GitIntel과 SigNoz가 모두 실행 중인 상태에서, 아무 GitHub 저장소(Repository)나 분석해 보세요.

분석이 시작되자마자 GitIntel은 OpenTelemetry Collector를 통해 텔레메트리 (Telemetry)를 내보내기 시작합니다. 몇 초 이내에 SigNoz의 Services 항목 아래에 gitintel이라는 이름의 새로운 서비스가 자동으로 나타납니다.

수동 등록, 설정 또는 대시보드 생성이 전혀 필요하지 않습니다. 애플리케이션에 설정된 OpenTelemetry service.name 리소스 속성 (Resource Attribute)을 통해 서비스가 자동으로 발견됩니다.

Services → gitintel을 열면 다음과 같은 실시간 애플리케이션 상태를 즉시 확인할 수 있습니다:

[

Part 3:- 계측 (Instrumentation) 작동 원리

SigNoz가 실행 중인 상태에서 다음 단계는 GitIntel에게 어떤 텔레메트리 (Telemetry)를 수집하고 어디로 보낼지 알려주는 것입니다.

관측성 (Observability) 코드를 프로젝트 전체에 흩뿌리는 대신, 저는 모든 것을 단일 파일인 **telemetry.py**에 집중시켰습니다. 하나의 설정 함수가 트레이스 (Traces)와 메트릭 (Metrics)을 초기화한 다음, 4317 포트의 OTLP/gRPC를 사용하여 OpenTelemetry Collector로 내보냅니다.

# telemetry.py

OTLP_ENDPOINT = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
...

여기 있는 몇 줄의 코드가 대부분의 핵심적인 작업을 수행합니다.

Resource는 애플리케이션에 gitintel이라는 서비스 이름을 할당함으로써 애플리케이션의 정체성을 정의합니다. 애플리케이션에서 생성되는 모든 트레이스 (Trace), 메트릭 (Metric), 로그 (Log)는 이 메타데이터를 포함하며, 이를 통해 SigNoz는 모든 데이터를 자동으로 단일 서비스 아래에 그룹화할 수 있습니다.