[infra] Pinpoint 설치 (with.mac, docker)

Pinpoint 란

Pinpoint는 네이버(Naver) 에서 개발한 APM (Application Performance Monitoring) 시스템으로, 분산 시스템 환경에서 각 애플리케이션의 성능과 흐름을 시각적으로 분석하고 모니터링할 수 있는 오픈소스 솔루션이다. 

Java, Spring, Spring Boot 기반의 서비스는 물론, 최근에는 Python, Node.js 등의 환경도 일부 지원하며, 다양한 플러그인으로 확장이 가능하다.

---

APM 이란

APM(Application Performance Monitoring) 은 애플리케이션의 성능을 실시간으로 모니터링하고, 병목 현상, 예외, 지연 등을 추적하여 운영 중 발생할 수 있는 문제를 조기에 감지하고 대응할 수 있도록 도와주는 시스템이다.

APM 종류

Pinpoint - 오픈소스 / 한국 개발사 / Spring 기반에 최적화

Scouter - 오픈소스 / JVM 중심 / 가볍고 빠름

SkyWalking - CNCF 소속 오픈소스 / 다양한 언어 지원 / Elastic, Kafka 기반

New Relic - 상용 / 글로벌 / 다양한 플랫폼 지원 / 강력한 UI

Datadog APM - 상용 / 통합 모니터링 툴 / 클라우드 네이티브 환경에 적합

왜 필요 합니까 ?

대규모 트래픽, 마이크로서비스 아키텍처(MSA), 외부 API 연동이 증가하면서 서비스 운영자는 다음과 같은 고민에 직면한다

• 요청이 느려지면 어디서 병목이 발생하는가?
• 서비스 장애는 왜 발생했는가?
• 어떤 API나 DB 쿼리가 가장 오래 걸리는가?
• 특정 사용자나 서버에서만 발생하는 오류는 무엇인가?

---

🧱 Pinpoint 아키텍처 이해

Pinpoint는 크게 다음 3개의 컴포넌트로 구성되어 있다:

1. Collector - 에이전트로부터 데이터를 수신
2. Web - UI 및 시각화
3. Agent - 대상 애플리케이션에 설치하여 성능 데이터 수집

🪏 설치 환경

• Macbook pro M4
• Java 21
• Spirng 3.x
• 16GB 메모리 이상 (Collector + HBase + Web 실행 기준)

꽤 무겁다.... 주키퍼 3 , h-base, redis, mysql, batch .. 등이 합께 설치 된다.

https://github.com/pinpoint-apm/pinpoint-docker

GitHub - pinpoint-apm/pinpoint-docker: Official Dockerized components of the Pinpoint

---

설치 - Collector And ....

git clone https://github.com/pinpoint-apm/pinpoint-docker.git
cd pinpoint-docker
docker-compose pull
docker-compose -f docker-compose.yml -f docker-compose-metric.yml up -d

공식 docker-compose.yml를 받았다면 pinpoint-agent,  pinpoint-quickstart 를 제거 후 설치 해준다.

MAC 용 docker-compose

공식 깃허브에서 설치가 가능 하지만 MAC 의 경우, HBase 가 Arm64 를 지원하지 않아, 오류를 뱉는다.

services:
  pinpoint-hbase:
    container_name: "${PINPOINT_HBASE_NAME}"
    image: "pinpointdocker/pinpoint-hbase:2.5.4"
    networks:
      - pinpoint
    environment:
      - AGENTINFO_TTL=${AGENTINFO_TTL}
      - AGENTSTATV2_TTL=${AGENTSTATV2_TTL}
      - APPSTATAGGRE_TTL=${APPSTATAGGRE_TTL}
      - APPINDEX_TTL=${APPINDEX_TTL}
      - AGENTLIFECYCLE_TTL=${AGENTLIFECYCLE_TTL}
      - AGENTEVENT_TTL=${AGENTEVENT_TTL}
      - STRINGMETADATA_TTL=${STRINGMETADATA_TTL}
      - APIMETADATA_TTL=${APIMETADATA_TTL}
      - SQLMETADATA_TTL=${SQLMETADATA_TTL}
      - TRACEV2_TTL=${TRACEV2_TTL}
      - APPTRACEINDEX_TTL=${APPTRACEINDEX_TTL}
      - APPMAPSTATCALLERV2_TTL=${APPMAPSTATCALLERV2_TTL}
      - APPMAPSTATCALLEV2_TTL=${APPMAPSTATCALLEV2_TTL}
      - APPMAPSTATSELFV2_TTL=${APPMAPSTATSELFV2_TTL}
      - HOSTAPPMAPV2_TTL=${HOSTAPPMAPV2_TTL}
    volumes:
      - hbase_data:/home/pinpoint/hbase
      - /home/pinpoint/zookeeper
    expose:
      # HBase Master API port
      - "60000"
      # HBase Master Web UI
      - "16010"
      # Regionserver API port
      - "60020"
      # HBase Regionserver web UI
      - "16030"
    ports:
      - "60000:60000"
      - "16010:16010"
      - "60020:60020"
      - "16030:16030"
    restart: always
    depends_on:
      - zoo1

  pinpoint-mysql:
    container_name: pinpoint-mysql
    image: mysql:8.0
    restart: "no"
    hostname: pinpoint-mysql
    entrypoint: > 
      sh -c "
      curl -SL "https://raw.githubusercontent.com/pinpoint-apm/pinpoint/2.5.4/web/src/main/resources/sql/CreateTableStatement-mysql.sql" -o /docker-entrypoint-initdb.d/CreateTableStatement-mysql.sql &&
      curl -SL "https://raw.githubusercontent.com/pinpoint-apm/pinpoint/2.5.4/web/src/main/resources/sql/SpringBatchJobRepositorySchema-mysql.sql" -o /docker-entrypoint-initdb.d/SpringBatchJobRepositorySchema-mysql.sql &&
      sed -i '/^--/d' /docker-entrypoint-initdb.d/CreateTableStatement-mysql.sql &&
      sed -i '/^--/d' /docker-entrypoint-initdb.d/SpringBatchJobRepositorySchema-mysql.sql &&
      docker-entrypoint.sh mysqld
      "
    ports:
      - "3306:3306"
    environment:
      - PINPOINT_VERSION=2.5.4
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_USER=${MYSQL_USER}
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}

    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - pinpoint

  pinpoint-web:
    container_name: "${PINPOINT_WEB_NAME}"
    image: "pinpointdocker/pinpoint-web:2.5.4"

    depends_on:
      - pinpoint-hbase
      - pinpoint-mysql
      - zoo1
      - redis
    restart: always
    expose:
      - "9997"
    ports:
      - "9997:9997"
      - "${WEB_SERVER_PORT:-8080}:8080"
    environment:
      - WEB_SERVER_PORT=${WEB_SERVER_PORT}
      - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES}
      - PINPOINT_ZOOKEEPER_ADDRESS=${PINPOINT_ZOOKEEPER_ADDRESS}
      - CLUSTER_ENABLE=${CLUSTER_ENABLE}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - CONFIG_SENDUSAGE=${CONFIG_SENDUSAGE}
      - LOGGING_LEVEL_ROOT=${WEB_LOGGING_LEVEL_ROOT}
      - CONFIG_SHOW_APPLICATIONSTAT=${CONFIG_SHOW_APPLICATIONSTAT}
      - JDBC_DRIVERCLASSNAME=${JDBC_DRIVERCLASSNAME}
      - JDBC_URL=${SPRING_DATASOURCE_HIKARI_JDBCURL}
      - JDBC_USERNAME=${SPRING_DATASOURCE_HIKARI_USERNAME}
      - JDBC_PASSWORD=${SPRING_DATASOURCE_HIKARI_PASSWORD}
      - SPRING_DATASOURCE_HIKARI_JDBCURL=${SPRING_DATASOURCE_HIKARI_JDBCURL}
      - SPRING_DATASOURCE_HIKARI_USERNAME=${SPRING_DATASOURCE_HIKARI_USERNAME}
      - SPRING_DATASOURCE_HIKARI_PASSWORD=${SPRING_DATASOURCE_HIKARI_PASSWORD}
      - SPRING_METADATASOURCE_HIKARI_JDBCURL=${SPRING_METADATASOURCE_HIKARI_JDBCURL}
      - SPRING_METADATASOURCE_HIKARI_USERNAME=${SPRING_METADATASOURCE_HIKARI_USERNAME}
      - SPRING_METADATASOURCE_HIKARI_PASSWORD=${SPRING_METADATASOURCE_HIKARI_PASSWORD}
      - SPRING_DATA_REDIS_HOST=${SPRING_DATA_REDIS_HOST}
      - SPRING_DATA_REDIS_PORT=${SPRING_DATA_REDIS_PORT}
      - SPRING_DATA_REDIS_USERNAME=${SPRING_DATA_REDIS_USERNAME}
      - SPRING_DATA_REDIS_PASSWORD=${SPRING_DATA_REDIS_PASSWORD}
      - PINPOINT_MODULES_WEB_LOGIN=${PINPOINT_MODULES_WEB_LOGIN}
      - WEB_SECURITY_AUTH_USER=${WEB_SECURITY_AUTH_USER}
      - WEB_SECURITY_AUTH_ADMIN=${WEB_SECURITY_AUTH_ADMIN}
      - WEB_SECURITY_AUTH_JWT_SECRETKEY=${WEB_SECURITY_AUTH_JWT_SECRETKEY}

    links:
      - "pinpoint-mysql:pinpoint-mysql"
    networks:
      - pinpoint

  pinpoint-collector:
    container_name: "${PINPOINT_COLLECTOR_NAME}"
    image: "pinpointdocker/pinpoint-collector:2.5.4"

    depends_on:
      - pinpoint-hbase
      - zoo1
      - redis
    restart: always
    expose:
      - "9991"
      - "9992"
      - "9993"
      - "9994"
      - "9995"
      - "9996"
    ports:
      - "${COLLECTOR_RECEIVER_GRPC_AGENT_PORT:-9991}:9991/tcp"
      - "${COLLECTOR_RECEIVER_GRPC_STAT_PORT:-9992}:9992/tcp"
      - "${COLLECTOR_RECEIVER_GRPC_SPAN_PORT:-9993}:9993/tcp"
      - "${COLLECTOR_RECEIVER_BASE_PORT:-9994}:9994"
      - "${COLLECTOR_RECEIVER_STAT_UDP_PORT:-9995}:9995/tcp"
      - "${COLLECTOR_RECEIVER_SPAN_UDP_PORT:-9996}:9996/tcp"
      - "${COLLECTOR_RECEIVER_STAT_UDP_PORT:-9995}:9995/udp"
      - "${COLLECTOR_RECEIVER_SPAN_UDP_PORT:-9996}:9996/udp"
    networks:
      pinpoint:
        ipv4_address: ${COLLECTOR_FIXED_IP}
    environment:
      - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES}
      - PINPOINT_ZOOKEEPER_ADDRESS=${PINPOINT_ZOOKEEPER_ADDRESS}
      - CLUSTER_ENABLE=${CLUSTER_ENABLE}
      - LOGGING_LEVEL_ROOT=${COLLECTOR_LOGGING_LEVEL_ROOT}
      - FLINK_CLUSTER_ENABLE=${FLINK_CLUSTER_ENABLE}
      - FLINK_CLUSTER_ZOOKEEPER_ADDRESS=${FLINK_CLUSTER_ZOOKEEPER_ADDRESS}
      - SPRING_DATA_REDIS_HOST=${SPRING_DATA_REDIS_HOST}
      - SPRING_DATA_REDIS_PORT=${SPRING_DATA_REDIS_PORT}
      - SPRING_DATA_REDIS_USERNAME=${SPRING_DATA_REDIS_USERNAME}
      - SPRING_DATA_REDIS_PASSWORD=${SPRING_DATA_REDIS_PASSWORD}

  pinpoint-batch:
    container_name: "${PINPOINT_BATCH_NAME}"
    image: "pinpointdocker/pinpoint-batch:2.5.4"
    depends_on:
      - pinpoint-hbase
      - pinpoint-mysql
      - zoo1
    restart: always
    environment:
      - BATCH_SERVER_PORT=${BATCH_SERVER_PORT}
      - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES}
      - PINPOINT_ZOOKEEPER_ADDRESS=${PINPOINT_ZOOKEEPER_ADDRESS}
      - CLUSTER_ENABLE=${CLUSTER_ENABLE}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - CONFIG_SENDUSAGE=${CONFIG_SENDUSAGE}
      - LOGGING_LEVEL_ROOT=${BATCH_LOGGING_LEVEL_ROOT}
      - CONFIG_SHOW_APPLICATIONSTAT=${CONFIG_SHOW_APPLICATIONSTAT}
      - BATCH_FLINK_SERVER=${BATCH_FLINK_SERVER}
      - JDBC_DRIVERCLASSNAME=${JDBC_DRIVERCLASSNAME}
      - JDBC_URL=${SPRING_DATASOURCE_HIKARI_JDBCURL}
      - JDBC_USERNAME=${SPRING_DATASOURCE_HIKARI_USERNAME}
      - JDBC_PASSWORD=${SPRING_DATASOURCE_HIKARI_PASSWORD}
      - SPRING_DATASOURCE_HIKARI_JDBCURL=${SPRING_DATASOURCE_HIKARI_JDBCURL}
      - SPRING_DATASOURCE_HIKARI_USERNAME=${SPRING_DATASOURCE_HIKARI_USERNAME}
      - SPRING_DATASOURCE_HIKARI_PASSWORD=${SPRING_DATASOURCE_HIKARI_PASSWORD}
      - SPRING_METADATASOURCE_HIKARI_JDBCURL=${SPRING_METADATASOURCE_HIKARI_JDBCURL}
      - SPRING_METADATASOURCE_HIKARI_USERNAME=${SPRING_METADATASOURCE_HIKARI_USERNAME}
      - SPRING_METADATASOURCE_HIKARI_PASSWORD=${SPRING_METADATASOURCE_HIKARI_PASSWORD}
      - ALARM_MAIL_SERVER_URL=${ALARM_MAIL_SERVER_URL}
      - ALARM_MAIL_SERVER_PORT=${ALARM_MAIL_SERVER_PORT}
      - ALARM_MAIL_SERVER_USERNAME=${ALARM_MAIL_SERVER_USERNAME}
      - ALARM_MAIL_SERVER_PASSWORD=${ALARM_MAIL_SERVER_PASSWORD}
      - ALARM_MAIL_SENDER_ADDRESS=${ALARM_MAIL_SENDER_ADDRESS}
      - ALARM_MAIL_TRANSPORT_PROTOCOL=${ALARM_MAIL_TRANSPORT_PROTOCOL}
      - ALARM_MAIL_SMTP_PORT=${ALARM_MAIL_SMTP_PORT}
      - ALARM_MAIL_SMTP_AUTH=${ALARM_MAIL_SMTP_AUTH}
      - ALARM_MAIL_SMTP_STARTTLS_ENABLE=${ALARM_MAIL_SMTP_STARTTLS_ENABLE}
      - ALARM_MAIL_SMTP_STARTTLS_REQUIRED=${ALARM_MAIL_SMTP_STARTTLS_REQUIRED}
      - ALARM_MAIL_DEBUG=${ALARM_MAIL_DEBUG}
    links:
      - "pinpoint-mysql:pinpoint-mysql"
    networks:
      - pinpoint


  #zookeepers
  zoo1:
    image: zookeeper:3.4.13
    restart: always
    hostname: zoo1
    expose:
      - "2181"
      - "2888"
      - "3888"
    ports:
      - "2181"
    environment:
      ZOO_MY_ID: 1
      ZOO_SERVERS: server.1=0.0.0.0:2888:3888 server.2=zoo2:2888:3888 server.3=zoo3:2888:3888
    networks:
      - pinpoint

  zoo2:
    image: zookeeper:3.4.13
    restart: always
    hostname: zoo2
    expose:
      - "2181"
      - "2888"
      - "3888"
    ports:
      - "2181"
    environment:
      ZOO_MY_ID: 2
      ZOO_SERVERS: server.1=zoo1:2888:3888 server.2=0.0.0.0:2888:3888 server.3=zoo3:2888:3888
    networks:
      - pinpoint

  zoo3:
    image: zookeeper:3.4.13
    restart: always
    hostname: zoo3
    expose:
      - "2181"
      - "2888"
      - "3888"
    ports:
      - "2181"
    environment:
      ZOO_MY_ID: 3
      ZOO_SERVERS: server.1=zoo1:2888:3888 server.2=zoo2:2888:3888 server.3=0.0.0.0:2888:3888
    networks:
      - pinpoint

  ##flink
  jobmanager:
    container_name: "${PINPOINT_FLINK_NAME}-jobmanager"
    image: "pinpointdocker/pinpoint-flink:2.5.4"
    expose:
      - "6123"
    ports:
      - "${FLINK_WEB_PORT:-8081}:8081"
    command: standalone-job -p 1 pinpoint-flink-job.jar -spring.profiles.active release
    environment:
      - JOB_MANAGER_RPC_ADDRESS=jobmanager
      - PINPOINT_ZOOKEEPER_ADDRESS=${PINPOINT_ZOOKEEPER_ADDRESS}
    networks:
      - pinpoint
    depends_on:
      - zoo1

  taskmanager:
    container_name: "${PINPOINT_FLINK_NAME}-taskmanager"
    image: "pinpointdocker/pinpoint-flink:2.5.4"
    expose:
      - "6121"
      - "6122"
      - "19994"
    ports:
      - "6121:6121"
      - "6122:6122"
      - "19994:19994"
    depends_on:
      - zoo1
      - jobmanager
    command: taskmanager
    links:
      - "jobmanager:jobmanager"
    environment:
      - JOB_MANAGER_RPC_ADDRESS=jobmanager
    networks:
      - pinpoint

  redis:
    image: redis:7.0.14
    restart: always
    hostname: pinpoint-redis
    ports:
      - "6379:6379"
    networks:
      - pinpoint

    
volumes:
  data-volume:
  mysql_data:
  hbase_data:

networks:
  pinpoint:
    driver: bridge
    ipam:
      config:
        - subnet: ${PINPOINT_NETWORK_SUBNET}

설치를 완료 하고 

http://localhost:8080 를 들어가면 pinpoint-web 을 볼 수 있다.

포트 개방

각 에이전트는 9991 / 9992 / 9993 포트로 콜렉터에게 데이터를 보내준다.

공유기를 사용한다면 포트포워딩을 잊지말고 해준다.

---

Agent 설치

Pinpoint Agent는 Spring 애플리케이션과 함께 JVM 위에서 동작하는 경량 프로세스로,

애플리케이션 내부에서 발생하는 트랜잭션, 메서드 호출, SQL 쿼리 실행, 외부 API 호출 등의 이벤트를

가로채고 수집하여 Pinpoint Collector로 전송하는 역할을 한다.

# 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
 
# 앞에서 구성한 collector 의 ip로 수정
profiler.transport.grpc.collector.ip={hostIP}

필자는 JAVA 21 환경을 사용한다. 

설치를 완료한 디렉토리 구조이다.

/app
├── app.jar
├── docker-compose.yml
└── pinpoint-agent-3.0.1  <- 방금 설치한 agent 디렉토리

services:
  app:
    image: eclipse-temurin:21-jdk
    container_name: sprint-app
    restart: unless-stopped
    volumes:
      - .:/app:rw
    command: >
      java -server -Xms4g -Xmx8g -Xss512k
      # 추가 된 Pinpoint-Agent 설정
      -javaagent:/app/pinpoint-agent-3.0.1/pinpoint-bootstrap-3.0.1.jar
      -Dpinpoint.config=/app/pinpoint-agent-3.0.1/pinpoint-root.config
      -Dpinpoint.agentId=spring-MainInstance
      -Dpinpoint.applicationName=springServer
      # 기존 Spring 설정
      -Dfile.encoding=UTF-8
      -Dspring.profiles.active=production
      -jar /app/app.jar
    ports:
      - "6661:6661"
    environment:
      - TZ=Asia/Seoul
    networks:
      - app-network

networks:
  app-network:
    external: true

docker compose up -d

 

실행을 해주면

Spring Application 이 뜨기 전에 아래와 같이 핀포인트 에이전트가 같이 실행 되는것을 확인 할 수 있다.