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.