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

[im1sun]

7. 애플리케이션 정보

info 엔드포인트는 애플리케이션의 기본 정보를 노출한다.

기본으로 제공하는 기능들은 다음과 같다.

• java : 자바 런타임 정보
• os : OS 정보
• env : Environment 에서 info. 로 시작하는 정보
• build : 빌드 정보, META-INF/build-info.properties 파일이 필요하다.
• git : git 정보, git.properties 파일이 필요하다.

env , java , os 는 기본으로 비활성화 되어 있다.

실행
http://localhost:8080/actuator/info

처음에 실행하면 정보들이 보이지 않을 것이다. java , os 기능을 활성화해보자.

java, os
JAVA, OS 정보를 확인해보자.

application.yml - 내용 추가

management:
 info:
    java:
        enabled: true
    os:
        enabled: true 

management.info..enabled 의 값을 true 로 지정하면 활성화 된다.
주의!: management.endpoint 하위가 아니다. management 바로 다음에 info가 나온다.

실행 결과
http://localhost:8080/actuator/info

{
    "java":{
        "version":"17.0.3",
        "vendor":{
            "name":"JetBrains s.r.o.",
            "version":"JBR-17.0.3+7-469.37-jcef"
        },
        "runtime":{
            "name":"OpenJDK Runtime Environment",
            "version":"17.0.3+7-b469.37"
        },
        "jvm":{
            "name":"OpenJDK 64-Bit Server VM",
            "vendor":"JetBrains s.r.o.",
            "version":"17.0.3+7-b469.37"
        }
    },
    "os":{
        "name":"Mac OS X",
        "version":"12.5.1",
        "arch":"aarch64"
    }
}

실행해보면 java , os 관련 정보를 확인할 수 있다.

env
이번에는 env 를 사용해보자.
Environment 에서 info. 로 시작하는 정보를 출력한다.

application.yml - 내용 추가

management:
    info:
        env:
            enabled: true
info:
    app:
        name: hello-actuator
        company: yh 

management.info.env.enabled 를 추가하고, info.. 관련 내용을 추가했다.

실행 결과
http://localhost:8080/actuator/info

{
    "app":{
        "name":"hello-actuator",
        "company":"yh"
    }
    ...
}

application.yml 에서 info 로 시작하는 부분의 정보가 노출되는 것을 확인할 수 있다.

build
이번에는 빌드 정보를 노출해보자. 빌드 정보를 노출하려면 빌드 시점에 META-INF/build-info.properties 파일을 만들어야 한다.
gradle 을 사용하면 다음 내용을 추가하면 된다.

build.gradle - 빌드 정보 추가

springBoot {
   buildInfo()
}

이렇게 하고 빌드를 해보면 build 폴더안에 resources/main/META-INF/build-info.properties 파일을 확인할 수 있다.

build.artifact=actuator
build.group=hello
build.name=actuator
build.time=2023-01-01T00\:000\:00.000000Z
build.version=0.0.1-SNAPSHOT 

build 는 기본으로 활성화 되어 있기 때문에 이 파일만 있으면 바로 확인할 수 있다.

실행 결과
http://localhost:8080/actuator/info

{
 "build":{
 "artifact":"actuator",
 "name":"actuator",
 "time":"2023-01-01T00:00:00.000Z",
 "version":"0.0.1-SNAPSHOT",
 "group":"hello"
 }
 ...
}

실행 결과를 통해서 애플리케이션의 기본 정보와 버전 그리고 빌드된 시간을 확인할 수 있다.

git
앞서본 build 와 유사하게 빌드 시점에 사용한 git 정보도 노출할 수 있다. git 정보를 노출하려면 git.properties 파일이 필요하다.

build.gradle - git 정보 추가

plugins {
 ...
 id "com.gorylenko.gradle-git-properties" version "2.4.1" //git info
}

물론 프로젝트가 git 으로 관리되고 있어야 한다. 그렇지 않으면 빌드시 오류가 발생한다.

프로젝트에 git 을 적용하고 커밋해보자.

참고
git 을 설명하는 것은 이 강의 범위를 넘어선다. git 을 잘 모르는 분들은 별도로 git 을 배운 다음에 이 부분을 다시 학습하자.

이렇게 하고 빌드를 해보면 build 폴더안에 resources/main/git.properties 파일을 확인할 수 있다.

git.branch=main
git.build.host=kim
git.build.user.email[email protected]
git.build.user.name=holyeye
git.build.version=0.0.1-SNAPSHOT
git.closest.tag.commit.count=
git.closest.tag.name=
git.commit.id=754bc78744107b6423352018e46367f5091b181e
git.commit.id.abbrev=754bc78
git.commit.id.describe=
git.commit.message.full=fitst commit\n
git.commit.message.short=fitst commit
git.commit.time=2023-01-01T00\:00\:00+0900
git.commit.user.email[email protected]
git.commit.user.name=holyeye
git.dirty=false
git.remote.origin.url=
git.tags=
git.total.commit.count=1 

git 은 기본으로 활성화 되어 있기 때문에 이 파일만 있으면 바로 확인할 수 있다.

실행 결과
http://localhost:8080/actuator/info

{
 "git":{
    "branch":"main",
    "commit":{
        "id":"754bc78",
        "time":"2023-01-01T00:00:00Z"
    }
 }
 ...
}

실행 결과를 통해서 이 빌드는 main 브랜치와 754bc78 커밋에서 만들어진 것을 확인할 수 있다.
애플리케이션을 배포할 때 가끔 기대와 전혀 다르게 동작할 때가 있는데,(특정 기능이 빠져있다던가) 확인해보면 다른
커밋이나 다른 브랜치의 내용이 배포된 경우가 종종 있다. 이럴 때 큰 도움이 된다.

git 에 대한 더 자세한 정보를 보고 싶다면 다음 옵션을 적용하면 된다.
application.yml 추가

management:
 info:
   git:
     mode: "full"

info 사용자 정의 기능 추가
info 의 사용자 정의 기능을 추가 하고 싶다면 다음 스프링 공식 메뉴얼을 참고하자
https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.info.writing-custom-info-contributors

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";
    }
}

여러 레벨을 로그를 남기는 단순한 컨트롤러이다.

application.yml 설정

logging:
    level:
        hello.controller: debug 

hello.controller 패키지와 그 하위는 debug 레벨을 출력하도록 했다. 이제 앞서 만든 LogController 클래스도 debug 레벨의 영향을 받는다.

실행
http://localhost:8080/log

결과 로그

DEBUG 53783 --- hello.controller.LogController : debug log
 INFO 53783 --- hello.controller.LogController : info log
 WARN 53783 --- hello.controller.LogController : warn log
ERROR 53783 --- hello.controller.LogController : error log

실행 결과를 보면 기대한 것 처럼 DEBUG 레벨까지 출력되는 것을 확인할 수 있다.

loggers 엔드포인트를 호출해보자.

실행
http://localhost:8080/actuator/loggers

실행 결과

{
    "levels":[
        "OFF",
        "ERROR",
        "WARN",
        "INFO",
        "DEBUG",
        "TRACE"
    ],
    "loggers":{
        "ROOT":{
            "configuredLevel":"INFO",
            "effectiveLevel":"INFO"
        },
        "_org.springframework":{
            "effectiveLevel":"INFO"
        },
        "hello":{
            "effectiveLevel":"INFO"
        },
        "hello.ActuatorApplication":{
            "effectiveLevel":"INFO"
        },
        "hello.controller":{
            "configuredLevel":"DEBUG",
            "effectiveLevel":"DEBUG"
        },
        "hello.controller.LogController":{
            "effectiveLevel":"DEBUG"
        }
    }
}

• 로그를 별도로 설정하지 않으면 스프링 부트는 기본으로 INFO 를 사용한다. 실행 결과를 보면 ROOT 의 configuredLevel 가 INFO 인 것을 확인할 수 있다. 따라서 그 하위도 모두 INFO 레벨이 적용된다.
• 앞서 우리는 hello.controller 는 DEBUG 로 설정했다. 그래서 해당 부분에서 configuredLevel이 DEBUG 로 설정된 것을 확인할 수 있다. 그리고 그 하위도 DEBUG 레벨이 적용된다.

더 자세히 조회하기
다음과 같은 패턴을 사용해서 특정 로거 이름을 기준으로 조회할 수 있다.
http://localhost:8080/actuator/loggers/{로거이름}

실행
http://localhost:8080/actuator/loggers/hello.controller

결과

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

실시간 로그 레벨 변경
개발 서버는 보통 DEBUG 로그를 사용하지만, 운영 서버는 보통 요청이 아주 많다. 따라서 로그도 너무 많이 남기 때문에 DEBUG 로그까지 모두 출력하게 되면 성능이나 디스크에 영향을 주게 된다. 그래서 운영 서버는 중요하다고 판단되는 INFO 로그 레벨을 사용한다.
그런데 서비스 운영중에 문제가 있어서 급하게 DEBUG 나 TRACE 로그를 남겨서 확인해야 확인하고 싶다면 어떻게 해야할까? 일반적으로는 로깅 설정을 변경하고, 서버를 다시 시작해야 한다.
loggers 엔드포인트를 사용하면 애플리케이션을 다시 시작하지 않고, 실시간으로 로그 레벨을 변경할 수 있다.

다음을 Postman 같은 프로그램으로 POST로 요청해보자(꼭! POST를 사용해야 한다.)

POST http://localhost:8080/actuator/loggers/hello.controller
POST로 전달하는 내용 JSON , content/type 도 application/json 으로 전달해야 한다.

{
 "configuredLevel": "TRACE"
}

참고로 이것은 POST에 전달하는 내용이다. 응답 결과가 아니다.
요청에 성공하면 204 응답이 온다.(별도의 응답 메시지는 없다.)

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

호출 결과

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

정말 로그 레벨이 실시간으로 변경되었는지 확인해보자.

실행
http://localhost:8080/log

결과 로그

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

실행 결과를 보면 TRACE 레벨까지 출력되는 것을 확인할 수 있다.

9. HTTP 요청 응답 기록

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

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

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

InMemoryHttpExchangeRepository 추가

@SpringBootApplication
public class ActuatorApplication {
    public static void main(String[] args) {
        SpringApplication.run(ActuatorApplication.class, args);
    }
    @Bean
    public InMemoryHttpExchangeRepository httpExchangeRepository() {
        return new InMemoryHttpExchangeRepository();
    }
}

이 구현체는 최대 100개의 HTTP 요청을 제공한다. 최대 요청이 넘어가면 과거 요청을 삭제한다. setCapacity()로 최대 요청수를 변경할 수 있다.

실행
http://localhost:8080/actuator/httpexchanges

실행해보면 지금까지 실행한 HTTP 요청과 응답 정보를 확인할 수 있다.

참고로 이 기능은 매우 단순하고 기능에 제한이 많기 때문에 개발 단계에서만 사용하고, 실제 운영 서비스에서는 모니터링 툴이나 핀포인트, Zipkin 같은 다른 기술을 사용하는 것이 좋다.

10. 액츄에이터와 보안

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

액츄에이터를 다른 포트에서 실행
예를 들어서 외부 인터넷 망을 통해서 8080 포트에만 접근할 수 있고, 다른 포트는 내부망에서만 접근할 수 있다면 액츄에이터에 다른 포트를 설정하면 된다.
액츄에이터의 기능을 애플리케이션 서버와는 다른 포트에서 실행하려면 다음과 같이 설정하면 된다. 이 경우 기존8080 포트에서는 액츄에이터를 접근할 수 없다.

액츄에이터 포트 설정
management.server.port=9292

실행
http://localhost:9292/actuator

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

엔드포인트 경로 변경
엔드포인트의 기본 경로를 변경하려면 다음과 같이 설정하면 된다.

application.yml

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

/actuator/{엔드포인트} 대신에 /manage/{엔드포인트} 로 변경된다.