Elastic Agent & APM

본글에서 사용된 모든 코드는
Backend Github Code
Terraform Code
를 통해 확인하실 수 있습니다.

작업 준비

작업 순서

성능 모니터링 할 Application Server , Elasitc Agent 구성
Elastic Search 설치
Fleet 서버 및 Agent Policy 생성
Elastic APM Integeration 추가

사용할 도구

Docker / Docker compose
Spring Boot (3.xx)
Elastic Search Stack (9.xx)
Elastic Agent (9.xx)

상황에 따라, 더 낮은 버전을 채택하셔도 상관없습니다.
현재 작성일 기준, 9.xx 버전대가 가장 최신버젼입니다.

Application server 기동

❗ Docker 에 대한 내용이 아니므로, 내용 중 사용되는 docker network, volumn mount등등 은 전혀 설명하지 않습니다.

성능을 모니터링 할, Application 을 APM Agent 이 데이터를 수집할 수 있도록 구성합니다.

현재 글에서는, Spring Boot 를 활용합니다.

설치 및 기동

Elastic 에서는 APM Agent 를 위한 다양한 솔루션을 개발해두었습니다. 공식문서

저희는 Spring Boot 서버에 적용할 것이고, JAVA 이기 때문에, Java 용 APM Agent 를 설치하여 사용합니다. 공식문서-JAVA

또한 저희는 Docker 로 실행할 것이기 때문에, 해당 문서를 참조하여 루트 경로에 Dockerfile 을 작성해줍니다. 공식문서-JAVA-Manual-setup

./Dockerfile

# 1. Build Stage
FROM eclipse-temurin:21-jdk AS builder
WORKDIR /app

COPY gradlew ./
COPY gradle gradle
COPY build.gradle settings.gradle ./
RUN chmod +x ./gradlew
RUN ./gradlew dependencies --no-daemon || true

COPY src src
RUN ./gradlew clean build -x test --no-daemon

# 2. Run Stage
FROM eclipse-temurin:21-jre
WORKDIR /app

ENV TZ=Asia/Seoul
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

COPY --from=docker.elastic.co/observability/apm-agent-java:latest /usr/agent/elastic-apm-agent.jar /elastic-apm-agent.jar
COPY --from=builder /app/build/libs/*.jar app.jar
EXPOSE 8080

ENTRYPOINT ["sh", "-c", "exec java -javaagent:/elastic-apm-agent.jar -Duser.timezone=Asia/Seoul -jar app.jar --spring.profiles.active=${SPRING_PROFILES_ACTIVE:-prod}"]

COPY --from=docker.elastic.co/observability/apm-agent-java:latest /usr/agent/elastic-apm-agent.jar /elastic-apm-agent.jar 을 통해, java 용 elastic apm agent 를 다운로드 해주고, java -javaagent:/elastic-apm-agent.jar을 통해 실행합니다.

해당 Dockerfile 을 통해 Build / Run 해도 상관없지만, 편의를 위해서 자동화 스크립트를 하나 작성합니다.

./docker/application/run-local.sh

#!/bin/bash

#######################################################
# 로컬에서 Spring Boot 를 Docker 로 기동하기 위한 스크립트 #
# 사용하기 위해서는, .env.local 파일이 필요합니다. #
# 필요하다면 ksu9801@gmail.com 으로 문의 하시기 바랍니다. #
#######################################################

set -e

ENV_FILE=.env.local

echo ">>> Stop & remove existing container (if exists)"
docker rm -f baekgwa-server 2>/dev/null || true

echo ">>> Remove existing image (if exists)"
docker rmi baekgwa-server:local 2>/dev/null || true

echo ">>> Docker image build"
docker build -t baekgwa-server:local ../..

echo ">>> Run container"
docker run -d \
  --name baekgwa-server \
  --network baekgwa-network \
  -p 8080:8080 \
  --env-file ${ENV_FILE} \
  baekgwa-server:local

echo ">>> Done"

다음으로, .env.local 파일을 작성해줍니다.

해당 파일에 들어가는 내용은, 본인 프로젝트에 맞게 필요한 환경 변수를 넣어주시면 됩니다.
DB 연결을 위한 URL 이나, Redis 주소, Auth 정보 등등...

# 설치하는데 필요한 다양한 환경 변수들...

ELASTIC_APM_SERVICE_NAME=baekgwa-blog-server
ELASTIC_APM_ENVIRONMENT=local
ELASTIC_APM_SERVER_URL=http://elastic-agent:8200
ELASTIC_APM_SECRET_TOKEN=baekgwa@apmsecret
ELASTIC_APM_APPLICATION_PACKAGES=baekgwa.blogserver
ELASTIC_APM_CAPTURE_SPAN_STACK_TRACES=true
ELASTIC_APM_SPAN_STACK_TRACE_MIN_DURATION=5ms

해당 환경 변수들은 추후에 생성할 Elastic Agent 와 통신할 때 사용할 환경 변수들 입니다.

작성된 내용은 다음 표를 보고 간단히 이해하시면 됩니다.

항목	역할
`SERVICE_NAME`	서비스 식별자
`ENVIRONMENT`	환경 구분
`SERVER_URL`	APM 데이터 수신 대상
`SECRET_TOKEN`	인증
`APPLICATION_PACKAGES`	내 코드 구분
`CAPTURE_SPAN_STACK_TRACES`	호출 스택 수집 여부
`SPAN_STACK_TRACE_MIN_DURATION`	스택 수집 기준 시간

더 다양한 설정은, 공식 문서 를 통해 확인하실 수 있습니다.

작성이 완료되었다면, run-local.sh 를 실행해 정상적으로 스프링 부트 서버가 띄워짐을 확인합니다.

정상적으로 기동 되었다면, 스프링 컨텍스트 관련 로그가 뜨기 전, elastic apm agent 부터 로그가 나올 것 입니다.

2026-01-15 16:27:21,736 [main] INFO  co.elastic.apm.agent.util.JmxUtils - Found JVM-specific OperatingSystemMXBean interface: com.sun.management.OperatingSystemMXBean
2026-01-15 16:27:21,778 [main] INFO  co.elastic.apm.agent.util.JmxUtils - Found JVM-specific ThreadMXBean interface: com.sun.management.ThreadMXBean
2026-01-15 16:27:21,792 [main] INFO  co.elastic.apm.agent.configuration.StartupInfo - Starting Elastic APM 1.55.3 as baekgwa-blog-server (0.0.1) on Java 21.0.9 Runtime version: 21.0.9+10-LTS VM version: 21.0.9+10-LTS (Eclipse Adoptium) Linux 5.15.146.1-microsoft-standard-WSL2
2026-01-15 16:27:21,792 [main] INFO  co.elastic.apm.agent.configuration.StartupInfo - service_name: 'baekgwa-blog-server' (source: Environment Variables)
2026-01-15 16:27:21,793 [main] INFO  co.elastic.apm.agent.configuration.StartupInfo - environment: 'local' (source: Environment Variables)
2026-01-15 16:27:21,793 [main] INFO  co.elastic.apm.agent.configuration.StartupInfo - secret_token: 'XXXX' (source: Environment Variables)
2026-01-15 16:27:21,793 [main] INFO  co.elastic.apm.agent.configuration.StartupInfo - server_url: 'http://elastic-agent:8200' (source: Environment Variables)
2026-01-15 16:27:21,794 [main] INFO  co.elastic.apm.agent.configuration.StartupInfo - application_packages: 'baekgwa.blogserver' (source: Environment Variables)
2026-01-15 16:27:23,361 [main] INFO  co.elastic.apm.agent.impl.ElasticApmTracer - Tracer switched to RUNNING state
2026-01-15 16:27:26,699 [elastic-apm-server-healthcheck] WARN  co.elastic.apm.agent.report.ApmServerHealthChecker - Elastic APM server http://elastic-agent:8200/ is not available (elastic-agent)
2026-01-15 16:27:26,704 [elastic-apm-remote-config-poller] ERROR co.elastic.apm.agent.configuration.ApmServerConfigurationSource - elastic-agent

현재, elastic-agent:8200 으로 연결을 시도하고 있고, 사용 가능하지 않다고 Error 가 뜨고있습니다.

아직 Agent 를 띄우지 않았으니 너무 정상입니다.

현재 사진에는 Logstash 관련 에러가 발생하는데, 제 서버에 Logback 을 Logstatsh 와 연결하는 코드가 들어가 있어 그렇습니다.
본 글 APM 관련된 내용은 아니니, 아마 뜨지 않을 것 입니다.

주요 확인 파트는, 저희가 위에서 환경 변수로 넣었던 부분이 모두 잘 적용된 모습을 확인하시면 됩니다.

Elastic Stack 설치

앞선 글 에서 설명하였 듯, 현재 docker 내부에서 수집중인 데이터를 전달 받아, Elasticsearch 에 저장할 APM integration 이 필요합니다.

정상적으로 기동하기 위해서는, 먼저 Fleet Server 가 필요하고, 이를 위해선 또 ELK 스택이 먼저 구성되어야 합니다.

ELK 중, Logstash 는 당연히 필수가 아닙니다.

Docker compose 파일 생성

ELK 스택을 docker compose 로 설치해줍니다.

./docker/elk/elk-docker-compose.yml

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.2.0
    container_name: elasticsearch
    networks:
      - baekgwa-network
    ports:
      - ${ELASTIC_SEARCH_PORT}:9200
    volumes:
      - es-data:/usr/share/elasticsearch/data
      - ./elastic/init-kibana-user.sh:/usr/share/elasticsearch/config/init/init-kibana-user.sh
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS=-Xms1g -Xmx1g
      - ELASTIC_PASSWORD=${ELASTICSEARCH_PASSWORD}
      - xpack.security.enabled=true
      - xpack.security.http.ssl.enabled=false
      # Kibana -> Elastic 접속을 위한 회원 정보, 기존 elastic system 계정을 사용하는 방법은 막힘
      - KIBANA_USERNAME=${KIBANA_USERNAME}
      - KIBANA_PASSWORD=${KIBANA_PASSWORD}
    entrypoint:
      [
        "/bin/bash",
        "-c",
        "bash /usr/share/elasticsearch/config/init/init-kibana-user.sh && /usr/local/bin/docker-entrypoint.sh"
      ]
    healthcheck:
      test: [ "CMD-SHELL", "curl -s -f -u elastic:${ELASTICSEARCH_PASSWORD} http://localhost:9200/_cluster/health" ]
      interval: 10s
      timeout: 10s
      retries: 10
    restart: always

  kibana:
    image: docker.elastic.co/kibana/kibana:9.2.0
    container_name: kibana
    networks:
      - baekgwa-network
    ports:
      - ${KIBANA_PORT}:5601
    volumes:
      - kibana-data:/usr/share/kibana/data
    environment:
      - ELASTICSEARCH_HOSTS=${ELASTICSEARCH_HOSTS}
      # Kibana -> Elastic 으로 접속할 떄 사용할 유저는, "kibana_system" 권한을 가지고 있는 새로 만든 유저
      - ELASTICSEARCH_USERNAME=${KIBANA_USERNAME}
      - ELASTICSEARCH_PASSWORD=${KIBANA_PASSWORD}
      - SERVER_PUBLICBASEURL=https://kibana.baekgwa.site
      - XPACK_ENCRYPTEDSAVEDOBJECTS_ENCRYPTIONKEY=${KIBANA_ENCRYPTED_SAVED_OBJECTS_ENCRYPTION_KEY}
    restart: always
    depends_on:
      elasticsearch:
        condition: service_healthy

volumes:
  es-data:
    driver: local
  kibana-data:
    driver: local

networks:
  baekgwa-network:
    external: true

다음으로는, Kibana 에서, Elastic Search 에 접근할 수 있는 권한을 가진 유저를 생성해줄 스크립트를 하나 작성합니다.

❗ 최근 ELK 스택에서는, Elastic -> Kibana 접속을 위해 elastic supper 계정을 사용하게 되면 오류를 발생하게 됩니다.
FATAL  Error: [config validation of [elasticsearch].username]: value of "elastic" is forbidden. This is a superuser account that cannot write to system indices that Kibana needs to function. Use a service account token instead. Learn more: https://www.elastic.co/guide/en/elasticsearch/reference/8.0/service-accounts.html
때문에, 별도의 elastic 접속용 계정을 만들어 사용해야 합니다.

❗ XPACK_ENCRYPTEDSAVEDOBJECTS_ENCRYPTIONKEY 옵션은 뭔가요?
Kibana 에서, 민감한 데이터를 안전하게 암호화 하기 위한 키 입니다.
저희는 Fleet을 통해 이러한 Agent 들을 관리할 것인데, 이 기능을 사용하려면 해당 저장 객체 암호화 키를 반드시 설정하라고 공식문서에 명시되어 있습니다.
공식문서

./docker/elk/elastic/init-kibana-user.sh

#!/bin/bash

# 환경변수로 받은 KIBANA_USER 계정 생성 (이미 존재하면 건너뜀)
if ! bin/elasticsearch-users list | grep -q "^${KIBANA_USERNAME} "; then
  echo "Init Script: Creating Kibana user: ${KIBANA_USERNAME}"
  bin/elasticsearch-users useradd ${KIBANA_USERNAME} -p ${KIBANA_PASSWORD} -r kibana_system
else
  echo "Init Script: Kibana user ${KIBANA_USERNAME} already exists."
fi

마지막으로, 필요한 환경 변수를 담은 .env 를 추가해줍니다.

./docker/elk/.env

ELASTIC_SEARCH_PORT=9200
KIBANA_PORT=5601
#LOGSTASH_PORT=5044
ELASTIC_APM_PORT=8200
FLEET_SERVER_PORT=8220

ELASTICSEARCH_USERNAME=elastic
ELASTICSEARCH_PASSWORD=elastic@password
ELASTICSEARCH_HOSTS=http://elasticsearch:9200
KIBANA_USERNAME=kibanauser
KIBANA_PASSWORD=kibanauser@password
KIBANA_ENCRYPTED_SAVED_OBJECTS_ENCRYPTION_KEY=32CHARS 이상의 무작위 암호화 키를 넣어주세요!
FLEET_SERVER_SERVICE_TOKEN=NEED_TO_CHANGE
FLEET_ENROLLMENT_TOKEN=NEED_TO_CHANGE

Fleet 이나, APM 관련된 설정은 추후에 필요하지만 작성의 편의를 위해 먼저 작성해서 올려둡니다.

ELK 기동

정상적으로 다 작성하였다면, 컨테이너를 생성합니다.

키바나 페이지(http://localhost:5601/)에 접속해, 저희가 설정한 비밀번호로 접속합니다.

ID : ${ELASTICSEARCH_USERNAME}
PW : ${ELASTICSEARCH_PASSWORD}
위 .env 그대로 사용하셨다면, elastic / elastic@password 입니다.

로그인 후, 첫페이지라면, 환영 페이지가 열리는데 Explore on my own 버튼을 눌러 살포시 메인 메뉴로 나가줍니다.

Fleet 서버 및 Agent Policy 생성

Fleet 서버는, 각각의 Agent 들이 어떤 행동을 할지 결정해주는 관리자 입니다. (관련 글)

Fleet 서버 추가를 위한 구성

현재 버전에서는 간단하게 Fleet Server 를 추가할 수 있게 되어있습니다.

❗ 아직 저희는 Fleet 서버를 설치하지 않았습니다!!

좌측 메뉴(햄버거 아이콘)을 눌러, Management -> Fleet 으로 이동합니다. (링크)

다음으로, Add Fleet Server 를 눌러, Quick Start 로 빠르게 실행하겠습니다.

다음과 같이 작성 후 Generate Fleet Server policy를 눌러줍니다.

자동으로, Fleet Server 를 위한 Policy 를 생성해 주고, Fleet(elastic-agent) 를 위한 service token 과 enrollment token scret 을 생성해줍니다.

다음 화면에서, curl 명령으로 token 을 안내해줍니다.

이전에 작성한 ./docker/elk/.env에 FLEET_SERVER_SERVICE_TOKEN 변수에 넣어줍니다

다음으로 해당 링크 에 접속해, 방금 생성된 Enrollment Token을 동일하게 /docker/elk/.env에 FLEET_ENROLLMENT_TOKEN변수에 넣어줍니다

현재 Kibana UI 에서는, Confirm connection 에서 연결 상태를 계속 대기하고 있을 것 입니다.

기존 docker/elk/elk-docker-compose.yml에서 Elastic Agent container 를 추가해 줍니다.

❓ Fleet 서버를 추가 해야 하는 거 아닌가요? 왜 Elastic Agent을추가하나요?
❗ Elastic Agent 내에, Fleet 기능을 내장하고 있습니다.

docker/elk/elk-docker-compose.yml

  elastic-agent:
    image: docker.elastic.co/elastic-agent/elastic-agent:9.2.3
    container_name: elastic-agent
    networks:
      - baekgwa-network
    ports:
      - ${FLEET_SERVER_PORT}:8220
      - ${ELASTIC_APM_PORT}:8200
    environment:
      - FLEET_SERVER_ENABLE=true
      - FLEET_SERVER_ELASTICSEARCH_HOST=http://elasticsearch:9200
      - ELASTICSEARCH_HOST=http://elasticsearch:9200
      - FLEET_SERVER_POLICY_ID=fleet-server-policy
      #내부 agent 들이 fleet 서버를 바라볼 주소. 현재 fleet server를 elastic-agent container 하나로 관리하기 때문에, 본인 스스로 지칭
      - FLEET_URL=http://elastic-agent:8220
      - FLEET_SERVER_INSECURE_HTTP=true
      - FLEET_SERVER_SERVICE_TOKEN=${FLEET_SERVER_SERVICE_TOKEN}
      - FLEET_ENROLLMENT_TOKEN=${FLEET_ENROLLMENT_TOKEN}
    depends_on:
      elasticsearch:
        condition: service_healthy
      kibana:
        condition: service_started
    restart: always

다음과 같이 작성 후 해당 컨테이너를 실행 시켜 줍니다.

이때, 변수들은 각각 아래의 표를 참고하시기 바랍니다.

환경변수	역할	설명
`FLEET_SERVER_ENABLE`	Fleet Server 활성화	`true`일 경우 해당 Elastic Agent가 Fleet Server 역할을 수행함
`FLEET_SERVER_ELASTICSEARCH_HOST`	Fleet Server → ES 연결	Fleet Server가 정책 / 에이전트 상태 / API Key 등을 저장·조회할 Elasticsearch 주소
`ELASTICSEARCH_HOST`	Agent 기본 ES 연결	Elastic Agent가 내부적으로 사용하는 Elasticsearch 기본 엔드포인트 (Fleet Server에서도 필요)
`FLEET_SERVER_POLICY_ID`	Fleet Server 정책 지정	Fleet Server 자신이 사용할 Agent Policy ID
`FLEET_URL`	Fleet Server 공개 주소	다른 Elastic Agent들이 접속할 Fleet Server 주소현재는 Fleet Server와 Agent를 동일 컨테이너로 쓰므로 자기 자신 주소
`FLEET_SERVER_INSECURE_HTTP`	HTTP 허용 여부	`true`면 TLS 없는 HTTP 허용 (로컬 / 테스트 환경용)
`FLEET_SERVER_SERVICE_TOKEN`	ES 인증 토큰	Fleet Server가 Elasticsearch에 서비스 계정으로 인증할 때 사용하는 토큰
`FLEET_ENROLLMENT_TOKEN`	Agent 등록 토큰	Elastic Agent가 Fleet에 자신을 등록(enroll) 할 때 사용하는 토큰

방금 실행시킨 elastic-agent 컨테이너가 정상적으로 Fleet server 로써 등록이 되면, 다음과 같이 연결이 완료되었다고 화면에 나타납니다.

Continue enrolling eastic agent 버튼을 눌러, 등록을 완료해줍니다.

Fleet -> Elastic search 연결 주소 수정

기본적으로, Fleet 서버는 Agent 들에게 어떤 역할을 수행하면 되는지 알려줍니다.

이 역할들을 Policy 라고 하는데, 이 정보들은 모두 elastic search 에 등록되어있습니다.

따라서, Fleet 에서 Elastic search 를 특정할 주소를 지정해줘야 합니다.

버그인지 아닌지 몰라도, 환경변수로 지정이 가능해야하는데, 지정이 되지 않고 default : localhost:9200 으로 잡히고 있어 해당 과정이 추가되었습니다.

Fleet 화면에서, Settings 탭에서 Outputs 항목에, default 로 내보내고 있는 elastic search 주소를 기존 localhost:9200 에서, http://elasticsearch:9200 으로 변경해줍니다. (링크)

before

after

잠시 1~2분정도 기다리면 Agent 의 상태가 Healthy 로 변경되어 있을 것 입니다.

APM Interagtion 추가

이제 스프링부트에서 데이터를 전송 받을 APM Integeration 을 생성합니다.

APM 추가

좌측 메뉴(햄버거)를 눌러, 제일 하단의 Add Integration 버튼을 눌러 이동합니다. (링크)

APM 을 검색하고 아래의 사진 순서대로 진입합니다.

APM 클릭

Add Integration 클릭

Add Elastic APM 클릭

Add Elastic Apm Integration 추가

Host : 0.0.0.0:8200
URL : http://elastic-agent:8200

Agent Polices

Fleet Server Policy (이전에 자동으로 생성된 Policy)

후, Save and continue

Spring Boot Docker 재실행

스프링 컨테이너를 재실행 합니다.

기존에는, http://elastic-agent:8200 라는곳에 연결할 수 없어 오류가 발생하고 있었습니다.

현재는 다음과 같이 정상적으로 연결된 로그를 확인할 수 있습니다.

2026-01-15 18:47:12,718 [elastic-apm-server-healthcheck] INFO  co.elastic.apm.agent.report.ApmServerHealthChecker - Elastic APM server is available: {  "build_date": "2025-12-16T16:15:36Z",  "build_sha": "c8a34af88824af299811f5e2e5622e63dd31651c",  "publish_ready": true,  "version": "9.2.3"}
2026-01-15 18:47:12,729 [elastic-apm-remote-config-poller] INFO  co.elastic.apm.agent.configuration.ApmServerConfigurationSource - Received new configuration from APM Server: {}

모니터링

이제 실제로, Application 의 성능 기록들이 재대로 로깅되는지 확인해 봅니다.

Service inventory에 접속해서 보면, spring boot inventory 가 남아 있습니다.

접속해서 보면, 정상적으로 APM 이 등록된 것을 확인할 수 있습니다.

[Elastic Stack] Elastic Agent(Fleet)로 Spring Boot APM 연동하기 #2

스택 시리즈🔎 Elastic Search! With Spring