feat(ci): add a read-only CI metrics script for the desktop runner #12

Merged
donghyeon.kang merged 1 commits from claude/w2-ci-metrics into main 2026-11-13 10:43:35 +00:00
Owner

무엇을, 왜

CI 대기열이 8시간 넘게 쌓였는데, 왜 그런지 숫자가 없다.

  • 지금까지는 run 하나의 job 시간 합만 손으로 뽑았다.
  • 대기 시간, runner 사용률, PR 하나가 쓴 run 수, main이 빨강이던 시간은 모른다.
  • 그래서 CI를 고친 뒤 빨라진 것이 그 변경 덕인지, desktop 부하가 달랐던 탓인지 가릴 수 없다.

이 PR은 infrastructure/ci/metrics/ci_metrics.py를 더한다.

  • 읽는 것: Gitea Actions API에서 runner가 받는 repo들의 run, 그 job, 닫힌 PR.
  • 내는 것: CI 매뉴얼(design-docs ci/manual.md) 10.1절 지표 1~5를 repo·단계별 표로 낸다.
    1. 실행 시간 p50·p90
    2. 대기 시간 p50·p90
    3. runner 사용률(KST 하루 기준)
    4. PR당 run 수
    5. main 빨강 시간
  • 서버에는 아무것도 쓰지 않는다.

고른 방법과 버린 대안

결정 고른 것 버린 것과 이유
위치 runner 설정 옆 infrastructure/ci/metrics/ 템플릿 repo 안: 두 repo를 함께 봐야 사용률이 나온다. runner도 하나다
언어 Python 표준 라이브러리만 셸+jq: 백분위·날짜 계산이 길어진다. 외부 패키지: 설치가 필요하다
대기 run 단위(첫 job 시작 − run 생성) job마다 started_at − created_at: 우리 서버는 job created_at이 run 생성 시각이다. runner 하나가 job을 차례로 돌리므로, 앞 job의 실행이 뒤 job의 대기에 들어간다
인증 GITEA_TOKEN(읽기 전용), 없으면 git credential fill 토큰을 새로 만들어 저장: 이 변경으로 비밀 값이 늘어난다

우리 Gitea 1.27의 응답은 API 명세와 세 곳이 다르다. 2026-11-13에 응답을 직접 확인했고, README에 적었다.

  • run에 created_at이 없다.
  • 시작하지 않은 run·job의 started_at이 1970-01-01T00:00:00Z다.
  • run 목록에 head_branch가 없다.

위험과 영향

  • 읽기만 한다. 두 repo의 7일치를 볼 때 run마다 jobs API를 한 번 불러 30초 안팎 걸린다.
  • needs로 늦게 풀린 job이 대기열 뒤에서 기다린 시간은 지표 2에 안 보인다. 실행 시간에도 들어가지 않는다. README에 적었다.
  • 바뀌는 운영 상태는 없다. 스크립트와 문서만 더한다.

검증

명령 결과
python3 -m unittest -v test_ci_metrics(서버 없이) 11개 통과. 대기·실행·빨강 시간·사용률·PR당 run 수
ci_metrics.py --repo …backend… --repo …frontend… --since 2026-11-07 --until 2026-11-13 rc=0, 30초
desktop의 새 clone에서 bash scripts/validate/scan-platform-sensitive-source.sh --platform-only(PATH에 ~/.local/bin의 helm) rc=0, PLATFORM SENSITIVE SOURCE SCAN PASS. laptop에는 rg가 없어 돌지 않는다

첫 결과(2026-11-07~13, 주요 단계만):

repo 단계 끝난 run 실행 p50·p90(분) 대기 p50·p90(분)
백엔드 pr.yml:pull_request 26(전체 93) 12.7 · 13.6 86.5 · 206.1
백엔드 main.yml:push 11 33.2 · 40.9 35.3 · 175.1
백엔드 release.yml:workflow_dispatch 7 41.1 · 57.4 58.1 · 336.4
프론트 quality-gates.yml:pull_request 32(전체 60) 26.2 · 31.0 155.8 · 348.6
프론트 quality-gates.yml:push 13 26.1 · 41.4 108.8 · 355.9
  • PR당 run 수(p50·p90·최대): 백엔드 2 · 5 · 9(병합 21개), 프론트 1 · 2 · 10(병합 23개).
  • main 빨강:
    • 백엔드 2회, 합 7.4시간. 가장 긴 것은 run 221 → 232, 4.8시간.
    • 프론트 2회, 합 37.2시간. 가장 긴 것은 run 80 → 192, 35.6시간.
  • runner 사용률(두 repo 합): 11-12 97%, 11-13 76%(그날 끝나기 전).

리뷰어가 볼 곳

  • ci_metrics.py 머리 docstring과 README 「우리 서버가 API 명세와 다른 곳」: 지표 정의를 서버에 맞춘 부분.
  • red_episodes: 「처음 실패한 run 생성 → 다음 성공 run 끝」을 workflow별로 센다.

관련

  • design-docs ci/03-time-reduction-plan.md M-0, ci/manual.md 10절
  • 기준값 줄과 매뉴얼 10.2절 사용법 한 줄은 design-docs 쪽 PR에 넣도록 그 문서를 맡은 세션에 보냈다
## 무엇을, 왜 CI 대기열이 8시간 넘게 쌓였는데, 왜 그런지 숫자가 없다. - 지금까지는 run 하나의 job 시간 합만 손으로 뽑았다. - 대기 시간, runner 사용률, PR 하나가 쓴 run 수, main이 빨강이던 시간은 모른다. - 그래서 CI를 고친 뒤 빨라진 것이 그 변경 덕인지, desktop 부하가 달랐던 탓인지 가릴 수 없다. 이 PR은 `infrastructure/ci/metrics/ci_metrics.py`를 더한다. - 읽는 것: Gitea Actions API에서 runner가 받는 repo들의 run, 그 job, 닫힌 PR. - 내는 것: CI 매뉴얼(design-docs `ci/manual.md`) 10.1절 지표 1~5를 repo·단계별 표로 낸다. 1. 실행 시간 p50·p90 2. 대기 시간 p50·p90 3. runner 사용률(KST 하루 기준) 4. PR당 run 수 5. main 빨강 시간 - 서버에는 아무것도 쓰지 않는다. ## 고른 방법과 버린 대안 | 결정 | 고른 것 | 버린 것과 이유 | | --- | --- | --- | | 위치 | runner 설정 옆 `infrastructure/ci/metrics/` | 템플릿 repo 안: 두 repo를 함께 봐야 사용률이 나온다. runner도 하나다 | | 언어 | Python 표준 라이브러리만 | 셸+jq: 백분위·날짜 계산이 길어진다. 외부 패키지: 설치가 필요하다 | | 대기 | run 단위(첫 job 시작 − run 생성) | job마다 `started_at − created_at`: 우리 서버는 job `created_at`이 run 생성 시각이다. runner 하나가 job을 차례로 돌리므로, 앞 job의 실행이 뒤 job의 대기에 들어간다 | | 인증 | `GITEA_TOKEN`(읽기 전용), 없으면 `git credential fill` | 토큰을 새로 만들어 저장: 이 변경으로 비밀 값이 늘어난다 | 우리 Gitea 1.27의 응답은 API 명세와 세 곳이 다르다. 2026-11-13에 응답을 직접 확인했고, README에 적었다. - run에 `created_at`이 없다. - 시작하지 않은 run·job의 `started_at`이 `1970-01-01T00:00:00Z`다. - run 목록에 `head_branch`가 없다. ## 위험과 영향 - 읽기만 한다. 두 repo의 7일치를 볼 때 run마다 jobs API를 한 번 불러 30초 안팎 걸린다. - `needs`로 늦게 풀린 job이 대기열 뒤에서 기다린 시간은 지표 2에 안 보인다. 실행 시간에도 들어가지 않는다. README에 적었다. - 바뀌는 운영 상태는 없다. 스크립트와 문서만 더한다. ## 검증 | 명령 | 결과 | | --- | --- | | `python3 -m unittest -v test_ci_metrics`(서버 없이) | 11개 통과. 대기·실행·빨강 시간·사용률·PR당 run 수 | | `ci_metrics.py --repo …backend… --repo …frontend… --since 2026-11-07 --until 2026-11-13` | rc=0, 30초 | | desktop의 새 clone에서 `bash scripts/validate/scan-platform-sensitive-source.sh --platform-only`(PATH에 `~/.local/bin`의 helm) | rc=0, `PLATFORM SENSITIVE SOURCE SCAN PASS`. laptop에는 `rg`가 없어 돌지 않는다 | 첫 결과(2026-11-07~13, 주요 단계만): | repo | 단계 | 끝난 run | 실행 p50·p90(분) | 대기 p50·p90(분) | | --- | --- | --- | --- | --- | | 백엔드 | `pr.yml:pull_request` | 26(전체 93) | 12.7 · 13.6 | 86.5 · 206.1 | | 백엔드 | `main.yml:push` | 11 | 33.2 · 40.9 | 35.3 · 175.1 | | 백엔드 | `release.yml:workflow_dispatch` | 7 | 41.1 · 57.4 | 58.1 · 336.4 | | 프론트 | `quality-gates.yml:pull_request` | 32(전체 60) | 26.2 · 31.0 | 155.8 · 348.6 | | 프론트 | `quality-gates.yml:push` | 13 | 26.1 · 41.4 | 108.8 · 355.9 | - PR당 run 수(p50·p90·최대): 백엔드 2 · 5 · 9(병합 21개), 프론트 1 · 2 · 10(병합 23개). - main 빨강: - 백엔드 2회, 합 7.4시간. 가장 긴 것은 run 221 → 232, 4.8시간. - 프론트 2회, 합 37.2시간. 가장 긴 것은 run 80 → 192, 35.6시간. - runner 사용률(두 repo 합): 11-12 97%, 11-13 76%(그날 끝나기 전). ## 리뷰어가 볼 곳 - `ci_metrics.py` 머리 docstring과 README 「우리 서버가 API 명세와 다른 곳」: 지표 정의를 서버에 맞춘 부분. - `red_episodes`: 「처음 실패한 run 생성 → 다음 성공 run 끝」을 workflow별로 센다. ## 관련 - design-docs `ci/03-time-reduction-plan.md` M-0, `ci/manual.md` 10절 - 기준값 줄과 매뉴얼 10.2절 사용법 한 줄은 design-docs 쪽 PR에 넣도록 그 문서를 맡은 세션에 보냈다
donghyeon.kang added 1 commit 2026-11-13 10:41:35 +00:00
There is no number for how long CI runs wait, how busy the one runner is,
how many runs a pull request costs or how long main stays red. Run times
were added up by hand from single runs, so whether a change helped could
not be told apart from load.

infrastructure/ci/metrics/ci_metrics.py reads the Gitea Actions API (runs,
their jobs, closed pull requests) for the repositories the runner serves
and prints the CI manual's metrics 1-5 per repository and stage: run
execution p50/p90, queue wait p50/p90, runner utilisation per KST day,
pull request runs per merged pull request, and main red time. It only
reads; credentials come from GITEA_TOKEN or `git credential fill` and are
never printed.

The arithmetic follows what our Gitea 1.27 returns, which differs from the
API reference: a run has no created_at (the earliest job created_at is
used), unstarted runs and jobs report 1970-01-01 times (treated as
absent), and a job's created_at is its run's, so queue wait is measured
per run (first job start minus run creation) instead of per job.

Verification: python3 -m unittest test_ci_metrics (11 offline tests) and
one run against the server for 2026-11-07..13 (two repositories, 30 s,
rc=0). The sensitive-source scan needs rg and ran on the desktop host.

Refs: design-docs ci/03-time-reduction-plan.md M-0
donghyeon.kang merged commit d0875bfe44 into main 2026-11-13 10:43:35 +00:00
donghyeon.kang deleted branch claude/w2-ci-metrics 2026-11-13 10:43:36 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/platform-core#12