Pinpoint APM 구축은 단순한 모니터링 도구 설치가 아니라, 운영 환경의 관측성(Observability)을 한 단계 끌어올리는 결정입니다. 어느 날 외부 연동 API의 응답이 평소 50ms에서 3초로 느려졌는데 로그만으로는 어디서 막히는지 추적이 불가능했던 경험이 도입의 출발점이었습니다. DB일까, 외부 호출일까, GC 정지일까 추측만 반복하다가 결국 APM 도입을 결정했습니다.
이 글에서는 APM 도구 6종을 비교한 과정과 Pinpoint를 선택한 이유, 구축 아키텍처, 그리고 실제 운영에 올리며 마주친 5가지 애로사항을 정리합니다. 비슷한 의사결정을 앞두고 있다면 참고하시기 바랍니다.
왜 APM이 필요했는가
장애 신고는 외부 연동 파트너로부터 들어왔습니다. 평소 30분이면 끝나던 일괄 호출이 어느 날부터 3시간 가까이 걸린다는 내용이었습니다. 그 시점에 확인 가능한 정보는 다음이 전부였습니다.
- API 액세스 로그: 요청은 들어왔고 응답도 돌아갔다 (정상)
- DB 슬로우 쿼리 로그: 느린 쿼리는 보이지 않는다
- 시스템 메트릭(CPU·메모리): 평균값은 정상 범위
겉으로 보이는 모든 지표가 정상인데 사용자는 느리다고 말합니다. 가장 답답한 상황입니다. 그제서야 깨달은 것은, 우리가 요청과 응답의 양 끝만 알고 있을 뿐, 그 사이의 한 호출 안에서 시간이 어디로 흘렀는지는 전혀 모른다는 사실이었습니다.
이 공백을 메우는 도구가 바로 APM(Application Performance Monitoring) 입니다. APM은 한 요청의 전 구간을 트랜잭션 단위로 따라가며 메서드 호출 시간, DB 쿼리 시간, 외부 API 호출 시간, GC 정지 시간을 시각적으로 보여줍니다. 도입 후 가장 먼저 알게 된 것은 “외부 결제 API 응답이 평소 100ms → 2.8초로 늘어났다”는 사실이었고, 원인은 우리가 아니라 결제사 측의 일시적 장애였습니다.
APM 도구 6종 비교
도입 결정 후 다음 6개 후보를 검토했습니다.
| 도구 | 라이센스 | 호스팅 | 강점 | 약점 |
|---|---|---|---|---|
| Pinpoint | Apache 2.0 (무료) | 자체 구축 | Java 특화, 시각적 분산 추적, 한국 커뮤니티 | HBase 운영 부담 |
| Scouter | Apache 2.0 (무료) | 자체 구축 | 가볍고 빠름, 국내 자료 풍부 | UI·기능이 Pinpoint 대비 부족 |
| Elastic APM | Apache 2.0 / 유료 | 자체 또는 Elastic Cloud | ELK 스택과 통합, 강력한 검색 | Elasticsearch 운영 부담 |
| Jaeger | Apache 2.0 (무료, CNCF) | 자체 구축 | 분산 추적 표준(OpenTelemetry), K8s 친화 | 메서드 레벨 추적은 약함 |
| Datadog APM | 상용 (SaaS) | SaaS | 풀스택 통합(로그·메트릭·APM), UI 최상급 | 호스트당 월 비용 매우 비쌈 |
| New Relic | 상용 (SaaS) | SaaS | 기능 풍부, AI 인사이트 | 비용 부담, 데이터 외부 전송 |
평가 기준은 네 가지였습니다.
- 비용: 운영 호스트 수가 늘어나도 비용이 폭발하지 않을 것
- 데이터 주권: 운영 데이터가 외부 클라우드로 나가지 않을 것 (B2B 컴플라이언스)
- Java/Spring 친화성: 코드 수정 없이 Java Agent 방식으로 붙을 것
- 분산 추적: 여러 서비스 간 호출을 한 화면에서 시각적으로 따라갈 것
이 네 가지로 좁히니 자연스럽게 Pinpoint와 Scouter가 남았고, 시각적 분산 추적과 메서드 단위 콜 트리(Call Tree)가 결정적이었던 Pinpoint를 최종 선택했습니다.
Pinpoint를 선택한 4가지 이유
1. 라이센스 비용이 0이다
운영 환경의 인스턴스 수가 늘어나도 라이센스 비용이 0입니다. Datadog이나 New Relic의 호스트당 월 비용을 1년치로 계산해 보면, 자체 구축한 Pinpoint 클러스터의 인프라 비용을 압도적으로 상회합니다. 인스턴스가 많을수록 자체 구축의 경제성이 커지는 구조입니다.
2. Java Agent 방식으로 코드 수정이 필요 없다
Pinpoint Agent는 JVM 시작 시 -javaagent 옵션으로 부착되며, 바이트코드 인스트루멘테이션을 통해 자동으로 Spring·MyBatis·HTTP Client·JDBC 등의 호출을 추적합니다. 비즈니스 코드 한 줄도 수정하지 않고 도입할 수 있는 점이 가장 컸습니다.
java -javaagent:/opt/pinpoint-agent/pinpoint-bootstrap.jar \
-Dpinpoint.agentId=order-service-01 \
-Dpinpoint.applicationName=order-service \
-jar order-service.jar
3. 시각적 분산 추적과 콜 트리
Pinpoint Web UI의 Call Tree는 한 요청이 거쳐 간 모든 메서드 호출을 트리 구조로 보여줍니다. 어느 메서드에서 몇 ms를 썼는지, 어느 DB 쿼리가 느렸는지, 어느 외부 호출이 멈췄는지를 그림으로 한 번에 파악할 수 있습니다. 이 시각화가 트러블슈팅 시간을 결정적으로 단축합니다.
4. 한국 커뮤니티 자료가 풍부하다
Naver가 만든 도구라 국내 자료, 발표 영상, 트러블슈팅 사례가 다른 도구 대비 압도적으로 많습니다. 신규 도입 시 학습 비용이 가장 적은 선택지였습니다.
Pinpoint 아키텍처와 구축 흐름
Pinpoint는 네 가지 컴포넌트로 구성됩니다.
| 컴포넌트 | 역할 | 권장 사양 |
|---|---|---|
| Agent | 각 애플리케이션 JVM에 부착, 데이터 수집 | 모니터링 대상 서버에 함께 배치 |
| Collector | Agent가 보낸 데이터를 받아 HBase에 저장 | 4 vCPU / 8GB RAM 이상 |
| HBase | 실제 데이터 저장소 | 3노드 이상 클러스터 권장 |
| Web | 시각화 UI 제공 | 2 vCPU / 4GB RAM |
구축 순서는 다음과 같이 진행했습니다.
첫째, HBase 클러스터부터 구성합니다. ZooKeeper 3노드 + HBase Master/RegionServer 구성을 먼저 안정화합니다. 이 단계가 가장 까다롭습니다.
둘째, Collector와 Web을 배포하고 HBase 연결을 확인합니다. 헬스 체크 엔드포인트가 정상 응답하는지 검증합니다.
셋째, 테스트 환경에 Agent를 먼저 부착해 데이터가 Web UI에 정상적으로 보이는지 확인합니다.
넷째, 운영 환경에 점진적으로 Agent를 부착합니다. 한 번에 전체 인스턴스에 적용하지 않고, 카나리 인스턴스 한 대로 부하 영향을 확인한 뒤 확대합니다.
구축하며 마주친 5가지 애로사항
문서에는 잘 나오지 않지만, 실제 운영에 올리며 부딪힌 함정들입니다. 미리 알고 준비하시기 바랍니다.
애로사항 1: HBase 운영 부담이 가장 큰 비용이다
Pinpoint의 가장 큰 약점은 HBase 운영 그 자체입니다. HBase는 RegionServer 장애, Region 분할, Compaction, ZooKeeper 의존성 등 운영 노하우가 필요한 시스템입니다. APM을 도입했더니 정작 HBase를 모니터링할 또 다른 도구가 필요해지는 아이러니가 발생합니다.
해결 방향: 처음부터 HBase 운영을 전담할 사람을 배정하거나, 인력이 없다면 매니지드 HBase 서비스를 고려합니다. HBase가 어렵다면 SkyWalking이나 Elastic APM 같이 다른 스토리지를 쓰는 도구를 재검토하는 것도 합리적인 선택입니다.
애로사항 2: Java·Spring Boot 버전 호환성 매트릭스 함정
Pinpoint Agent는 라이브러리별로 추적 플러그인을 갖고 있는데, Spring Boot 3.x·Java 17/21 환경에서 일부 라이브러리가 추적되지 않는 일이 종종 발생합니다. 가장 흔한 케이스는 다음과 같습니다.
- WebFlux 기반 코드 일부가 추적 누락
- HTTP 클라이언트 라이브러리 최신 버전(예: Apache HttpClient 5.x) 미지원
- Jakarta 패키지(
jakarta.*)와 Javax 패키지(javax.*) 혼용 환경에서 일부 어노테이션 미인식
해결 방향: 공식 호환 매트릭스를 도입 전 반드시 확인하고, 가능하다면 Pinpoint 최신 안정 버전을 사용합니다. 일부 라이브러리가 미지원이라면 핵심 경로만이라도 추적되는지 PoC 단계에서 검증해야 합니다.
애로사항 3: 에이전트가 운영 성능에 미치는 영향
Pinpoint Agent는 약 1~5% 수준의 CPU 오버헤드를 동반합니다. 평소엔 무시할 수준이지만, 모든 트랜잭션을 100% 샘플링하면 네트워크·디스크 부하가 빠르게 누적됩니다. 도입 초반 한 번은 Collector로 가는 네트워크가 포화되어 본 서비스 응답까지 영향을 받은 적이 있습니다.
해결 방향: 샘플링 비율을 운영 트래픽에 맞게 조정합니다. 트래픽이 큰 서비스는 10~20%만 추적해도 통계적으로 충분합니다.
# 20% 샘플링 (20개당 1개 추적이 아니라, 20% 트랜잭션 추적)
profiler.sampling.rate=5
profiler.sampling.type=COUNTING
또한 에러 트랜잭션은 100% 추적되도록 설정해, 정상 트래픽은 샘플링하더라도 장애 추적은 누락되지 않게 합니다.
애로사항 4: 알람·대시보드 기능이 빈약하다
Pinpoint Web UI는 트랜잭션 시각화는 훌륭하지만, 임계치 기반 알람·커스텀 대시보드 기능이 약합니다. “응답 시간 p99가 1초를 넘으면 Slack으로 알림” 같은 기본 요구를 Pinpoint만으로 구현하기 어렵습니다.
해결 방향: 다음 조합을 함께 운영합니다.
| 목적 | 도구 조합 |
|---|---|
| 트랜잭션 트러블슈팅 | Pinpoint |
| 시계열 메트릭·알람 | Prometheus + Grafana + Alertmanager |
| 로그 검색 | ELK 또는 Loki |
| 알림 전달 | Slack / PagerDuty / Telegram |
Pinpoint Flink(스트리밍 분석)와 통합해 알람을 만들 수도 있지만, 운영 부담이 또 늘어나므로 익숙한 Prometheus·Grafana 조합과 병행하는 편이 현실적이었습니다.
애로사항 5: 비동기 코드와 외부 시스템 traceId 전파의 한계
@Async·CompletableFuture·Reactor 같은 비동기 코드는 ThreadLocal 컨텍스트가 끊겨 traceId 전파가 끊어지는 경우가 있습니다. 또한 다른 회사·외부 시스템으로 가는 호출은 우리 쪽 Pinpoint가 추적할 수 없습니다.
해결 방향: 다음 패턴을 적용합니다.
- 비동기 컨텍스트 전파:
TaskDecorator로 MDC와 traceId를 새 스레드로 복사 - 외부 호출 헤더 전파: 모든 외부 호출에
X-Trace-Id헤더 첨부, 양측 시스템이 같은 traceId를 공유하도록 합의 - 분산 추적 표준 준수: 신규 도입이라면 처음부터 W3C Trace Context 표준을 따르도록 설정
운영하며 얻은 효과와 남은 한계
도입 6개월 후의 체감 효과를 정리하면 다음과 같습니다.
얻은 것
| 영역 | 변화 |
|---|---|
| 장애 추적 시간 | 평균 2시간 → 평균 15분 |
| 외부 호출 병목 가시화 | 결제·인증·외부 API 응답 분포 파악 가능 |
| 슬로우 트랜잭션 발견 | 평소 묻혀 있던 p99 이상치 가시화 |
| 배포 영향도 측정 | 배포 전후 응답 시간 비교 가능 |
여전히 남은 한계
| 한계 | 대응 |
|---|---|
| HBase 디스크 관리 | TTL 설정, 주기적 압축 자동화 |
| 신규 라이브러리 추적 누락 | 공식 업데이트 모니터링, 필요 시 플러그인 직접 작성 |
| 보안 정책상 일부 패킷 인스펙션 제한 | 헤더 마스킹 정책 적용 |
APM은 만능 해결책이 아니라, 추측을 사실로 바꾸는 도구입니다. 도입 자체보다 도입 이후의 운영 정책이 더 중요합니다.
APM 도입 체크리스트
도입을 검토 중이라면 다음 항목을 점검하시기 바랍니다.
첫째, APM이 답할 질문이 명확한지 확인합니다. “어느 메서드가 느린가”, “어느 외부 호출이 막혔는가” 등 구체적 질문이 있어야 도구 선택이 명확해집니다.
둘째, 데이터 주권 요구사항을 확인합니다. B2B·금융·공공 환경이라면 SaaS 도구가 컴플라이언스 이슈를 가져올 수 있습니다.
셋째, 운영 인력의 전문 영역을 평가합니다. HBase·Elasticsearch 운영 경험이 없다면 자체 구축의 진짜 비용은 라이센스가 아니라 운영자의 시간입니다.
넷째, 샘플링 정책과 데이터 보관 기간을 미리 설계합니다. 모든 트랜잭션을 1년 보관하면 스토리지가 폭증합니다. 30일 100% + 1년 5% 같은 정책이 현실적입니다.
다섯째, 알람·대시보드는 별도 도구와의 조합을 가정합니다. APM 단독으로 운영 모니터링 전체를 해결할 수는 없습니다.
여섯째, traceId 전파 표준을 정합니다. W3C Trace Context 또는 B3 헤더 중 하나로 통일하고, 외부 연동 파트너와 합의합니다.
자주 묻는 질문 (FAQ)
Q1. Pinpoint와 Scouter 중 어떤 게 더 좋나요?
시각적 분산 추적과 콜 트리가 중요하다면 Pinpoint, 가볍고 빠른 모니터링과 시스템 메트릭 중심이라면 Scouter가 적합합니다. Scouter는 Pinpoint보다 가볍고 설치가 쉬운 대신, 분산 추적 시각화는 다소 약합니다. 둘 다 무료이므로 PoC를 함께 돌려 보는 것을 권장합니다.
Q2. Spring Boot 3.x·Java 21 환경에서 Pinpoint가 잘 동작하나요?
대부분의 핵심 기능은 동작하지만, 일부 최신 라이브러리(예: 최신 HTTP Client, WebFlux 일부 케이스)는 추적이 누락될 수 있습니다. 도입 전 공식 호환 매트릭스 확인과 PoC 검증이 필수입니다. 신규 도입이라면 Pinpoint의 최신 안정 릴리스를 사용하시기 바랍니다.
Q3. HBase 대신 다른 스토리지로 바꿀 수 있나요?
Pinpoint는 기본적으로 HBase에 강하게 결합되어 있어 다른 스토리지로의 교체는 어렵습니다. HBase 운영이 부담된다면 Elastic APM(Elasticsearch 기반) 이나 SkyWalking(Elasticsearch·H2·MySQL 등 선택 가능) 을 처음부터 검토하시기 바랍니다.
Q4. Pinpoint Agent를 운영 환경에 붙여도 안전한가요?
수년간 다수 기업에서 운영 검증된 도구라 안전성 자체는 높습니다. 다만 샘플링 비율을 100%로 두면 네트워크·CPU 부담이 누적될 수 있으므로, 운영 트래픽 규모에 맞춰 샘플링을 조정해야 합니다. 카나리 인스턴스 한 대에서 1주일 부하 영향을 측정한 뒤 전체 확대를 권장합니다.
Q5. 분산 환경에서 traceId 전파는 어떻게 설정하나요?
같은 Pinpoint 클러스터에 연결된 서비스 간에는 Pinpoint Agent가 자동으로 헤더를 통해 traceId를 전파합니다. 외부 시스템과의 호출은 X-B3-TraceId(B3) 또는 traceparent(W3C Trace Context) 헤더를 사용해 양측이 같은 ID를 공유하도록 합의해야 합니다. 신규 설계라면 W3C 표준을 권장합니다.
마무리
Pinpoint APM 구축의 본질은 도구 설치가 아니라, 추측으로 시작하던 장애 대응을 사실 기반으로 바꾸는 운영 전환입니다. 어느 메서드가 느린지, 어느 외부 호출이 막혔는지, 어느 쿼리가 누적되는지를 화면으로 볼 수 있게 되면, 같은 사람·같은 인프라로도 운영 안정성이 크게 향상됩니다.
핵심을 다시 정리하면 다음과 같습니다. APM 도구는 비용·데이터 주권·Java 친화성·분산 추적 네 가지 기준으로 좁히고, 자체 구축이 가능하다면 Pinpoint가 한국 환경에서 가장 균형 잡힌 선택입니다. 다만 HBase 운영 부담, 버전 호환성, 에이전트 부하, 알람 기능 한계, 비동기 추적의 끊김은 도입 전에 반드시 인지하고 대비해야 합니다. Prometheus·Grafana 같은 기존 모니터링 스택과 병행하는 운영 전략이 가장 현실적입니다.
핵심 요약
- 도입 동기: 양 끝의 로그만으로는 한 요청 안에서 시간이 어디로 흘렀는지 알 수 없습니다.
- 선택 기준 4가지: 비용 / 데이터 주권 / Java 친화성 / 분산 추적 시각화.
- Pinpoint 강점: 무료·Java Agent 자동 추적·시각적 콜 트리·한국 커뮤니티.
- 5가지 애로사항: HBase 운영 부담 / 버전 호환성 / 에이전트 부하 / 알람 한계 / 비동기·외부 traceId 전파.
- 운영 전략: Pinpoint + Prometheus·Grafana + ELK 조합으로 보완, 샘플링 정책 사전 설계.