[스프링 핵심 원리와 활용] 섹션9. 액츄에이터(2)

[YuDeokRin]

6️⃣ 헬스 정보

• http://localhost:8080/actuator/health
  • show-details: always는 헬스 정보가 자세하게 나온다.

management:
  endpoint:
    shutdown:
      enabled:  true
    health:
      show-details: always
  endpoints:
    web:
      exposure:
        include: "*"

• 결과

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "H2",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 494384795648,
        "free": 267227369472,
        "threshold": 10485760,
        "path": "/Users/dante/Desktop/DanteFolder/study/actuator/.",
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

• application.yml
  • show-components: always 는 간략하게 상태 정보만 노출

management:
  endpoint:
    shutdown:
      enabled:  true
    health:
      show-components: always
  endpoints:
    web:
      exposure:
        include: "*"

• 실행결과
  • components 옵션은 하나라도 문제가 있으면 전체 상태는 down이 된다.

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP"
    },
    "diskSpace": {
      "status": "UP"
    },
    "ping": {
      "status": "UP"
    }
  }
}

• 참고 - 자세한 헬스 기본 지원 기능, 공식 메뉴얼

https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.health.auto-configured-health-indicators

• 참고 - 헬스 기능 직접 구현하기

https://docs.spring.io/spring-boot/reference/actuator/endpoints.html#actuator.endpoints.health.writing-custom-health-indicators

7️⃣ 애플리케이션 정보

management:
  info:
    java:
      enabled: true
    os:
      enabled: true
  endpoint:
    shutdown:
      enabled: true
    health:
      show-components: always
  #      show-details: always
  endpoints:
    web:
      exposure:
        include: "*"

{
  "app": {
    "name": "hello-actuator",
    "company": "yh"
  },
  "java": {
    "version": "17.0.6",
    "vendor": {
      "name": "Oracle Corporation"
    },
    "runtime": {
      "name": "Java(TM) SE Runtime Environment",
      "version": "17.0.6+9-LTS-190"
    },
    "jvm": {
      "name": "Java HotSpot(TM) 64-Bit Server VM",
      "vendor": "Oracle Corporation",
      "version": "17.0.6+9-LTS-190"
    }
  },
  "os": {
    "name": "Mac OS X",
    "version": "15.6",
    "arch": "aarch64"
  }
}

✅ build

✅ git

• info 실행 결과

{
  "app": {
    "name": "hello-actuator",
    "company": "yh"
  },
  "git": {
    "branch": "main",
    "commit": {
      "id": "5d9bec2",
      "time": "2025-08-22T13:54:36Z"
    }
  },
  "build": {
    "artifact": "actuator",
    "name": "actuator",
    "time": "2025-08-22T13:55:51.654Z",
    "version": "0.0.1-SNAPSHOT",
    "group": "hello"
  },
  "java": {
    "version": "17.0.6",
    "vendor": {
      "name": "Oracle Corporation"
    },
    "runtime": {
      "name": "Java(TM) SE Runtime Environment",
      "version": "17.0.6+9-LTS-190"
    },
    "jvm": {
      "name": "Java HotSpot(TM) 64-Bit Server VM",
      "vendor": "Oracle Corporation",
      "version": "17.0.6+9-LTS-190"
    }
  },
  "os": {
    "name": "Mac OS X",
    "version": "15.6",
    "arch": "aarch64"
  }
}

• git mode에서 fulld을 하면 상세히 볼 수 있다.

management:
  info:
    java:
      enabled: true
    os:
      enabled: true
    env:
      enabled: true
    git:
      mode: "full"

• 실행 결과

{
  "app": {
    "name": "hello-actuator",
    "company": "yh"
  },
  "git": {
    "branch": "main",
    "commit": {
      "time": "2025-08-22T13:54:36Z",
      "message": {
        "full": "start\n",
        "short": "start"
      },
      "id": {
        "describe": "",
        "abbrev": "5d9bec2",
        "full": "5d9bec2b74c831b26569188295ffed4f34e2ca2b"
      },
      "user": {
        "email": "[email protected]",
        "name": "Dante"
      }
    },
  ... 
}

8️⃣ 로거

• loggers 엔드포인트를 사용하면 로깅과 관련된 정보를 확인할 수 있고 실시간으로 변경도 할 수 있다.

• LogController

package hello.controller;

import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Slf4j
@RestController
public class LogController {

    @GetMapping("/log")
    public String log() {
        log.trace("trace log");
        log.debug("debug log");
        log.info("info log");
        log.warn("warn log");
        log.error("error log");

        return "ok";
    }
}

• 실행 결과

2025-08-22T23:12:10.497+09:00  INFO 19478 --- [nio-8080-exec-3] hello.controller.LogController           : info log
2025-08-22T23:12:10.498+09:00  WARN 19478 --- [nio-8080-exec-3] hello.controller.LogController           : warn log
2025-08-22T23:12:10.498+09:00 ERROR 19478 --- [nio-8080-exec-3] hello.controller.LogController           : error log

• application.yml 에서 logging수정
  • hello.controller 패키지와 그 하위는 debug 레벨을 출력하도록 함.

logging:
  level:
    hello.controller: debug

• 실행결과

2025-08-22T23:17:59.118+09:00 DEBUG 24292 --- [nio-8080-exec-1] hello.controller.LogController           : debug log
2025-08-22T23:17:59.119+09:00  INFO 24292 --- [nio-8080-exec-1] hello.controller.LogController           : info log
2025-08-22T23:17:59.119+09:00  WARN 24292 --- [nio-8080-exec-1] hello.controller.LogController           : warn log
2025-08-22T23:17:59.119+09:00 ERROR 24292 --- [nio-8080-exec-1] hello.controller.LogController           : error log

✅ loggers 엔드포인트 호출

• 결과 확인
  • 로그를 별도로 설정하지 않으면 스프링 부트는 기본으로 info를 사용
  • 아래의 결과에서 ROOT는 configuredLevel이 info이다 따라서 그 하위도 info레벨 적용된다.

{
  "levels": [
    "OFF",
    "ERROR",
    "WARN",
    "INFO",
    "DEBUG",
    "TRACE"
  ],
  "loggers": {
    "ROOT": {
      "configuredLevel": "INFO",
      "effectiveLevel": "INFO"
    },
    "SQL dialect": {
      "effectiveLevel": "INFO"
    },
    "_org": {
      "effectiveLevel": "INFO"
    },
    "_org.springframework": {
      "effectiveLevel": "INFO"
    },
    "_org.springframework.web": {
      "effectiveLevel": "INFO"
    },
    "_org.springframework.web.servlet": {
      "effectiveLevel": "INFO"
    },
    "_org.springframework.web.servlet.HandlerMapping": {
      "effectiveLevel": "INFO"
    },
    "_org.springframework.web.servlet.HandlerMapping.Mappings": {
      "effectiveLevel": "INFO"
    },
      "hello.controller.LogController": {
      "effectiveLevel": "DEBUG"
    },
  }
}

✅ 더 자세히 조회하기 → 패턴을 이용

• http://localhost:8080/actuator/loggers/hello.controller

{
  "configuredLevel": "DEBUG",
  "effectiveLevel": "DEBUG"
}

✅ 실시간 로그 레벨 변경

• 보통 개발 서버에서는 DEBUG까지만 로그를 사용

• 운영 서버는 요청이 너무 많기 때문에 DEBUG까지 출력하면 엄청 많이 출력한다. → 모두 출력하면 성능, 디스크에 영향을준다.

• 운영 서버는 INFO까지만 하는걸 추천

• 서비스 운영중에 문제가 있어서 급하게 DEBUG 나 TRACE 로그를 남겨서 확인해야 확인하고 싶다면 어떻게 해야할까?

  • 일반적으로는 로깅 설정을 변경하고, 서버를 다시 시작해야 한다.

• loggers 엔드포인트를 사용하면 애플리케이션을 다시 시작하지 않고, 실시간으로 로그 레벨을 변경할 수 있다.

• POST로 전달하는 내용 JSON content/type도 application/json

으로 전달해야 한다.

{
	"configuredLevel": "TRACE"
}

• GET으로 요청해서 확인해보면 configuredLevel 이 TRACE로 변경된 것을 확인할 수 있다.
• GET http://localhost:8080/actuator/loggers/hello.controller

{
	"configuredLevel": "TRACE",
	"effectiveLevel": "TRACE"
}

• http://localhost:8080/log
  • 실행 결과를 보면 TRACE 레벨까지 출력되는 것을 확인

TRACE 53783 --- [nio-8080-exec-6] hello.controller.LogController : trace log
DEBUG 53783 --- [nio-8080-exec-6] hello.controller.LogController : debug log
INFO 53783 --- [nio-8080-exec-6] hello.controller.LogController : info log
WARN 53783 --- [nio-8080-exec-6] hello.controller.LogController : warn log
ERROR 53783 --- [nio-8080-exec-6] hello.controller.LogController : error log

9️⃣ HTTP 요청 응답 기록

• HTTP 요청과 응답의 과거 기록을 확인하고 싶다면 httpexchanges 엔드포인트를 사용

• HttpExchangeRepository 인터페이스의 구현체를 빈으로 등록하면 httpexchanges 엔드포인트를 사용할 수 있다. ( 해당 빈을 등록하지 않으면 httpexchanges 엔드포인트를 활성화 되지않는다.)

• 스프링 부트는 기본으로 InMemoryHttpExchangeRepository 구현체를 제공한다.

• InMemoryHttpExchangeRepository 추가

  • InMemoryHttpExchangeRepository 구현체는 최대 100개의 HTTP 요청을 제공한다.
  • 최대 요청이 넘어가면 과거 요청을 삭제한다.

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.actuate.web.exchanges.InMemoryHttpExchangeRepository;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class ActuatorApplication {

    public static void main(String[] args) {
        SpringApplication.run(ActuatorApplication.class, args);
    }

    @Bean
    public InMemoryHttpExchangeRepository inMemoryHttpExchangeRepository() {
        return new InMemoryHttpExchangeRepository();
    }
}

• 실행결과

{
  "exchanges": [
    {
      "timestamp": "2025-08-22T15:11:25.200053Z",
      "request": {
        "uri": "http://localhost:8080/log",
        "method": "GET",
        "headers": {
          "host": [
            "localhost:8080"
          ],
          "connection": [
            "keep-alive"
          ],
          "sec-ch-ua": [
            "\"Not;A=Brand\";v=\"99\", \"Google Chrome\";v=\"139\", \"Chromium\";v=\"139\""
          ],
          "sec-ch-ua-mobile": [
            "?0"
          ],
          "sec-ch-ua-platform": [
            "\"macOS\""
          ],
          "upgrade-insecure-requests": [
            "1"
          ],
          "user-agent": [
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
          ],
          "accept": [
            "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"
          ],
          "sec-fetch-site": [
            "none"
          ],
          "sec-fetch-mode": [
            "navigate"
          ],
          "sec-fetch-user": [
            "?1"
          ],
          "sec-fetch-dest": [
            "document"
          ],
          "accept-encoding": [
            "gzip, deflate, br, zstd"
          ],
          "accept-language": [
            "ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7"
          ]
        }
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": [
            "text/html;charset=UTF-8"
          ],
          "Content-Length": [
            "2"
          ],
          "Date": [
            "Fri, 22 Aug 2025 15:11:25 GMT"
          ],
          "Keep-Alive": [
            "timeout=60"
          ],
          "Connection": [
            "keep-alive"
          ]
        }
      },
      "timeTaken": "PT0.065599S"
    },
    {
      "timestamp": "2025-08-22T15:11:12.304301Z",
      "request": {
        "uri": "http://localhost:8080/actuator/httpexchanges",
        "method": "GET",
        "headers": {
          "host": [
            "localhost:8080"
          ],
          "connection": [
            "keep-alive"
          ],
          "sec-ch-ua": [
            "\"Not;A=Brand\";v=\"99\", \"Google Chrome\";v=\"139\", \"Chromium\";v=\"139\""
          ],
          "sec-ch-ua-mobile": [
            "?0"
          ],
          "sec-ch-ua-platform": [
            "\"macOS\""
          ],
          "upgrade-insecure-requests": [
            "1"
          ],
          "user-agent": [
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36"
          ],
          "accept": [
            "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7"
          ],
          "sec-fetch-site": [
            "none"
          ],
          "sec-fetch-mode": [
            "navigate"
          ],
          "sec-fetch-user": [
            "?1"
          ],
          "sec-fetch-dest": [
            "document"
          ],
          "accept-encoding": [
            "gzip, deflate, br, zstd"
          ],
          "accept-language": [
            "ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7"
          ]
        }
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": [
            "application/vnd.spring-boot.actuator.v3+json"
          ],
          "Transfer-Encoding": [
            "chunked"
          ],
          "Date": [
            "Fri, 22 Aug 2025 15:11:12 GMT"
          ],
          "Keep-Alive": [
            "timeout=60"
          ],
          "Connection": [
            "keep-alive"
          ]
        }
      },
      "timeTaken": "PT0.029559S"
    }
  ]
}

1️⃣0️⃣ 액츄에이터와 보안

✅ 보안 주의

• 위에서 배운 엑추에이터는 기능이 많다 하지만 우리 애플리케이션의 내부 정보를 너무 많이 노출한다.
• 그래서 외부 인터넷 망이 공개된 곳에 액츄에이터의 엔드포인터를 공개하는 것은 보안상 좋지 않다.
• 액추에이터의 엔드포인트들은 외부 인터넷에서 접근이 불가능하게 막고, 내부에서만 접근 가능한 내부망을 사용하는 것이 안전하다.

✅ 액추에이터를 다른 포트에서 실행

• 예를 들어서 외부 인터넷 망을 통해서 8080 포트에만 접근할 수 있고, 다른 포트는 내부망에서만 접근할 수 있다면 액츄에이터에 다른 포트를 설정하면 된다.

• application.yml 에서 수정된 내용

  server:
    port: 9292

✅ 액츄에티어 URL 경로에 인증 설정

• 포트를 분리하는 것이 어렵고 어쩔 수 없이 외부 인터넷 망을 통해서 접근해야 한다면 /actuator 경로에 서블릿 필터, 또는 스프링 시큐티리를 통해서 인증된 사용자만 접근 가능하도록 추가 개발이 필요하다.

✅ 엔드포인트 경로 변경

endpoints:
		web:
			base-path: "/manage"

base-path: "/manage"
/actuator/{엔드포인트} 대신에 /manage/{엔드포인트}로 변경된다.