KO How it works

Read in English

동작 방식

toard는 개발자 머신에서 사용량을 읽고, 서버에서 사용자 귀속과 비용을 확정한 뒤 대시보드에 보여줍니다. 수집 방식이 달라도 서버 안에서는 같은 사용량 이벤트 형태로 정리됩니다.

데이터 흐름

flowchart LR
  Files["로컬 세션 파일"] --> Shim["toard shim"]
  Shim --> API["인증된 /api/v1/events"]
  API --> Pricing["정규화 · 서버 비용 계산"]
  Pricing --> PG[("Postgres")]
  Pricing --> CH[("ClickHouse — 선택")]
  PG --> Dashboard["대시보드"]
  CH --> Dashboard

Loading

1. 개발 도구가 로컬 세션 파일에 사용량을 기록합니다.
2. toard-shim이 파일을 읽고 정규화된 사용량 이벤트를 서버로 보냅니다.
3. 서버는 ingest token으로 사용자를 귀속하고 가격 정보로 비용을 계산합니다.
4. 기본 저장소인 Postgres 또는 선택한 ClickHouse 경로가 집계 결과를 대시보드에 제공합니다.

수집 방식

기본 경로는 로컬 세션 파일을 읽는 pull 수집입니다. 이는 개발 도구를 재시작하거나 별도 환경 변수를 주입하지 않아도 수집할 수 있게 설계되었습니다. OTLP push 경로는 남아 있지만 experimental 기능으로 취급합니다. provider별 수집 방식은 한 번에 하나만 활성화해 pull과 OTLP가 같은 사용량을 이중 저장하지 않도록 합니다.

신뢰 경계

사용자 귀속은 이벤트 본문이 아니라 ingest token을 기준으로 결정됩니다. shim은 사용량을 전송하지만, 비용은 서버가 계산해 확정합니다. 이 구분은 잘못된 클라이언트 값이 사용자나 비용을 바꾸지 않게 하기 위한 것입니다.

저장소 선택

Postgres는 기본 모드이며 계정, 팀, 인증 같은 메타데이터의 기준 저장소입니다. ClickHouse는 이벤트와 집계 조회 규모가 커질 때 선택할 수 있는 백엔드입니다. ClickHouse를 사용해도 메타데이터는 Postgres에 남습니다.

더 상세한 설계 계약은 KO-Architecture와 저장소의 설계 문서를 참고하세요.