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

[seyeop03]

2.5. 애플리케이션 정보 (/actuator/info)

💡

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

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

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

env, java, os 는 기본으로 비활성화 되어 있다. build, git 은 파일을 추가해야 한다.

실행

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

(1) java, os

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

application.yml - 내용 추가

management:
	info:
		java:
			enabled: true
		os:
			enabled: true
	# management 다음에 바로 info가 나와야 함!
	endpoint:
		shutdown:
			

management.info.<id>.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 관련 정보를 확인할 수 있다.

(2) env

💡

env 는 Environment 에서 info. 로 시작하는 정보를 출력한다.

이번에는 env 를 사용해보자.

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 로 시작하는 부분의 정보가 노출되는 것을 확인할 수 있다.

(3) build

이번에는 빌드 정보를 노출해보자. 빌드 정보를 노출하려면 빌드 시점에 META-INF/[build-info.properties](http://build-info.properties/) 파일을 만들어야 한다.

• 수동으로 build-info.properties 파일을 만드는 것이 아니다! 그저 gradle에 다음과 같이 추가해주면 된다!

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

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

(4) git

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

• 수동으로 [git.properties](http://git.properties) 파일을 만드는 것이 아니다! 그저 gradle에 다음과 같이 추가해주면 된다!

build.gradle - git 정보 추가

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

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

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

git 을 설명하는 것은 이 강의 범위를 넘어선다. 별도로 git 을 배우고 다시 학습하자.

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

git.branch=main
git.build.host=kim
git.build.user.email=zipkyh@mail.com
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=zipkyh@mail.com
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

2.6. 로그 정보 (/actuator/loggers)

💡

loggers 엔드포인트를 사용하면 로깅과 관련된 정보를 확인할 수 있고, 또 운영중에 급할 때 서버를 껐다켜지 않고 실시간으로 변경할 수도 있다.

코드를 통해서 알아보자.

(1) 기본 로그 조회

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

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

1. application.yml 설정

logging:
	level:
		hello.controller: **debug**

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

실행

http://localhost:8080/log

결과 로그

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

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

실행

http://localhost:8080/actuator/loggers

실행 결과

{
	"levels":[
		"OFF",
		"ERROR",
		"WARN",
		"INFO",
		"DEBUG",
		"TRACE"
	]
	//기본 로깅 레벨 "INFO"
	"loggers":{
		"ROOT":{
			"configuredLevel":"INFO",
			"effectiveLevel":"INFO"
		},
		"_org.springframework":{
			"effectiveLevel":"INFO"
		},
		"hello":{
			"effectiveLevel":"INFO"
		},
		"hello.ActuatorApplication":{
			"effectiveLevel":"INFO"
		},
		//우리가 .yml 에 설정한 hello.controller 패키지 및 하위 패키지 로깅 레벨 "DEBUG"
		"hello.controller":{
			"configuredLevel":"DEBUG",
			"effectiveLevel":"DEBUG"
		},
		"hello.controller.LogController":{
			"effectiveLevel":"DEBUG"
		}
	}
}

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

(2) 더 자세히 조회하기

다음과 같은 패턴을 사용해서 특정 로거 이름을 기준으로 조회할 수 있다.

• [http://localhost:8080/actuator/loggers/{로거이름}](http://localhost:8080/actuator/loggers/%7B%EB%A1%9C%EA%B1%B0%EC%9D%B4%EB%A6%84%7D)

실행

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

결과

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

(3) 실시간 로그 레벨 변경

개발 서버는 보통 DEBUG 로그를 사용하지만, 운영 서버는 보통 요청이 아주 많다. 따라서 로그도 너무 많이 남기 때문에 DEBUG 로그까지 모두 출력하게 되면 성능이나 디스크에 영향을 주게 된다. 그래서 운영 서버는 중요하다고 판단되는 INFO 로그 레벨을 사용한다.

그런데 서비스 운영중에 문제가 있어서 급하게 DEBUG 나 TRACE 로그를 남겨서 확인하고 싶다면 어떻게 해야할까? 일반적으로는 로깅 설정을 변경하고, 서버를 다시 시작해야 한다.

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

---

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

POST 요청 : http://localhost:8080/actuator/loggers/hello.controller

POST로 전달하는 내용 JSON, content/type 도 application/json 으로 전달해야 한다.

**POST** /actuator/loggers/hello.controller HTTP/1.1
Host: http://localhost:8080
{
	 "configuredLevel": "TRACE"
}

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

GET으로 요청해서 확인해보면 configuredLevel 이 TRACE 로 변경된 것을 확인할 수 있다.

GET 요청 : http://localhost:8080/actuator/loggers/hello.controller

호출 결과

**GET** /actuator/loggers/hello.controller HTTP/1.1
Host: http://localhost:8080
{
	"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 레벨까지 출력되는 것을 확인할 수 있다.

2.7. 로그 정보 (/actuator/httpexchanges)

💡

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();
		}
}

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

실행

http://localhost:8080/actuator/httpexchanges

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

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

2.8. 액추에이터와 보안 (/actuator)

(1) 보안 주의 필요

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

액츄에이터의 엔드포인트들은 외부 인터넷에서 접근이 불가능하게 막고, 내부에서만 접근 가능한 내부망을 사용하는 것이 안전하다.

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

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

액추에이터 포트 설정

• management.server.port: 9292

실행

http://localhost:9292/actuator

• http://localhost:8080/actuator 는 이제 안됨

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

(2) 엔드포인트 경로 변경

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

application.yml

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

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

Chapter 9. 에서는 본격적으로 스프링 부트가 제공하는 액추에이터에다가 CPU 사용량, 메모리 사용량, 톰캣 쓰레드 등이 제공되는 metrics 를 활용한 모니터링 + 프로메테우스와 그라파나를 엮어서 실무에서 어떤식으로 모니터링을 구성하는지 설명한다.