Pinpoint로 APM 구축하기 With SpringBoot

1. APM 이란?

APM이란 Application Performance Management / Application Performance Monitoring의 약자이다.

즉, 애플리케이션의 성능을 관리/모니터링 을 담당한다. 

 

APM 도구를 사용하면 서버에서 발생하는 메트릭(CPU, Memory, Thread, Transaction, …), 이벤트, 로그, 트랜잭션 등을 모니터링할 수 있다.

 

 

이렇게 분석한 데이터는 아래의 목적을 위해 활용할 수 있다.

• 성능 문제를 예측하고 방지
• 고객 기대 성능 보장, 고객 경험 향상
• 응답 시간 보장
• 가용성 증대, 다운타임 감소

 

 

 

 

 

 

 

 

 

 

2. Pinpoint 와 Prometheus+Grafana 차이

Prometheus+Grafana도 유명한 모니터링 도구이다. Pinpoint와 Prometheus는 비슷한 역할을 하지만 사용하는 목적에서 약간의 차이를 갖는다. 

 

추적

Prometheus는 서버의 각 지표(metric)을 활용해서 JVM Memory, 초당 트랜잭션 발생 수, Thread 상황 등 자원 상태를 파악하기 좋다. 이를 통해 전체적인 시스템 상태를 시각화할 수 있어 전반적인 자원 관리에 적합하다. 

 

반면, 문제가 발생했을 때 단순히 시각화만으로는 정확한 원인을 파악하기 어려울 수  있다. 그렇지만, 문제가 발생할 경우 단순히 시각화만 가능할 경우 정확한 원인을 파악하기 힘들 수도 있다.

 

이때 Pinpoint는 트레이싱(tracing)을 통해 요청의 흐름을 추적하고, 특정 문제 지점을 명확히 파악할 수 있도록 도와준다. 

 

쉽게 말해, Prometheus와 Grafana는 전체적인 시스템의 상태(숲)를 파악하는 데 유리하며, Pinpoint는 특정 문제의 원인(나무)을 깊이 분석하는 데 효과적이다. 

 

 

 

데이터 저장 및 질의

Prometheus는 내장된 시계열 데이터에 수집한 데이터를 저장하고, PromQL을 통해 질의할 수 있다.

 

Pinpoint에서는 Elasticsearch와 HBase와 같은 분산 데이터베이스에 데이터를 저장할 수 있고, Kibana를 통해 저장된 데이터를 검색하고 시각화할 수도 있다.

 

 

 

수집 방식

두 APM 도구는 데이터 수집 방식에 따른 확장성 차이가 있다.

 

Prometheus는 Exporter가 주기적으로 메트릭 데이터를 Pull 방식으로 수집하기 때문 분산 서버에 적용하기에 적합하지 않다.

 

Pinpoint는 Prometheus랑 다르게 Push 방식으로 데이터를 Collector에 전달하기 때문에 분산 서버에서도 잘 동작한다.

 

확장성을 제공하는 데 중점을 두었고, 수집된 데이터의 양이 증가해도 확장 가능한 아키텍처를 가지고 있다. 

 

 

• Pinpoint Agent - 애플리케잇녀의 성능 관련 지표 수집 및 전달
• Pinpoint Collector - Agent에서 받은 정보를 HBase에 적재
• Pinpoint Web UI - 수집된 정보를 화면으로 제공한다.(성능, 모니터링, 지표)

 

 

 

 

 

 

 

 

 

 

 

3. Pinpoint 띄우기

 

테스트를 위해 2개의 가상 서버를 띄웠고,

Server1엔 SpringBoot + Agent

Server2엔 HBase, Collector, Pinpoint Web을 띄울 것이다. 

 

Server1 환경은 SpringBoot Application을 띄우기 위한 Docker, Java21, .. 을 설치해뒀고

Server2 환경엔 Java8 만 설치해뒀다. 

 

Pinpoint의 버전은 Pinpoint Github에서 본인에게 맞춰 사용하면 된다.

 

나는 SpringBoot 3.x, Java21 에 

Agent: 3.0.1 (3 이하 버전이 Agent는 Java21과 호환X)

HBase: 1.2.7

Collector: 2.2.2

Web: 2.2.2

버전을 사용해서 띄웠고 문제 없이 동작했다. 

 

 

 

 

 

Server2 (APM 환경 세팅)

Pinpoint는 Hbase 1.2.X 버전에 최적화되어있다고 해서 1.2.7을 설치했다.

 

HBase 설치

wget https://archive.apache.org/dist/hbase/1.2.7/hbase-1.2.7-bin.tar.gz

tar xzvf hbase-1.2.7-bin.tar.gz

vi ./hbase-1.2.7/conf/hbase-env.sh

// 이 옵션을 주석처리 하지 않으면 hbase 실행시 warning 이 뜸
# export HBASE_MASTER_OPTS="$HBASE_MASTER_OPTS -XX:PermSize=128m -XX:MaxPermSize=128m"
# export HBASE_REGIONSERVER_OPTS="$HBASE_REGIONSERVER_OPTS -XX:PermSize=128m -XX:MaxPermSize=128m"

./hbase-1.2.7/bin/start-hbase.sh

 

 

HBase 와 JAVA Version 호환은 아래와 같다.

 

 

 

 

 

PinPoint 정보를 담을 테이블 생성

# 스크립트 다운
wget https://raw.githubusercontent.com/pinpoint-apm/pinpoint/master/hbase/scripts/hbase-create.hbase

# 스크립트 실행
./hbase-1.2.7/bin/hbase shell hbase-create.hbase

 

 

 

 

 

Pinpoint Collector 설치

// jar 파일 다운
wget https://github.com/pinpoint-apm/pinpoint/releases/download/v2.2.2/pinpoint-collector-boot-2.2.2.jar

// 실행권한
chmod +x pinpoint-collector-boot-2.2.2.jar

// 실행
nohup java -jar -Dpinpoint.zookeeper.address=localhost pinpoint-collector-boot-2.2.2.jar > collector.log 2> collector-error.log &

 

 

 

 

 

Pinpoint Web 설치

# jar 파일 다운
wget https://github.com/pinpoint-apm/pinpoint/releases/download/v2.2.2/pinpoint-web-boot-2.2.2.jar

# 실행 권한 부여
chmod +x pinpoint-web-boot-2.2.2.jar

# 백그라운드 실행
nohup java -jar -Dpinpoint.zookeeper.address=localhost pinpoint-web-boot-2.2.2.jar > web.log 2> web-error.log &

 

 

 

 

Server1 (SpringBoot + Agent)

 

Agent 설치

# agent 설치
wget https://repo1.maven.org/maven2/com/navercorp/pinpoint/pinpoint-agent/3.0.1/pinpoint-agent-3.0.1.tar.gz

# 압축 해제
tar xvzf pinpoint-agent-3.0.1.tar.gz

# config 파일 수정
sudo vi pinpoint-root.config

# 앞에서 구성한 monitoring EC2의 ip로 수정
profiler.transport.grpc.collector.ip=pinpoint ip로 변경

 

 

Agent는 Java21 까지 지원 가능하다. 

 

 

 

 

 

Spring Boot Dockerfile 작성

# Java 21 OpenJDK 이미지를 기반으로 설정
FROM eclipse-temurin:21-jdk-jammy

# 작업 디렉토리 설정
WORKDIR /app

# JAR 파일 복사
COPY build/libs/arch-unit-test-0.0.1-SNAPSHOT.jar app.jar

EXPOSE 8080

# 애플리케이션 실행 명령
ENTRYPOINT ["java", "-jar","-javaagent:/pinpoint/pinpoint-bootstrap-3.0.1.jar", "-Dpinpoint.agentId=appDev","-Dpinpoint.applicationName=app1","-Dpinpoint.config=/pinpoint/pinpoint-root.config", "-Duser.timezone=Asia/Seoul", "/app/app.jar"]

 

실행 명령을 보면 /pinpoint 하위에서 pinpoint 관련해서 접근하고 있다. 따라서 저 내용들을 컨테이너 안으로 볼륨 마운트 시켜줘야 한다. 

 

 

 

 

Spring Boot Docker 컨테이너 실행

sudo docker run -d -p 8080:8080 -v /home/js.kim/pinpoint/pinpoint-agent-3.0.1:/pinpoint --network pinpoint --name app1 app1

 

SpringBoot 실행 전 아래와 같이 PINPOINT가 먼저 뜬다. 

 

 

 

 

 

Postgres DB 컨테이너 실행

docker run -d --network pinpoint --name postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=testDB -p 15432:5432 postgres

 

 

 

 

 

 

 

 

 

4. Pinpoint 기능

Server2에 띄웠던 Pinpoint Web 주소 [ip]:8080 로 접근해보면 Agent와 함께 실행시켰던 SpringBoot Application이 뜬다. 

 

 

 

 

Postman으로 요청을 보내보면 이런식으로 ServerMap이 제공되고 호출 횟수 또한 보여진다. 

 

 

 

 

 

우측 패널 맨 위에 Scatter Chart가 존재하는데 RealTime Scatter Graph를 드래그하여 들어가면, Pinpoint CallStack 을 볼 수 있다. 

 

 

 

 

 

 

서버 Inspector 정보도 확인할 수 있다.

 

 

아래와 같은 정보들을 확인할 수 있다. 

 

 

• Heap Usage: JVM의 Heap 정보와 Major Garbage Collection에 소요된 시간.
• Non-Heap Usage: JVM의 Non-Heap 메모리 정보와 Major Garbage Collection에 소요된 시간.
• JVM/System CPU Usage: JVM과 시스템의 CPU 사용량. 멀티코어 CPU의 경우 전체 코어 사용량의 평균 값.
• Transactions Per Second: 서버로 유입된 초당 트랜잭션 수.
• Active Requests: 사용자 요청을 처리 중인 Agent의 활성 요청 현황.
• Total Threads: Agent가 사용하는 전체 쓰레드 수.
• Response Time: Agent의 평균 응답 시간.
• Open File Descriptors: 현재 열려 있는 File Descriptor의 개수 및 상태.
• Direct Buffer Count: Agent의 Direct Buffer 개수.
• Direct Buffer Memory: Agent의 Direct Buffer 메모리 사용 현황.
• Mapped Buffer Count: Agent의 Mapped Buffer 개수.
• Loaded Classes: Agent에 로드된 클래스의 총 개수.

 

 

 

 

 

 

 

 

 

 

5. 마치며

Pinpoint는 병목 구간을 파악하거나 비효율적인 메소드와 쿼리를 분석하기에 적합해보였다. 또한 Zipkin 처럼 분산 추적도 가능할 뿐더러 JVM 관련한 리소스 사용 정보 또한 확인할 수 있다. 

 

특히, Agent 를 사용해서 데이터를 PUSH 해주기 때문에 MSA 환경에서도 적합했고, Product 코드 수정 없이 구축이 가능하다는 점이 큰 장점인 것 같다.

 

알림 기능은 다뤄보지 않았지만 이메일, SMS, 웹훅을 통해 전송할 수 있도록 기능을 제공해준다. 

 

 

 

 

 

 

 

 

 

 

+ 모니터링, WAS를 하나의 서버에서 구축하고 싶다면

Pinpoint 를 도입하기 위해선 Java 버전이 굉장히 중요하다. 

이것저것 다 테스트해본 결과 Java8로 띄우는게 Hbase, Pinpoint(Collector, Web)이랑 찰떡이다. 

 

하나의 서버에서 Pinpoint 툴과 WAS를 띄우고 싶다면 아래와 같이 Java Version을 명시적으로 작성하고 실행해주면 된다. 

JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 ./hbase-1.2.7/bin/start-hbase.sh

 

start-hbase.sh 같이 쉘 스크립트는 쉘 스크립트 상단에 JAVA_HOME을 따로 지정해줘도 똑같이 동작한다. 

 

 

 

 

나는 Pinpoint에 필요한 앱들을 실행하는 start-pinpoint-monitoring.sh 라는 쉘 스크립트를 작성하여 관리하려 한다. 

#!/bin/bash

# Java 8 경로 설정
JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
export JAVA_HOME
export PATH=$JAVA_HOME/bin:$PATH

# 로그 디렉토리 생성
LOG_DIR="./logs"
mkdir -p $LOG_DIR

# 1. Start HBase
echo "Starting HBase..."
JAVA_HOME=$JAVA_HOME ./hbase-1.2.7/bin/start-hbase.sh > $LOG_DIR/hbase-start.log 2>&1
if [ $? -ne 0 ]; then
  echo "HBase failed to start. Check the log: $LOG_DIR/hbase-start.log"
  exit 1
fi
echo "HBase started successfully."

# 2. Run HBase shell to create tables
echo "Running HBase shell for table creation..."
JAVA_HOME=$JAVA_HOME ./hbase-1.2.7/bin/hbase shell hbase-create.hbase > $LOG_DIR/hbase-create.log 2>&1
if [ $? -ne 0 ]; then
  echo "HBase shell execution failed. Check the log: $LOG_DIR/hbase-create.log"
  exit 1
fi
echo "HBase tables created successfully."

# 3. Start Pinpoint Collector
echo "Starting Pinpoint Collector..."
nohup $JAVA_HOME/bin/java -jar -Dpinpoint.zookeeper.address=localhost pinpoint-collector-boot-2.2.2.jar > $LOG_DIR/collector.log 2> $LOG_DIR/collector-error.log &
if [ $? -ne 0 ]; then
  echo "Pinpoint Collector failed to start. Check the log: $LOG_DIR/collector-error.log"
  exit 1
fi
echo "Pinpoint Collector started successfully."

# 4. Start Pinpoint Web
echo "Starting Pinpoint Web..."
nohup $JAVA_HOME/bin/java -jar -Dpinpoint.zookeeper.address=localhost pinpoint-web-boot-2.2.2.jar > $LOG_DIR/web.log 2> $LOG_DIR/web-error.log &
if [ $? -ne 0 ]; then
  echo "Pinpoint Web failed to start. Check the log: $LOG_DIR/web-error.log"
  exit 1
fi
echo "Pinpoint Web started successfully."

echo "All services started successfully."

 

 

참고로 패키지 구조는 다음과 같다.