📊 trace-analyzer

🇰🇷 이 문서는 영문 (English) 으로도 제공됩니다.

Chrome의 Performance Trace 파일(.trace.json )을 분석하여 웹 페이지의 성능 병목 요소를 탐지하고, 핵심 문제를 요약한 리포트를 생성하는 경량 CLI 도구입니다.

---

✨ 주요 기능

기능	설명
🐢 느린 API 분석	ResourceSendRequest → ResourceReceiveResponse 구간의 소요 시간 계산
🚧 렌더링 차단 리소스 분석	로딩 시간 긴 JS/CSS 리소스 탐지
🧠 Long Task 분석	메인 스레드에서 50ms 이상 실행된 Task, EvaluateScript 등 추출
📑 분서 보고서 생성	Markdown 형식의 리포트 생성

---

🔧 설치

npm install -g trace-analyzer
# 또는 (pnpm 사용 시)
pnpm add -g trace-analyzer

📦 이 도구는 npm에서 배포 중이며, Node.js 기반 환경에서 동작합니다.

---

🚀 사용법

기본 사용

npx trace-analyzer <trace.json> [옵션]
# 또는 (pnpm 사용 시)
pnpm dlx trace-analyzer <trace.json> [옵션]

옵션 목록

옵션	설명	기본값
--top <N>	상위 N개만 출력	10
--slowapi	느린 API 요청만 분석	전체 포함
--blocking	렌더링 차단 리소스만 분석	전체 포함
--longtask	Long Task만 분석	전체 포함
--longtask <N>	Long Task 기준 시간 (ms) 설정	50
--json <N>	결과 json 파일 생성	-
--report <format>	결과 리포트 출력 (현재: md 지원)	-

사용 예시

trace-analyzer ./sample.trace.json --top 5
trace-analyzer ./sample.trace.json --longtask 80
trace-analyzer ./sample.trace.json --blocking
trace-analyzer ./sample.trace.json --json ouput.json
trace-analyzer ./sample.trace.json --report md

---

🧪 입력 파일 수집 방법

크롬 개발자 도구(DevTools)의 Performance 탭에서 성능 측정 후, 우측 상단의 Save profile...을 선택하여 .trace.json 형식으로 저장합니다. 이 파일을 입력으로 사용할 수 있습니다.

{
  "traceEvents": [
    { "name": "ResourceSendRequest", "ts": 1000, ... },
    { "name": "ResourceFinish", "ts": 9000, ... },
    { "name": "FunctionCall", "ts": 9000, "dur": 200000, ... }
  ]
}

---

📝 리포트 구성 예시

샘플 분석 리포트 보기

---

🧪 테스트

npm test

---

🛠 예정 기능

• 🧪 다양한 CLI 옵션 지원 (--filter, --json, --out 등)
• 🤖 AI 요약 기능

---

📁 디렉토리 구조

.
├── analyzers/
│   ├── extractSlowApis.ts           # 느린 API 분석기
│   ├── extractBlockingAssets.ts     # 렌더링 차단 리소스 분석기
│   └── extractLongTasks.ts          # Long Task 분석기
├── cli/
│   └── main.ts                      # CLI 실행 흐름 제어
├── utils/
│   └── generateMarkdownReport.ts    # MardDown 리포터 생성기
│   └── loadTraceFile.ts             # 공통 trace 로더
│   └── parseCliArgs.ts              # CLI 명령어 옵션 파서
├── tests/
│   ├── extractSlowApis.test.ts
│   ├── extractBlockingAssets.test.ts
│   └── extractLongTasks.test.ts     # 테스트 코드
├── sample.trace.json                # 샘플 trace.json
└── index.ts                         # CLI 진입점

---

📚 기술 스택

구분	사용 기술 / 라이브러리	설명
언어	TypeScript	정적 타입 지원으로 안정적인 CLI 도구 구현
실행 환경	Node.js	CLI 실행 및 파일 시스템, 경로 처리 등 기반 런타임 환경
CLI 도구	commander	CLI 명령어 및 옵션 파싱 처리
파일 처리	fs, path (Node 내장 모듈)	trace 파일 로딩 및 출력 파일 저장
데이터 처리	custom parser (extract*.ts 등)	traceEvents를 가공하여 성능 분석 항목 추출 (API, 리소스, Long Task 등)
테스트	Vitest	유닛 테스트를 통해 각 분석 로직의 정확도 검증
포맷 출력	Markdown/HTML string template	분석 결과를 보기 쉽게 리포트 형식으로 출력

---

👩‍💻 작성자

gomguma

PR 및 기여 환영합니다!