Skip to content

ApiLens v0.3.3

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 Jul 14:58
v0.3.3
5ebdd73

ApiLens v0.3.3 — 거대 trace 적재 즉시완화 (청크 커밋) | Huge-trace ingest mitigation (chunked commit)

한 요청이 수만 개의 span 을 만드는 "거대 trace" 가 적재될 때, SQLite 의 write 잠금을
오래 붙잡아 그 사이 들어온 다른 적재가 SQLITE_BUSY 로 유실되던 문제를 완화했습니다.
이제 한 trace 의 span 을 500개 단위로 나눠 짧은 트랜잭션으로 커밋해, 잠금을 붙잡는 시간을
줄이고 조회·다른 적재가 끼어들 틈을 만듭니다. server(collector) 전용 릴리스이며
agent·common 모듈은 변경이 없습니다 — v0.1~v0.3.2 agent 그대로 호환됩니다. 스키마 변경도
없어 0.3.2 DB 와 그대로 호환되고 롤백도 안전합니다.

When a huge trace (a single request producing tens of thousands of spans) was ingested, its
single transaction held the SQLite write lock for a long time, so other concurrent ingests
were dropped with SQLITE_BUSY. This release mitigates that by committing each trace's spans
in chunks of 500 within short transactions, shortening how long the write lock is held and
letting queries and other ingests slip in between. This is a server (collector)-only
release; the agent and common modules are unchanged (fully compatible with v0.1–v0.3.2
agents). No schema change either — fully compatible with 0.3.2 databases, and rolling back is
safe.

새로운 기능 | What's new

  • 거대 trace 적재 즉시완화 (청크 커밋) — 한 trace 의 span 을 500개 단위 청크로 나눠 청크마다 짧은 트랜잭션으로 커밋합니다. 청크 경계마다 write 잠금이 풀려, 거대 trace 하나가 잠금을 통째로 오래 붙잡던 동작이 사라집니다. 물리적으로 잠금을 붙잡는 시간이 줄어듭니다.
  • 유실 기준선 관찰 도구 — 적재 경합으로 SQLITE_BUSY 를 만난 횟수와 버린 양을 세어 로그에 남기고, 로그를 logs/apilens.log 파일로도 기록합니다(기본 롤링). 완화 전·후의 유실 정도를 로그로 직접 비교할 수 있는 기준선이 생겼습니다.
  • SQLite·커넥션 풀 운영값 조정 — 대기 시간(busy_timeout)을 5초에서 10초로 늘리고, 커넥션 풀 크기를 4로 명시하고, WAL 체크포인트 주기를 넓혔습니다. 청크 커밋을 돕는 보조 설정이며, 운영 데이터를 보면서 더 조정할 수 있습니다.
  • payload 중복 방지 — 같은 span 이 다시 들어와도 payload 가 중복으로 쌓이지 않도록 정리했습니다(처음 저장되는 span 은 동작이 이전과 동일).
  • API 문서(Swagger) 다듬기 — 공통 오류 응답 형태, 데이터 관리(유지보수) API 6종의 동작 설명, payload 조회 시 마스킹 적용 시점 안내를 문서에 보강했습니다.

업그레이드 | Upgrade

  • collector(server) jar 만 0.3.3 으로 교체하고 재기동하면 됩니다. agent jar 재배포 불필요 (agent 무변경).
  • 스키마 변경 0 — 0.3.2 DB 와 그대로 호환되고, 0.3.2 로 롤백해도 데이터 영향이 없습니다.

Replace only the collector (server) jar with 0.3.3 and restart. No agent redeploy needed
(agent unchanged). No schema change — fully compatible with 0.3.2 databases, and rolling
back to 0.3.2 has no data impact.

주의 | Notes

  • 이번 릴리스는 완화 + 기준선 확보 라운드입니다. 유실이 몇 % 줄었다는 정량 수치는 아직 측정 전이라 주장하지 않습니다. 완화 효과는 logs/apilens.log 의 SQLITE_BUSY 카운터로 실운영에서 전·후를 비교해 확인하세요. 거대 trace 를 애초에 줄이는 근본 해소(agent 계측량 축소)는 다음 라운드입니다.
  • SQLITE_BUSY 카운터는 메모리에만 두므로 server 를 재시작하면 0 으로 돌아갑니다. 기준선은 로그 파일의 누적으로 비교하세요.
  • API 문서 경로는 여전히 무인증으로 열립니다 — 내부 운영망 배포라면 추가 조치가 필요 없습니다. ApiLens 를 인터넷에 직접 노출하는 배포라면, 앞단 리버스 프록시(nginx 등)에서 /swagger-ui·/v3/api-docs 를 인증/차단하세요.

This release mitigates the problem and establishes a baseline; it does not claim a specific
percentage reduction in dropped ingests (not yet measured). Compare the SQLITE_BUSY
counters in logs/apilens.log before and after in your environment. The root fix (reducing
how many spans the agent produces) is a later round. The SQLITE_BUSY counters are
in-memory and reset to zero on restart — use the log file to compare baselines.

전체 변경 내역은 CHANGELOG 를 참고하세요. | See the CHANGELOG for full details.

Assets 4
Loading