Skip to content

ApiLens v0.4.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 16 Jul 08:36
v0.4.0
e3935a5

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.

Assets 4
Loading