ApiLens v0.5.0

ApiLens v0.5.0 — 서비스별 agent 버전 표시 + 계측 분석 화면 | Per-service agent version + instrumentation analysis screen

collector(server)와 화면만 바뀌는 릴리스입니다. agent 는 다시 배포하지 않아도 됩니다.
두 가지가 핵심입니다. 첫째, 서비스 목록에서 각 서비스가 어떤 버전의 agent 를 쓰는지
바로 보입니다. 둘째, 계측 분석 화면이 새로 생겼습니다 — 어느 클래스가 기록을 많이
만드는지 세 가지 잣대로 보여 주고, 계측에서 빼기 전에 얼마나 줄어드는지와 흐름이
얼마나 조각나는지를 함께 계산해 줍니다. 지난 릴리스에서 들어온 계측 제외 옵션을
"어디에 쓸지" 정할 수 있게 하는 짝입니다. DB 에 컬럼 하나가 추가되므로 올리기 전
DB 파일 백업을 권합니다.

This release changes only the collector (server) and the UI — you do not need to redeploy
the agent. Two things matter. First, the service list now shows which agent version each
service runs. Second, a new instrumentation analysis screen shows which classes produce
the most records, measured three different ways, and — before you exclude anything — computes
both how much you would save and how much your traces would fragment. It is the counterpart
that tells you where to apply the package-exclude option introduced in the previous release.
One column is added to the database, so back up your DB file before upgrading.

---

새로운 기능 | What's new

• 서비스별 agent 버전 표시 — 서비스 목록에 agent 버전 칸이 생겼습니다. 어떤 서비스가 구버전 agent 로 돌고 있는지 화면에서 바로 확인할 수 있습니다. 값은 agent 가 시작할 때 보내는 첫 기록에서 가져오며, 한 번 받은 값은 계속 유지됩니다.
  • ⚠️ 이미 돌고 있는 서비스는 agent 를 한 번 재시작하기 전까지 빈 칸(—)으로 보입니다. 지난 값을 거슬러 채우지 않습니다.
• 계측 분석 화면 — 서비스 목록의 계측 분석 버튼으로 들어갑니다.
  • 세 가지 잣대의 순위 — 기록 수 · 본문 건수 · 본문 용량. 잣대마다 순위가 다릅니다. 기록 수로는 뒤쪽인데 용량으로는 앞쪽인 클래스가 실제로 있으므로, 한 가지만 보고 정하면 큰 덩어리를 놓칩니다. 각 수치 옆에 그 잣대에서 전체 몇 번째인지를 함께 적었습니다.
  • 빼기 전 예상 결과 — 클래스를 골라 보면 줄어드는 양과 함께 흐름이 얼마나 조각나는지를 계산해 보여 줍니다. 조각난 흐름이 많아지면 저장량은 줄어도 목록이 읽기 어려워집니다.
  • 조각남 경고 — 조각난 흐름의 비율이 높아지면 경고가 뜹니다. 진행을 막지는 않고 확인 절차가 한 단계 늘어납니다.
  • 뺄 수 있는지 여부 — 화면에 보이는 이름으로 실제로 제외가 되는지를 가능 / 불가 / 확인 필요 로 나눠 보여 줍니다. MyBatis mapper 처럼 화면 이름과 계측이 걸리는 이름이 달라 제외가 안 되는 계층이 있습니다.
  • 분석은 버튼을 눌렀을 때만 실행됩니다(자동 새로고침 없음). 한 번에 하나씩만 돌며, 오래 걸리면 스스로 멈추고 구간을 좁히라고 안내합니다.
• 문서 보강 — 계측 제외 옵션으로 뺄 수 없는 계층을 문서에 명문화했습니다(docs/agent-options.md). MyBatis mapper 는 화면에 보이는 이름으로 제외되지 않으며, 흐름의 위쪽을 빼면 그 아래 호출들이 각자 독립된 시작점이 되어 조각난 흐름이 쏟아질 수 있습니다.

업그레이드 | Upgrade

• agent 재배포 불필요 — 이번 릴리스는 agent 소스를 바꾸지 않았습니다. 기존 agent 를 그대로 두고 collector(server) jar 만 0.5.0 으로 교체하고 재기동하면 됩니다. 구버전 agent 와 새 collector 사이의 수집은 그대로 동작합니다.
• ⚠️ DB 파일 백업을 먼저 하세요. 기동하면 서비스 표에 컬럼 하나가 추가되는 변경이 자동으로 적용되고, 이 변경은 되돌릴 수 없습니다. 0.5.0 으로 한 번 올린 DB 파일을 0.4.0 collector 로 다시 열지 마세요. 되돌려야 한다면 백업한 파일로 복원하고 이전 jar 로 기동하세요.
  • 컬럼을 더하는 것뿐이라 기존 데이터에는 영향이 없고, 기존 행은 그 값이 비어 있는 상태로 정상 동작합니다.
• agent 버전 칸을 채우려면 agent 를 한 번 재시작하세요. 재시작 전까지는 빈 칸으로 보입니다(정상 동작이며 결함이 아닙니다).
• API 호환 — 적재 계약과 기존 조회 응답이 그대로입니다. 서비스 목록 응답에 값이 하나 늘어난 것뿐이라 기존 사용처에 영향이 없습니다.

No agent redeploy needed. This release does not change agent sources — replace only the
collector (server) jar with 0.5.0 and restart. Ingestion between an older agent and the new
collector works unchanged. ⚠️ Back up your DB file first: starting up applies a one-column
addition to the services table automatically, and that change cannot be undone. Do not
reopen a database that 0.5.0 has upgraded with a 0.4.0 collector — restore from your backup
and start the previous jar instead. Restart the agent once to populate the agent-version
column; until then it shows as blank, which is expected. Existing API contracts are unchanged.

주의 | Notes

• agent 버전이 0.4.0 으로 보이는 것은 정상입니다. 제품 버전(0.5.0)과 다른 것은 어긋남이 아니라 의도한 결정입니다 — 이번 릴리스는 agent 소스를 바꾸지 않았으므로 agent 가 보고하는 버전도 그대로 두었습니다.
• 줄어드는 양은 환경마다 다릅니다. 계측 분석 화면이 보여 주는 예상치는 선택한 구간의 실제 자료로 계산한 값입니다. 일반적으로 몇 퍼센트가 줄어든다는 수치를 이 문서는 단정하지 않습니다 — 화면에서 본인 환경의 값을 확인하세요.
• 조각남을 함께 보세요. 줄어드는 양만 보고 빼면 흐름이 조각나 목록이 읽기 어려워질 수 있습니다. 화면은 두 값을 항상 같이 보여 주도록 만들었습니다.
• 분석 화면은 자동으로 돌지 않습니다. 무거운 조회이므로 버튼을 눌렀을 때만 실행되고, 동시에 하나만 돕니다. 다른 분석이 돌고 있으면 잠시 뒤 다시 시도하라는 안내가 나옵니다.

The agent reporting 0.4.0 while the product is 0.5.0 is intentional, not a mismatch — agent
sources were untouched. Savings estimates are computed from your own data for the selected
window; this document claims no general percentage. Always read the fragmentation figure
alongside the savings figure — the screen always shows both. The analysis runs only when you
press the button, one at a time.

---

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

ApiLens v0.4.0

ApiLens v0.4.0 — agent 계측량 제어(opt-in) + 마스킹 정규식 폭주 실행 방어 | Agent instrumentation control (opt-in) + masking regex runtime guard

v0.1 이후 처음으로 agent 모듈이 바뀌는 릴리스입니다. 두 가지가 핵심입니다.
첫째, 운영자가 잡음이 많은 패키지를 계측에서 뺄 수 있는 옵션이 생겼습니다(기본은
현재 계측 그대로라, 켜지 않으면 동작이 이전과 완전히 같습니다). 둘째, 마스킹에 쓰는
정규식이 특정 입력을 만나 폭주(catastrophic backtracking)해 처리 스레드를 오래 붙잡는
문제를, 마스킹 1회에 시간 상한을 두어 막았습니다. server 의 API·DB 스키마는 바뀌지
않습니다(0.3.3 DB 와 그대로 호환). 다만 agent jar 산출물이 v0.1 이후 처음 바뀌므로,
운영망(NAS 등)에 새 agent jar 를 다시 배포하고 대상 앱 JVM 을 재시작해야 이번 변경이
반영됩니다.

This is the first release since v0.1 that changes the agent module. Two things matter.
First, operators can now exclude noisy packages from instrumentation (the default excludes
nothing, so if you leave it off, behavior is exactly the same as before). Second, when a
masking regex meets certain input and blows up (catastrophic backtracking), holding the
processing thread for a long time, a per-call time budget now stops it. The server API and
DB schema are unchanged (fully compatible with 0.3.3 databases). However, since the agent
jar artifact changes for the first time since v0.1, you must redeploy the new agent jar and
restart the target app's JVM for this release's changes to take effect.

---

새로운 기능 | What's new

• 계측 제외 패키지 옵션 (apilens.instrument.exclude-packages) — 저장 부담과 대시보드 잡음을 키우는 패키지(예: 특정 batch·repository)를 계측에서 뺄 수 있습니다. 대상 앱 JVM 옵션에 콤마로 패키지 prefix 를 나열하면(예: -Dapilens.instrument.exclude-packages=com.example.batch,com.example.repo), 그 패키지의 클래스는 계측 대상에서 제외돼 span·payload 를 만들지 않습니다. 계측을 붙이는 시점에 결정되므로 실행 중 추가 비용은 없습니다. 기본값은 "제외 없음" 이라 옵션을 지정하지 않으면 지금까지와 동작이 똑같습니다. 고급 옵션이라 설치 명령 생성기에는 노출하지 않고, 운영망 JVM 의 -D 로 직접 지정합니다.
• 얼마나 줄었는지는 직접 측정하세요 — 계측 제외로 저장량·잡음이 얼마나 줄었는지의 정량 수치는 이 문서가 단정하지 않습니다. 본인 운영망에서 옵션 적용 전·후로 저장량·대시보드를 비교해 확인하세요.

보안 | Security

• 마스킹 정규식 폭주(ReDoS) 실행 시점 방어 — 인증 없이 들어온 임의 payload 와 운영자가 저장해 둔 정규식 룰이 만나 정규식이 폭주하면(catastrophic backtracking), 처리 스레드를 오래 붙잡을 수 있었습니다. 이제 마스킹 1회 처리에 기본 1초의 시간 예산을 두고, 넘으면 다음처럼 안전하게 처리합니다.
  • 적재 경로: 해당 payload 를 통째로 마스킹(***)한 보수적 형태로 저장하고 계속 진행합니다. 평문이 부분적으로라도 새지 않습니다.
  • 마스킹 룰 미리보기: 400 응답으로 알려줍니다.
  • 기존의 "룰 저장 시점 복잡도 검사"와 함께, 저장·미리보기·적재 세 경로를 한 엔진 위에서 방어합니다. 이로써 이전 버전에 남아 있던 무인증 적재·미리보기 경로의 정규식 폭주 취약 구멍을 닫았습니다.

업그레이드 | Upgrade

• agent jar 재배포 + JVM 재시작 (중요) — v0.1 이후 처음으로 agent jar 자체가 바뀝니다(계측 옵션 추가 + 공유 마스킹 엔진 재빌드 + 버전 정렬). 이번 변경(새 계측 옵션·버전 라벨)을 반영하려면 운영망(예: NAS vams-prod)에 새 agent jar 를 다시 배포하고 대상 앱 JVM 을 재시작하세요. 재배포하지 않아도 구 agent 는 기존대로 동작하지만(무파손), 새 계측 제외 옵션은 새 agent jar 에서만 유효합니다.
• collector(server) jar 교체 — server jar 를 0.4.0 으로 교체하고 재기동하면 됩니다. DB 스키마 변경 0 — 0.3.3 DB 와 그대로 호환되고, 0.3.3 으로 롤백해도 데이터 영향이 없습니다(롤백 시 구 agent jar 도 함께 되돌리는 것을 권장).

Redeploy the agent jar and restart the JVM (important). For the first time since v0.1,
the agent jar itself changes. Redeploy the new agent jar to your environment (e.g. the NAS
vams-prod) and restart the target app's JVM to pick up the new instrumentation option and
version label. Not redeploying keeps the old agent working (no breakage), but the new
package-exclude option only takes effect with the new agent jar. Replace the collector
(server) jar with 0.4.0 and restart — no schema change (fully compatible with 0.3.3
databases; rolling back to 0.3.3 has no data impact).

주의 | Notes

• 기본값은 이전과 동일 — 계측 제외 옵션을 켜지 않으면 계측 범위가 지금까지와 완전히 같습니다. "조용히 계측이 줄어드는" 일은 없습니다.
• 정규식 폭주 방어는 안전 우선 — 시간 예산을 넘긴 payload 는 통째로 마스킹해 저장하므로, 그 경우 원문 대신 *** 가 저장됩니다(평문 노출 대신 안전을 택한 결과).
• 정량 수치는 미주장 — 계측 제외로 저장량이 얼마나 줄었는지, 정규식 방어가 유실을 얼마나 막았는지는 측정 전이라 수치를 주장하지 않습니다. 본인 운영망에서 전·후로 비교하세요.

The default excludes nothing — behavior is identical to before unless you opt in; there is no
silent reduction of instrumentation. The regex guard prioritizes safety: a payload that
exceeds the time budget is stored fully masked (*** instead of plaintext). This release does
not claim specific percentage figures for storage reduction or dropped-ingest prevention
(not yet measured) — compare before and after in your own environment.

---

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

ApiLens v0.3.3

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.

ApiLens v0.3.2

ApiLens v0.3.2 — API 문서 자동화 (Swagger UI) | Automated API Docs (Swagger UI)

손으로 쓰던 마크다운 API 문서가 코드와 어긋나던 문제를, 컨트롤러에서 스펙을 자동으로
만들어 단일 jar 에 담는 방식으로 근본 해소했습니다. server 를 띄운 뒤 /swagger-ui
(인터랙티브 문서) 또는 /v3/api-docs (OpenAPI JSON) 를 열면 최신 요청·응답 스키마와
상태 코드를 그대로 확인하고 시험 호출할 수 있습니다. server 와 UI 의 버전 라벨만
바뀌고 agent·common 모듈은 변경 없음 — v0.1~v0.3.1 agent 그대로 호환됩니다.

We fixed the hand-written Markdown API docs — which kept drifting from the code — by
generating the spec from the controllers and embedding interactive docs in the single jar.
Start the server and open /swagger-ui (interactive) or /v3/api-docs (OpenAPI JSON) to
inspect and try the current request/response schemas and status codes. Only the server
and UI version labels changed; the agent and common modules are unchanged (fully
compatible with v0.1–v0.3.1 agents).

---

새로운 기능 | What's new

• API 문서 자동화 (OpenAPI / Swagger UI) — springdoc-openapi 로 컨트롤러에서 스펙을 자동 생성하고 인터랙티브 문서를 단일 jar 에 임베드했습니다. 손으로 문서를 갱신하지 않아도 전체 엔드포인트가 코드와 항상 일치합니다. server 전용 의존성이라 agent 는 무관 (재빌드 불필요).
• 문서 경로는 인증 없이 열립니다 — API Key 를 설정한 기동 상태에서도 /swagger-ui · /v3/api-docs 는 토큰 없이 접근할 수 있습니다 (의도된 면제). 기존 /v1/** 관리·조회 API 의 보호는 그대로 유지됩니다. 문서 경로를 위한 신규 필터·인터셉터는 추가하지 않았습니다.
• 문서 버전이 빌드 버전을 자동 추종 — OpenAPI info.version 을 손으로 적지 않고 빌드 버전에서 주입해, 버전을 올릴 때 문서 버전이 어긋나는 문제를 원천 차단했습니다.

업그레이드 | Upgrade

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

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

주의 | Notes

• /swagger-ui · /v3/api-docs 는 인증 없이 열립니다. 신뢰망 안에서 운영자가 단독으로 쓰는 전제라 문서 경로는 면제로 두었습니다. server 를 인터넷에 직접 노출하는 배포라면, 앞단 리버스 프록시(nginx 등)에서 이 두 경로를 인증/차단하는 것을 권장합니다.
• 필드 단위 요청/응답 계약의 단일 진실 출처는 이제 자동 스펙(/swagger-ui)입니다. docs/api.md 에는 자동 스펙이 담기 어려운 운영 서사(유지보수 중 503, 마스킹 적용 시점, 인증 헤더 전제 등)만 남겼습니다.

/swagger-ui and /v3/api-docs are exposed without authentication (intended, for a
single trusted-network operator). If you expose the server directly to the internet, put a
reverse proxy (e.g. nginx) in front and authenticate or block those two paths.

---

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

ApiLens v0.3.1

v0.3.1 — 유지보수 모드(수신 일시정지)

디스크 최적화(VACUUM)·정리를 SQLite 잠금 경합 없이 끝내도록 collector 의
적재만 잠시 멈추는 기능입니다. server 와 UI 만 바뀌고 agent·apilens-common
모듈은 변경 없음 (v0.1~v0.3.0 agent 그대로 호환).

BREAKING CHANGES: 없음. 기존 동작 변경 0 · 와이어 계약 불변(정상 수신은
202 + {accepted,traces} 그대로). 503 은 일시정지를 켰을 때만 나오는 신규 동작.

주요 변경:
- 수신 일시정지 API 3종: GET /v1/maintenance/status · POST /v1/maintenance/pause · POST /v1/maintenance/resume (멱등, /v1/** 인증 자동 계승)
- POST /v1/spans: 일시정지 중 503 + Retry-After:60, validate/mask/DB write 전부 skip
- max-pause cap 30분: 켜둔 채 잊어도 30분 뒤 자동 재개 (스케줄러 없는 lazy 판정)
- UI 4종: 전역 배너 · Services 배지 · Dashboard 폴링 중단 · 정리 전 일시정지 권장 안내
- 상태 in-memory — server 재시작 시 paused=false 복귀, 스키마 변경 0

ApiLens v0.3.0

v0.3.0 — API Key 인증 + 마스킹 ReDoS 가드 + 온라인 VACUUM 최적화

BREAKING CHANGES:
- 관리/조회 API 에 선택적 API Key 인증 신설. APILENS_AUTH_API_KEY(env) 또는
  -Dapilens.auth.api-key 설정 시 /v1/** 관리·조회 API 가 Authorization: Bearer 헤더 요구.
- 키 미설정 시 무인증 폴백 (0.2.x 동일 + 기동 WARN 1회) — 기존 환경 호환.
- 롤백: 0.2.x jar 로 되돌려도 DB 호환 (스키마 변경 없음).
- agent(ingest /v1/spans) 무인증 면제 — NAS·원격 agent 적재 영향 0.

Added: API Key 인증 / 마스킹 ReDoS 가드 / 온라인 VACUUM 최적화.
agent·apilens-common 모듈 무변경 (v0.1/v0.2 agent 호환). 자세한 내역: CHANGELOG.md [0.3.0]

ApiLens v0.2.1

v0.2.1 — payload guard + manual maintenance + disk reclaim (server-only)

ApiLens v0.2.0

ApiLens v0.2.0 (2026-06-11) — 성능 수습 + 설정 페이지 + trace 필터

본질 의도: retention 미구현·22GB(trace 388만 건) 누적의 근본 수습 — cleanup 신설
(기본 30일, 매일 04:00) + SQLite WAL 전환 + /v1/services 24h 윈도우 카운트 +
복합 인덱스 (전수 COUNT 1.7s → p95 89.8ms 실측). 운영자가 결재 없이 직접 조정하는
설정 페이지 (/settings — retention + 마스킹 룰 관리/라이브 프리뷰) + Dashboard
trace 필터 (status + operation 검색). agent 모듈 무변경 — v0.1 agent 그대로 호환.

BREAKING: journal_mode delete→WAL 전환 / GET /v1/services traceCount 의미 변경
(누적 전수 → 최근 24h) / retention 기본 30일 자동 삭제 시작 — 상세·마이그레이션은
CHANGELOG [0.2.0] BREAKING CHANGES 절 참조.

ApiLens v0.1.0

ApiLens v0.1.0 — 첫 공개 릴리스 | First public release

Spring Boot 운영자를 위한 가벼운 호출 추적 도구입니다. 코드 수정 없이 -javaagent: 한 줄로
부착하여 controller → service → repository → SQL 흐름과 각 단계의 payload를 한 화면에서 봅니다.

A lightweight call-tracing tool for Spring Boot operators. Attach with one -javaagent: flag — no
code change — and see the controller → service → repository → SQL flow with per-step payloads on a
single screen.

이 릴리스는 실제 운영 시스템 dogfooding(60,000+ trace)을 거쳐 호스트 영향 P0 이슈를 잡은 뒤
출시되었습니다. Dogfooded against a live production system before release.

---

다운로드 | Downloads

파일	용도
apilens-server-0.1.0.jar	ApiLens server (UI 임베드). java -jar 로 실행
apilens-agent-0.1.0.jar	사용자 앱에 -javaagent: 로 부착

빠른 시작 | Quick Start

# 1. server 실행 (포트 8765)
java -jar apilens-server-0.1.0.jar

# 2. 브라우저에서 Setup wizard
open http://localhost:8765

# 3. 자기 앱에 agent 부착 후 재기동
java -javaagent:/path/to/apilens-agent-0.1.0.jar \
     -Dapilens.server=http://localhost:8765 \
     -Dapilens.service.name=my-app \
     -jar my-app.jar

---

주요 기능 | Highlights

• 무중단 부착 — 코드 수정 0줄, ByteBuddy premain, 모든 의존성 relocate로 호스트 클래스 충돌 0
• 노드 그래프 추적 — controller → service → repository → SQL을 mind-map으로 시각화
• MyBatis Mapper 자동 추적 — @Mapper 인터페이스 호출 캡처
• JDBC 파라미터/결과셋 캡처 — SQL의 ? 자리에 실제 값 표시 (kill switch 제공)
• server-side PII 마스킹 — 주민번호·카드번호·password/token 기본 룰 자동 적용
• Setup wizard — 브라우저에서 옵션 선택 → 부착용 JVM 옵션 한 줄 생성
• 단일 jar 배포 — server + UI가 하나의 jar

---

⚠️ 업그레이드 안내 | Upgrade note

사전 dogfooding으로 0.1.0-SNAPSHOT 빌드를 배포한 환경(예: NAS 원격)은 즉시 0.1.0으로
재배포하기를 권장합니다. wizard 옵션 키 변경과 호스트 데이터 무결성 fix가 포함되어 있습니다.

If you deployed a 0.1.0-SNAPSHOT build during pre-release dogfooding, redeploy to 0.1.0
immediately — this release contains wizard option-key corrections and host data-integrity fixes.

---

v0.1 한계 | Limitations

• 단일 서비스 추적 (MSA 분산 trace는 v0.3 예정)
• 동기 호출만 (@Async / WebFlux는 v0.2)
• 메서드 파라미터 이름이 arg0·arg1… 인덱스로 표시 (-parameters 컴파일 옵션으로 실제 이름 표시 가능)
• JDBC 파라미터의 키 이름 기반 마스킹 한계 — 민감 컬럼 우려 시 apilens.jdbc.capture-params=false
• 인증·권한 없음 (운영망 내부, 신뢰된 네트워크 사용 가정)

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

---

License: Apache 2.0 · 무료 오픈소스 (donation only)