<div id="readability-page-1" class="page"><div>
      
      <header>
        
        

  <p>
    

    

    
      
      

      <span>
        
        
          5 분 소요
        
      </span>
    
  </p>


      </header>
      

      <section itemprop="text">
        
        

<h2 id="0-들어가면서">0. 들어가면서</h2>

<p>최근 OOM(out of memory) 에러를 만났을 때 스프링 애플리케이션 메트릭 정보를 확인하기 위해 스프링 액추에이터(spring actuator)를 추가했다. 프로젝트마다 매번 설정 방법을 검색하는 것이 번거로워 블로그 글로 기록했다.</p>

<h2 id="1-spring-actuator">1. Spring Actuator</h2>

<p>애플리케이션의 전반적인 상태를 메트릭(metric)이라고 한다. 이는 그라파나(grafana), 데이터독(datadog)이나 엘라스틱 서치(elastic search) 같은 애플리케이션 성능 모니터링 도구들이 애플리케이션의 상태를 시각화 할 때 사용한다. 메트릭은 서비스를 운영함에 있어 추적할 필요가 있는 다음과 같은 정보들을 의미한다.</p>

<ul>
  <li>CPU 사용률</li>
  <li>메모리 사용률</li>
  <li>스레드 사용률</li>
</ul>

<p>액추에이터는 스프링 애플리케이션 상태에 대한 종합적인 정보를 HTTP 엔드-포인트(end-point)를 통해 노출시킨다. 모니터링 수집 도구들은</p>

<h2 id="2-practice">2. Practice</h2>

<p>스프링 부트 3.2.5 버전 환경에서 실습을 진행한다. 액추에이터에서 제공하는 몇 가지 기능들을 정리한다. 의존성은 다음과 같다.</p>

<div><pre><code><span>plugins</span> <span>{</span>
    <span>id</span> <span>'java'</span>
    <span>id</span> <span>'org.springframework.boot'</span> <span>version</span> <span>'3.2.5'</span>
    <span>id</span> <span>'io.spring.dependency-management'</span> <span>version</span> <span>'1.1.4'</span>
<span>}</span>

<span>group</span> <span>=</span> <span>'action.in.blog'</span>
<span>version</span> <span>=</span> <span>'0.0.1-SNAPSHOT'</span>

<span>java</span> <span>{</span>
    <span>sourceCompatibility</span> <span>=</span> <span>'17'</span>
<span>}</span>

<span>repositories</span> <span>{</span>
    <span>mavenCentral</span><span>()</span>
<span>}</span>

<span>dependencies</span> <span>{</span>
    <span>implementation</span> <span>'org.springframework.boot:spring-boot-starter-web'</span>
    <span>implementation</span> <span>'org.springframework.boot:spring-boot-starter-actuator'</span>
    <span>testImplementation</span> <span>'org.springframework.boot:spring-boot-starter-test'</span>
<span>}</span>

<span>tasks</span><span>.</span><span>named</span><span>(</span><span>'test'</span><span>)</span> <span>{</span>
    <span>useJUnitPlatform</span><span>()</span>
<span>}</span>
</code></pre></div>

<p>스프링 액추에이터 의존성이 추가된 상태에서 애플리케이션을 실행하면 액추에이터가 기본으로 제공하는 엔드-포인트를 확인할 수 있다.</p>

<ul>
  <li>액추에이터가 제공하는 엔드-포인트는 <code>/actuator</code> 경로에서 확인할 수 있다.</li>
  <li><code>templated</code> 플래그는 엔드-포인트가 템플릿 형태로 중간 변수로 인해 변경될 수 있다는 의미이다.</li>
</ul>

<div><pre><code>$ curl http://localhost:8080/actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   243    0   243    0     0  71115      0 --:--:-- --:--:-- --:--:-- 81000
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    }
  }
}
</code></pre></div>

<h3 id="21-expose-endpoints">2.1. Expose Endpoints</h3>

<p>간단한 확인을 위해 액추에이터가 제공하는 모든 엔드-포인트를 노출해보자. application.yml 파일을 다음과 같이 설정한다.</p>

<ul>
  <li>웹에서 노출할 정보에 ‘*‘(애스터리스크)를 지정한다.</li>
</ul>

<div><pre><code><span>management</span><span>:</span>
  <span>endpoints</span><span>:</span>
    <span>web</span><span>:</span>
      <span>exposure</span><span>:</span>
        <span>include</span><span>:</span> <span>'</span><span>*'</span>
</code></pre></div>

<p>/actuator 경로에서 액추에이터가 제공하는 정보를 확인해보자.</p>

<ul>
  <li>총 20개 엔드-포인트를 통해 애플리케이션 상태를 제공한다.</li>
  <li>각 엔드-포인트들이 제공하는 정보는 이 <a href="https://docs.spring.io/spring-boot/docs/current/actuator-api/pdf/spring-boot-actuator-web-api.pdf">문서</a>에 잘 정리되어 있다.</li>
</ul>

<div><pre><code>$ curl http://localhost:8080/actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1680    0  1680    0     0  18310      0 --:--:-- --:--:-- --:--:-- 18260
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "beans": {
      "href": "http://localhost:8080/actuator/beans",
      "templated": false
    },
    "caches": {
      "href": "http://localhost:8080/actuator/caches",
      "templated": false
    },
    "caches-cache": {
      "href": "http://localhost:8080/actuator/caches/{cache}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "info": {
      "href": "http://localhost:8080/actuator/info",
      "templated": false
    },
    "conditions": {
      "href": "http://localhost:8080/actuator/conditions",
      "templated": false
    },
    "configprops-prefix": {
      "href": "http://localhost:8080/actuator/configprops/{prefix}",
      "templated": true
    },
    "configprops": {
      "href": "http://localhost:8080/actuator/configprops",
      "templated": false
    },
    "env-toMatch": {
      "href": "http://localhost:8080/actuator/env/{toMatch}",
      "templated": true
    },
    "env": {
      "href": "http://localhost:8080/actuator/env",
      "templated": false
    },
    "loggers-name": {
      "href": "http://localhost:8080/actuator/loggers/{name}",
      "templated": true
    },
    "loggers": {
      "href": "http://localhost:8080/actuator/loggers",
      "templated": false
    },
    "heapdump": {
      "href": "http://localhost:8080/actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:8080/actuator/threaddump",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
      "templated": true
    },
    "metrics": {
      "href": "http://localhost:8080/actuator/metrics",
      "templated": false
    },
    "scheduledtasks": {
      "href": "http://localhost:8080/actuator/scheduledtasks",
      "templated": false
    },
    "mappings": {
      "href": "http://localhost:8080/actuator/mappings",
      "templated": false
    }
  }
}
</code></pre></div>

<p>각 엔드-포인트마다 제공하는 정보가 다르다. 예를 들어 애플리케이션 메트릭 정보를 요청해보자.</p>

<ul>
  <li>액추에이터가 제공하는 메트릭 정보들을 전달한다.</li>
</ul>

<div><pre><code>$ curl http://localhost:8080/actuator/metrics | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1489    0  1489    0     0   440k      0 --:--:-- --:--:-- --:--:--  484k
{
  "names": [
    "application.ready.time",
    "application.started.time",
    "disk.free",
    "disk.total",
    "executor.active",
    "executor.completed",
    "executor.pool.core",
    "executor.pool.max",
    "executor.pool.size",
    "executor.queue.remaining",
    "executor.queued",
    "hikaricp.connections",
    "hikaricp.connections.acquire",
    "hikaricp.connections.active",
    "hikaricp.connections.creation",
    "hikaricp.connections.idle",
    "hikaricp.connections.max",
    "hikaricp.connections.min",
    "hikaricp.connections.pending",
    "hikaricp.connections.timeout",
    "hikaricp.connections.usage",
    "http.server.requests",
    "http.server.requests.active",
    "jdbc.connections.active",
    "jdbc.connections.idle",
    "jdbc.connections.max",
    "jdbc.connections.min",
    "jvm.buffer.count",
    "jvm.buffer.memory.used",
    "jvm.buffer.total.capacity",
    "jvm.classes.loaded",
    "jvm.classes.unloaded",
    "jvm.compilation.time",
    "jvm.gc.live.data.size",
    "jvm.gc.max.data.size",
    "jvm.gc.memory.allocated",
    "jvm.gc.memory.promoted",
    "jvm.gc.overhead",
    "jvm.gc.pause",
    "jvm.info",
    "jvm.memory.committed",
    "jvm.memory.max",
    "jvm.memory.usage.after.gc",
    "jvm.memory.used",
    "jvm.threads.daemon",
    "jvm.threads.live",
    "jvm.threads.peak",
    "jvm.threads.started",
    "jvm.threads.states",
    "logback.events",
    "process.cpu.usage",
    "process.files.max",
    "process.files.open",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "system.load.average.1m",
    "tomcat.sessions.active.current",
    "tomcat.sessions.active.max",
    "tomcat.sessions.alive.max",
    "tomcat.sessions.created",
    "tomcat.sessions.expired",
    "tomcat.sessions.rejected"
  ]
}
</code></pre></div>

<p>액추에이터가 제공하는 메트릭 중 JVM 메모리 사용량을 살펴보자.</p>

<ul>
  <li>해당 엔드-포인트에서 제공하는 정보에 대한 설명을 볼 수 있다.
    <ul>
      <li>어느 정도 사용 중인지 바이트 단위로 알 수 있다.</li>
      <li>어느 메모리 영역의 사용량인지 알 수 있다.</li>
    </ul>
  </li>
</ul>

<div><pre><code>$ curl http://localhost:8080/actuator/metrics/jvm.memory.used | jq . 
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   330    0   330    0     0  90065      0 --:--:-- --:--:-- --:--:--  107k
{
  "name": "jvm.memory.used",
  "description": "The amount of used memory",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 118935248
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": [
        "heap",
        "nonheap"
      ]
    },
    {
      "tag": "id",
      "values": [
        "G1 Survivor Space",
        "Compressed Class Space",
        "Metaspace",
        "CodeCache",
        "G1 Old Gen",
        "G1 Eden Space"
      ]
    }
  ]
}
</code></pre></div>

<p>위에서 살펴본 것처럼 액추에이터는 애플리케이션의 상태에서부터 민감한 정보까지 제공한다. 그렇기에 불필요한 엔드-포인트들까지 노출하는 것은 문제가 될 수 있다. 다음과 같이 설정하면 필요한 엔드-포인트들만 노출할 수 있다.</p>

<div><pre><code><span>management</span><span>:</span>
  <span>endpoints</span><span>:</span>
    <span>web</span><span>:</span>
      <span>exposure</span><span>:</span>
        <span>include</span><span>:</span> <span>health, heapdump, threaddump, metrics</span>
</code></pre></div>

<p>/actuator 경로에서 제공하는 정보를 확인해보자.</p>

<div><pre><code>$ curl http://localhost:8080/actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   602    0   602    0     0   4023      0 --:--:-- --:--:-- --:--:--  4013
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "heapdump": {
      "href": "http://localhost:8080/actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:8080/actuator/threaddump",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
      "templated": true
    },
    "metrics": {
      "href": "http://localhost:8080/actuator/metrics",
      "templated": false
    }
  }
}
</code></pre></div>

<h3 id="22-change-port-and-api-path">2.2. Change port and API path</h3>

<p>액추에이터는 애플리케이션 정보를 노출하고 많이 사용되는 라이브러리이기 때문에 잘 알려진 포트(port)나 기본 API 경로를 사용하는 것보다 변경 후 사용하는 것이 안전하다. 다음과 같은 설정으로 액추에이터 포트 번호와 앤드-포인트 경로를 변경할 수 있다.</p>

<div><pre><code><span>management</span><span>:</span>
  <span>endpoints</span><span>:</span>
    <span>web</span><span>:</span>
      <span>exposure</span><span>:</span>
        <span>include</span><span>:</span> <span>health, heapdump, threaddump, metrics</span>
      <span>base-path</span><span>:</span> <span>/custom-actuator</span>
  <span>server</span><span>:</span>
    <span>port</span><span>:</span> <span>9090</span>
</code></pre></div>

<p>애플리케이션을 실행하면 다음과 같은 로그를 볼 수 있다.</p>

<ul>
  <li>톰캣 서버가 9090 포트를 활성화한다.</li>
  <li>/custom-actuator 하위 경로에 액추에이터가 제공하는 정보들이 노출되어 있다.</li>
</ul>

<div><pre><code>2024-05-14T22:16:26.641+09:00  INFO 5048 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path ''
2024-05-14T22:16:26.704+09:00  INFO 5048 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port 9090 (http)
2024-05-14T22:16:26.705+09:00  INFO 5048 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2024-05-14T22:16:26.705+09:00  INFO 5048 --- [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.20]
2024-05-14T22:16:26.719+09:00  INFO 5048 --- [           main] o.a.c.c.C.[Tomcat-1].[localhost].[/]     : Initializing Spring embedded WebApplicationContext
2024-05-14T22:16:26.719+09:00  INFO 5048 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 75 ms
2024-05-14T22:16:26.732+09:00  INFO 5048 --- [           main] o.s.b.a.e.web.EndpointLinksResolver      : Exposing 4 endpoint(s) beneath base path '/custom-actuator'
2024-05-14T22:16:26.766+09:00  INFO 5048 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 9090 (http) with context path ''
2024-05-14T22:16:26.780+09:00  INFO 5048 --- [           main] action.in.blog.ActionInBlogApplication   : Started ActionInBlogApplication in 4.527 seconds (process running for 5.307)
</code></pre></div>

<p>다음과 같은 cURL 명령어로 애플리케이션 정보를 획득할 수 있다.</p>

<ul>
  <li>9090 포트 번호로 요청을 보낸다.</li>
  <li>/custom-actuator 하위 경로에서 필요한 정보를 획득할 수 있다.</li>
</ul>

<div><pre><code>$ curl http://localhost:9090/custom-actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   651    0   651    0     0   7158      0 --:--:-- --:--:-- --:--:--  7233
{
  "_links": {
    "self": {
      "href": "http://localhost:9090/custom-actuator",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:9090/custom-actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:9090/custom-actuator/health",
      "templated": false
    },
    "heapdump": {
      "href": "http://localhost:9090/custom-actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:9090/custom-actuator/threaddump",
      "templated": false
    },
    "metrics": {
      "href": "http://localhost:9090/custom-actuator/metrics",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:9090/custom-actuator/metrics/{requiredMetricName}",
      "templated": true
    }
  }
}
</code></pre></div>

<h4 id="test-code-repository">TEST CODE REPOSITORY</h4>

<ul>
  <li><a href="https://github.com/Junhyunny/blog-in-action/tree/master/2024-05-15-spring-boot-actuator">https://github.com/Junhyunny/blog-in-action/tree/master/2024-05-15-spring-boot-actuator</a></li>
</ul>

<h4 id="reference">REFERENCE</h4>

<ul>
  <li><a href="https://docs.spring.io/spring-boot/docs/current/actuator-api/htmlsingle/">https://docs.spring.io/spring-boot/docs/current/actuator-api/htmlsingle/</a></li>
  <li><a href="https://docs.spring.io/spring-boot/docs/current/actuator-api/pdf/spring-boot-actuator-web-api.pdf">https://docs.spring.io/spring-boot/docs/current/actuator-api/pdf/spring-boot-actuator-web-api.pdf</a></li>
  <li><a href="https://stackoverflow.com/questions/76794560/what-does-templated-false-mean-for-spring-boot-actuator">https://stackoverflow.com/questions/76794560/what-does-templated-false-mean-for-spring-boot-actuator</a></li>
  <li><a href="https://incheol-jung.gitbook.io/docs/study/srping-in-action-5th/chap-16.">https://incheol-jung.gitbook.io/docs/study/srping-in-action-5th/chap-16.</a></li>
</ul>

        
      </section>

      

      


      
  

    </div></div>

Junhyunny's Devlogs

0. 들어가면서
최근 OOM(out of memory) 에러를 만났을 때 스프링 애플리케이션 메트릭 정보를 확인하기 위해 스프링 액추에이터(spring actuator)를 추가했다. 프로젝트마다 매번 설정 방법을 검색하는 것이 번거로워 블로그 글로 기록했다.
1. Spring Actuator
애플리케이션의 전반적인 상태를 메트릭(metric)이라고 한다. 이는 그라파나(grafana), 데이터독(datadog)이나 엘라스틱 서치(elastic search) 같은 애플리케이션 성능 모니터링 도구들이 애플리케이션의 상태를 시각화 할 때 사용한다. 메트릭은 서비스를 운영함에 있어 추적할 필요가 있는 다음과 같은 정보들을 의미한다.
CPU 사용률
메모리 사용률
스레드 사용률
액추에이터는 스프링 애플리케이션 상태에 대한 종합적인 정보를 HTTP 엔드-포인트(end-point)를 통해 노출시킨다. 모니터링 수집 도구들은
2. Practice
스프링 부트 3.2.5 버전 환경에서 실습을 진행한다. 액추에이터에서 제공하는 몇 가지 기능들을 정리한다. 의존성은 다음과 같다.
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.5'
    id 'io.spring.dependency-management' version '1.1.4'
}
group = 'action.in.blog'
version = '0.0.1-SNAPSHOT'
java {
    sourceCompatibility = '17'
}
repositories {
    mavenCentral()
}
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
tasks.named('test') {
    useJUnitPlatform()
}
스프링 액추에이터 의존성이 추가된 상태에서 애플리케이션을 실행하면 액추에이터가 기본으로 제공하는 엔드-포인트를 확인할 수 있다.
액추에이터가 제공하는 엔드-포인트는 /actuator 경로에서 확인할 수 있다.
templated 플래그는 엔드-포인트가 템플릿 형태로 중간 변수로 인해 변경될 수 있다는 의미이다.
$ curl http://localhost:8080/actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   243    0   243    0     0  71115      0 --:--:-- --:--:-- --:--:-- 81000
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    }
  }
}
2.1. Expose Endpoints
간단한 확인을 위해 액추에이터가 제공하는 모든 엔드-포인트를 노출해보자. application.yml 파일을 다음과 같이 설정한다.
웹에서 노출할 정보에 ‘*‘(애스터리스크)를 지정한다.
management:
  endpoints:
    web:
      exposure:
        include: '*'
/actuator 경로에서 액추에이터가 제공하는 정보를 확인해보자.
총 20개 엔드-포인트를 통해 애플리케이션 상태를 제공한다.
각 엔드-포인트들이 제공하는 정보는 이 문서에 잘 정리되어 있다.
$ curl http://localhost:8080/actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1680    0  1680    0     0  18310      0 --:--:-- --:--:-- --:--:-- 18260
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "beans": {
      "href": "http://localhost:8080/actuator/beans",
      "templated": false
    },
    "caches": {
      "href": "http://localhost:8080/actuator/caches",
      "templated": false
    },
    "caches-cache": {
      "href": "http://localhost:8080/actuator/caches/{cache}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "info": {
      "href": "http://localhost:8080/actuator/info",
      "templated": false
    },
    "conditions": {
      "href": "http://localhost:8080/actuator/conditions",
      "templated": false
    },
    "configprops-prefix": {
      "href": "http://localhost:8080/actuator/configprops/{prefix}",
      "templated": true
    },
    "configprops": {
      "href": "http://localhost:8080/actuator/configprops",
      "templated": false
    },
    "env-toMatch": {
      "href": "http://localhost:8080/actuator/env/{toMatch}",
      "templated": true
    },
    "env": {
      "href": "http://localhost:8080/actuator/env",
      "templated": false
    },
    "loggers-name": {
      "href": "http://localhost:8080/actuator/loggers/{name}",
      "templated": true
    },
    "loggers": {
      "href": "http://localhost:8080/actuator/loggers",
      "templated": false
    },
    "heapdump": {
      "href": "http://localhost:8080/actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:8080/actuator/threaddump",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
      "templated": true
    },
    "metrics": {
      "href": "http://localhost:8080/actuator/metrics",
      "templated": false
    },
    "scheduledtasks": {
      "href": "http://localhost:8080/actuator/scheduledtasks",
      "templated": false
    },
    "mappings": {
      "href": "http://localhost:8080/actuator/mappings",
      "templated": false
    }
  }
}
각 엔드-포인트마다 제공하는 정보가 다르다. 예를 들어 애플리케이션 메트릭 정보를 요청해보자.
액추에이터가 제공하는 메트릭 정보들을 전달한다.
$ curl http://localhost:8080/actuator/metrics | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1489    0  1489    0     0   440k      0 --:--:-- --:--:-- --:--:--  484k
{
  "names": [
    "application.ready.time",
    "application.started.time",
    "disk.free",
    "disk.total",
    "executor.active",
    "executor.completed",
    "executor.pool.core",
    "executor.pool.max",
    "executor.pool.size",
    "executor.queue.remaining",
    "executor.queued",
    "hikaricp.connections",
    "hikaricp.connections.acquire",
    "hikaricp.connections.active",
    "hikaricp.connections.creation",
    "hikaricp.connections.idle",
    "hikaricp.connections.max",
    "hikaricp.connections.min",
    "hikaricp.connections.pending",
    "hikaricp.connections.timeout",
    "hikaricp.connections.usage",
    "http.server.requests",
    "http.server.requests.active",
    "jdbc.connections.active",
    "jdbc.connections.idle",
    "jdbc.connections.max",
    "jdbc.connections.min",
    "jvm.buffer.count",
    "jvm.buffer.memory.used",
    "jvm.buffer.total.capacity",
    "jvm.classes.loaded",
    "jvm.classes.unloaded",
    "jvm.compilation.time",
    "jvm.gc.live.data.size",
    "jvm.gc.max.data.size",
    "jvm.gc.memory.allocated",
    "jvm.gc.memory.promoted",
    "jvm.gc.overhead",
    "jvm.gc.pause",
    "jvm.info",
    "jvm.memory.committed",
    "jvm.memory.max",
    "jvm.memory.usage.after.gc",
    "jvm.memory.used",
    "jvm.threads.daemon",
    "jvm.threads.live",
    "jvm.threads.peak",
    "jvm.threads.started",
    "jvm.threads.states",
    "logback.events",
    "process.cpu.usage",
    "process.files.max",
    "process.files.open",
    "process.start.time",
    "process.uptime",
    "system.cpu.count",
    "system.cpu.usage",
    "system.load.average.1m",
    "tomcat.sessions.active.current",
    "tomcat.sessions.active.max",
    "tomcat.sessions.alive.max",
    "tomcat.sessions.created",
    "tomcat.sessions.expired",
    "tomcat.sessions.rejected"
  ]
}
액추에이터가 제공하는 메트릭 중 JVM 메모리 사용량을 살펴보자.
해당 엔드-포인트에서 제공하는 정보에 대한 설명을 볼 수 있다.
    
어느 정도 사용 중인지 바이트 단위로 알 수 있다.
어느 메모리 영역의 사용량인지 알 수 있다.
$ curl http://localhost:8080/actuator/metrics/jvm.memory.used | jq . 
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   330    0   330    0     0  90065      0 --:--:-- --:--:-- --:--:--  107k
{
  "name": "jvm.memory.used",
  "description": "The amount of used memory",
  "baseUnit": "bytes",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 118935248
    }
  ],
  "availableTags": [
    {
      "tag": "area",
      "values": [
        "heap",
        "nonheap"
      ]
    },
    {
      "tag": "id",
      "values": [
        "G1 Survivor Space",
        "Compressed Class Space",
        "Metaspace",
        "CodeCache",
        "G1 Old Gen",
        "G1 Eden Space"
      ]
    }
  ]
}
위에서 살펴본 것처럼 액추에이터는 애플리케이션의 상태에서부터 민감한 정보까지 제공한다. 그렇기에 불필요한 엔드-포인트들까지 노출하는 것은 문제가 될 수 있다. 다음과 같이 설정하면 필요한 엔드-포인트들만 노출할 수 있다.
management:
  endpoints:
    web:
      exposure:
        include: health, heapdump, threaddump, metrics
/actuator 경로에서 제공하는 정보를 확인해보자.
$ curl http://localhost:8080/actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   602    0   602    0     0   4023      0 --:--:-- --:--:-- --:--:--  4013
{
  "_links": {
    "self": {
      "href": "http://localhost:8080/actuator",
      "templated": false
    },
    "health": {
      "href": "http://localhost:8080/actuator/health",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:8080/actuator/health/{*path}",
      "templated": true
    },
    "heapdump": {
      "href": "http://localhost:8080/actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:8080/actuator/threaddump",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:8080/actuator/metrics/{requiredMetricName}",
      "templated": true
    },
    "metrics": {
      "href": "http://localhost:8080/actuator/metrics",
      "templated": false
    }
  }
}
2.2. Change port and API path
액추에이터는 애플리케이션 정보를 노출하고 많이 사용되는 라이브러리이기 때문에 잘 알려진 포트(port)나 기본 API 경로를 사용하는 것보다 변경 후 사용하는 것이 안전하다. 다음과 같은 설정으로 액추에이터 포트 번호와 앤드-포인트 경로를 변경할 수 있다.
management:
  endpoints:
    web:
      exposure:
        include: health, heapdump, threaddump, metrics
      base-path: /custom-actuator
  server:
    port: 9090
애플리케이션을 실행하면 다음과 같은 로그를 볼 수 있다.
톰캣 서버가 9090 포트를 활성화한다.
/custom-actuator 하위 경로에 액추에이터가 제공하는 정보들이 노출되어 있다.
2024-05-14T22:16:26.641+09:00  INFO 5048 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path ''
2024-05-14T22:16:26.704+09:00  INFO 5048 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port 9090 (http)
2024-05-14T22:16:26.705+09:00  INFO 5048 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2024-05-14T22:16:26.705+09:00  INFO 5048 --- [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.20]
2024-05-14T22:16:26.719+09:00  INFO 5048 --- [           main] o.a.c.c.C.[Tomcat-1].[localhost].[/]     : Initializing Spring embedded WebApplicationContext
2024-05-14T22:16:26.719+09:00  INFO 5048 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 75 ms
2024-05-14T22:16:26.732+09:00  INFO 5048 --- [           main] o.s.b.a.e.web.EndpointLinksResolver      : Exposing 4 endpoint(s) beneath base path '/custom-actuator'
2024-05-14T22:16:26.766+09:00  INFO 5048 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 9090 (http) with context path ''
2024-05-14T22:16:26.780+09:00  INFO 5048 --- [           main] action.in.blog.ActionInBlogApplication   : Started ActionInBlogApplication in 4.527 seconds (process running for 5.307)
다음과 같은 cURL 명령어로 애플리케이션 정보를 획득할 수 있다.
9090 포트 번호로 요청을 보낸다.
/custom-actuator 하위 경로에서 필요한 정보를 획득할 수 있다.
$ curl http://localhost:9090/custom-actuator | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   651    0   651    0     0   7158      0 --:--:-- --:--:-- --:--:--  7233
{
  "_links": {
    "self": {
      "href": "http://localhost:9090/custom-actuator",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:9090/custom-actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:9090/custom-actuator/health",
      "templated": false
    },
    "heapdump": {
      "href": "http://localhost:9090/custom-actuator/heapdump",
      "templated": false
    },
    "threaddump": {
      "href": "http://localhost:9090/custom-actuator/threaddump",
      "templated": false
    },
    "metrics": {
      "href": "http://localhost:9090/custom-actuator/metrics",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:9090/custom-actuator/metrics/{requiredMetricName}",
      "templated": true
    }
  }
}
TEST CODE REPOSITORY
https://github.com/Junhyunny/blog-in-action/tree/master/2024-05-15-spring-boot-actuator
REFERENCE
https://docs.spring.io/spring-boot/docs/current/actuator-api/htmlsingle/
https://docs.spring.io/spring-boot/docs/current/actuator-api/pdf/spring-boot-actuator-web-api.pdf
https://stackoverflow.com/questions/76794560/what-does-templated-false-mean-for-spring-boot-actuator
https://incheol-jung.gitbook.io/docs/study/srping-in-action-5th/chap-16.

Spring Boot Actuator

댓글