2025-04-08T19:56:24

2025-04-08 19:56:24 +09:00
parent a75a1dbd0f
commit eef061c1c9
100 changed files with 18639 additions and 0 deletions
--- a/docs/actuator/01_actuator.md
+++ b/docs/actuator/01_actuator.md
@@ -0,0 +1,98 @@
+좋아, 1부 "개요와 시작"을 간결하게 작성해볼게. 실무자가 빠르게 이해하고 따라 할 수 있도록 구성하고, 예시는 Gradle 기준으로 쓸게.
+
+---
+
+## **1부. 개요와 시작**
+
+---
+
+### **1장. 스프링 부트 액추에이터란?**
+
+#### 액추에이터의 개요
+
+- 스프링 부트 액추에이터(Spring Boot Actuator)는 애플리케이션의 상태, 성능, 메트릭, 로그 설정 등을 HTTP 엔드포인트로 노출하여 운영·모니터링을 쉽게 할 수 있도록 도와주는 기능이다.
+
+#### 주요 기능
+
+- Health 체크
+- 애플리케이션 정보 출력
+- 메트릭 수집 (CPU, 메모리, 요청 수 등)
+- HTTP 요청 추적
+- 로깅 레벨 변경
+- 사용자 정의 엔드포인트 구현
+
+---
+
+### **2장. 프로젝트 설정**
+
+#### Gradle 설정 예시
+
+```kotlin
+dependencies {
+    implementation 'org.springframework.boot:spring-boot-starter-actuator'
+    implementation 'org.springframework.boot:spring-boot-starter-web'
+}
+```
+
+#### 애플리케이션 실행
+
+```bash
+./gradlew bootRun
+```
+
+실행 후 `http://localhost:8080/actuator` 접속
+
+---
+
+### **3장. 기본 엔드포인트 살펴보기**
+
+#### 엔드포인트 목록
+
+- `/actuator/health` – 애플리케이션 상태 확인
+- `/actuator/info` – 앱 정보 출력
+- `/actuator/metrics` – 메트릭 데이터
+- `/actuator/loggers` – 로깅 레벨 제어
+- `/actuator/beans` – 빈 목록 출력
+- `/actuator/env` – 환경 변수 출력
+
+#### application.yml 설정 예시
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: "*"
+```
+
+> 기본적으로 대부분의 엔드포인트는 비공개이며, 위 설정으로 전체 노출 가능.
+
+---
+
+### **4장. 엔드포인트 테스트하기**
+
+#### curl로 확인
+
+```bash
+curl http://localhost:8080/actuator/health
+```
+
+#### 결과 예시
+
+```json
+{
+  "status": "UP"
+}
+```
+
+---
+
+### **5장. 요약**
+
+- 액추에이터는 스프링 부트에서 운영 편의성을 높이는 핵심 도구다.
+- 별도 서버 설치 없이 엔드포인트를 통해 상태, 성능, 설정 정보를 쉽게 확인할 수 있다.
+- Gradle로 간단히 의존성을 추가하고, `application.yml`로 노출 설정을 제어할 수 있다.
+
+---
+
+원하면 각 장에 더 많은 설명이나 예제를 추가해줄 수 있어. 다음은 2부 주요 엔드포인트 설명 들어가면 좋을 것 같아. 계속 이어서 쓸까?
--- a/docs/actuator/02_endpoints.md
+++ b/docs/actuator/02_endpoints.md
@@ -0,0 +1,190 @@
+좋아, 이어서 **2부. 주요 엔드포인트 상세 분석**을 작성해볼게. 실무에서 자주 쓰는 엔드포인트 중심으로 간결하게 구성하고, 예시도 함께 제공할게.
+
+---
+
+## **2부. 주요 엔드포인트 상세 분석**
+
+---
+
+### **6장. `/actuator/health` — 헬스 체크**
+
+#### 개요  
+애플리케이션의 현재 상태(UP, DOWN 등)를 알려주는 엔드포인트. 모니터링 시스템, 로드 밸런서의 상태 판단 기준으로 자주 사용됨.
+
+#### 기본 사용
+
+```bash
+curl http://localhost:8080/actuator/health
+```
+
+```json
+{
+  "status": "UP"
+}
+```
+
+#### 커스터마이징
+
+```yaml
+management:
+  endpoint:
+    health:
+      show-details: always
+```
+
+```json
+{
+  "status": "UP",
+  "components": {
+    "diskSpace": {
+      "status": "UP",
+      "details": {
+        "total": 500000000000,
+        "free": 480000000000,
+        "threshold": 10485760
+      }
+    }
+  }
+}
+```
+
+#### 사용자 정의 헬스 인디케이터
+
+```java
+@Component
+public class MyHealthIndicator implements HealthIndicator {
+    @Override
+    public Health health() {
+        return Health.up().withDetail("custom", "OK").build();
+    }
+}
+```
+
+---
+
+### **7장. `/actuator/info` — 정보 제공**
+
+#### 설정
+
+```yaml
+info:
+  app:
+    name: actuator-demo
+    version: 1.0.0
+```
+
+```bash
+curl http://localhost:8080/actuator/info
+```
+
+```json
+{
+  "app": {
+    "name": "actuator-demo",
+    "version": "1.0.0"
+  }
+}
+```
+
+#### Git 정보 포함하기
+
+`build.gradle`
+
+```kotlin
+plugins {
+    id "com.gorylenko.gradle-git-properties" version "2.4.0"
+}
+```
+
+```yaml
+management:
+  info:
+    git:
+      mode: full
+```
+
+---
+
+### **8장. `/actuator/metrics` — 메트릭 수집**
+
+#### 개요  
+CPU, 메모리, 요청 횟수 등 주요 리소스 사용량 정보를 제공함.
+
+```bash
+curl http://localhost:8080/actuator/metrics
+```
+
+```json
+{
+  "names": [
+    "jvm.memory.used",
+    "jvm.gc.memory.promoted",
+    "http.server.requests",
+    ...
+  ]
+}
+```
+
+#### 특정 메트릭 조회
+
+```bash
+curl http://localhost:8080/actuator/metrics/http.server.requests
+```
+
+---
+
+### **9장. `/actuator/loggers` — 로깅 레벨 제어**
+
+#### 현재 로깅 레벨 조회
+
+```bash
+curl http://localhost:8080/actuator/loggers/com.example
+```
+
+#### 런타임 레벨 변경
+
+```bash
+curl -X POST http://localhost:8080/actuator/loggers/com.example \
+     -H 'Content-Type: application/json' \
+     -d '{"configuredLevel": "DEBUG"}'
+```
+
+---
+
+### **10장. `/actuator/httptrace` — HTTP 요청 추적**
+
+> Spring Boot 2.6 이후 기본 미포함. 의존성 추가 필요.
+
+```kotlin
+implementation 'org.springframework.boot:spring-boot-starter-actuator'
+implementation 'org.springframework.boot:spring-boot-starter-web'
+implementation 'org.springframework.boot:spring-boot-actuator-autoconfigure'
+```
+
+```yaml
+management:
+  endpoint:
+    httptrace:
+      enabled: true
+  endpoints:
+    web:
+      exposure:
+        include: httptrace
+```
+
+---
+
+### **11장. 기타 엔드포인트 요약**
+
+| 엔드포인트         | 설명 |
+|------------------|------|
+| `/actuator/beans` | 등록된 스프링 빈 목록 |
+| `/actuator/env`   | 환경 변수 및 프로퍼티 확인 |
+| `/actuator/mappings` | URL-컨트롤러 매핑 확인 |
+| `/actuator/threaddump` | 스레드 덤프 출력 |
+| `/actuator/configprops` | `@ConfigurationProperties` 설정 확인 |
+| `/actuator/scheduledtasks` | 스케줄링된 작업 정보 확인 |
+
+---
+
+다음은 3부 **보안과 커스터마이징**으로 이어지면 좋아. 계속 이어서 써줄까?
--- a/docs/actuator/03_config.md
+++ b/docs/actuator/03_config.md
@@ -0,0 +1,162 @@
+좋아, 이어서 **3부. 보안과 커스터마이징**을 작성해볼게. 액추에이터를 실무에 적용할 때 꼭 필요한 보안 설정과 사용자 정의 방법을 중심으로 정리할게.
+
+---
+
+## **3부. 보안과 커스터마이징**
+
+---
+
+### **12장. 액추에이터 엔드포인트 보안**
+
+#### 기본 설정  
+Spring Security를 사용할 경우, 액추에이터 엔드포인트는 기본적으로 인증이 필요함.
+
+#### `application.yml`에서 노출 대상 설정
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health, info, metrics
+```
+
+#### WebSecurityConfigurer를 통한 제어
+
+```java
+@Configuration
+public class ActuatorSecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        http
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
+                .requestMatchers("/actuator/**").hasRole("ADMIN")
+                .anyRequest().authenticated()
+            )
+            .httpBasic();
+        return http.build();
+    }
+}
+```
+
+> 인증 필요 시 기본 사용자 정보는 `application.yml`에서 설정
+
+```yaml
+spring:
+  security:
+    user:
+      name: admin
+      password: admin123
+```
+
+---
+
+### **13장. 액추에이터 엔드포인트 커스터마이징**
+
+#### 엔드포인트 비활성화
+
+```yaml
+management:
+  endpoint:
+    metrics:
+      enabled: false
+```
+
+#### 엔드포인트 경로 변경
+
+```yaml
+management:
+  endpoints:
+    web:
+      base-path: /manage
+```
+
+> 결과: `/manage/health`, `/manage/info` 등의 경로로 변경됨
+
+#### 관리 포트를 분리
+
+```yaml
+management:
+  server:
+    port: 8081
+```
+
+> `/actuator`는 8081 포트에서만 노출됨. 일반 API는 기존 8080에서 제공됨
+
+---
+
+### **14장. 사용자 정의 엔드포인트 만들기**
+
+#### 기본 구조
+
+```java
+@Component
+@Endpoint(id = "customstatus")
+public class CustomStatusEndpoint {
+
+    @ReadOperation
+    public Map<String, Object> customStatus() {
+        return Map.of(
+            "service", "My Service",
+            "status", "Running",
+            "timestamp", Instant.now()
+        );
+    }
+}
+```
+
+> `GET /actuator/customstatus` 호출 시 결과 반환
+
+```json
+{
+  "service": "My Service",
+  "status": "Running",
+  "timestamp": "2025-04-07T10:00:00Z"
+}
+```
+
+#### WriteOperation 예시 (POST)
+
+```java
+@WriteOperation
+public String updateSomething(@Selector String id, @Nullable String value) {
+    // 업데이트 처리
+    return "Updated " + id + " to " + value;
+}
+```
+
+> POST `/actuator/customstatus/myconfig?value=test` 등으로 호출 가능
+
+---
+
+### **15장. 상태 분류 및 외부 연동 대응**
+
+#### Health 상태 분류 예시
+
+```yaml
+management:
+  health:
+    status:
+      http-mapping:
+        DOWN: 503
+        OUT_OF_SERVICE: 503
+        UP: 200
+        UNKNOWN: 200
+```
+
+> Kubernetes, AWS 등 상태 확인을 위한 HTTP 상태 코드 제어 가능
+
+---
+
+### **요약**
+
+- 액추에이터는 민감한 정보를 다루므로 보안 설정이 필수
+- 엔드포인트는 개별적으로 비활성화하거나 커스터마이징 가능
+- 사용자 정의 엔드포인트로 비즈니스 모니터링도 가능
+- 상태 값은 외부 환경(K8s 등)에 맞게 분류할 수 있음
+
+---
+
+다음은 **4부. 운영 환경 통합**으로 Prometheus, Grafana, Spring Boot Admin 같은 외부 시스템과의 통합 내용을 다루면 좋아. 계속 이어서 써줄까?
--- a/docs/actuator/04_prometheus.md
+++ b/docs/actuator/04_prometheus.md
@@ -0,0 +1,157 @@
+좋아, 이제 **4부. 운영 환경 통합**을 작성해볼게. 이 파트에서는 액추에이터를 실무에서 자주 사용하는 외부 도구들과 연동하는 방법을 다룰게. 특히 Prometheus, Grafana, Spring Boot Admin, 클라우드 환경 중심으로 구성할게.
+
+---
+
+## **4부. 운영 환경 통합**
+
+---
+
+### **16장. Prometheus & Grafana 연동**
+
+#### Micrometer + Prometheus 설정
+
+```kotlin
+dependencies {
+    implementation 'io.micrometer:micrometer-registry-prometheus'
+}
+```
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: prometheus
+  metrics:
+    export:
+      prometheus:
+        enabled: true
+```
+
+> 결과: `/actuator/prometheus` 엔드포인트에서 Prometheus 포맷의 메트릭 제공
+
+#### Prometheus 설정 예시 (`prometheus.yml`)
+
+```yaml
+scrape_configs:
+  - job_name: 'spring-app'
+    metrics_path: '/actuator/prometheus'
+    static_configs:
+      - targets: ['localhost:8080']
+```
+
+#### Grafana 대시보드 구성
+
+- 데이터 소스: Prometheus
+- 대시보드: Micrometer for JVM preset 사용 가능
+- JVM 메모리, GC, HTTP 요청 등 실시간 그래프 시각화
+
+---
+
+### **17장. Spring Boot Admin 연동**
+
+#### 의존성 추가
+
+```kotlin
+implementation 'de.codecentric:spring-boot-admin-starter-client'
+```
+
+#### 클라이언트 애플리케이션 설정
+
+```yaml
+spring:
+  boot:
+    admin:
+      client:
+        url: http://localhost:8081  # Spring Boot Admin 서버 주소
+```
+
+> 액추에이터 엔드포인트가 자동 등록되어 UI로 상태, 메트릭, 로그 등 확인 가능
+
+#### 서버 애플리케이션 설정 (별도 프로젝트)
+
+```kotlin
+dependencies {
+    implementation 'de.codecentric:spring-boot-admin-starter-server'
+    implementation 'spring-boot-starter-security'
+}
+```
+
+```java
+@EnableAdminServer
+@SpringBootApplication
+public class AdminServerApp {
+    public static void main(String[] args) {
+        SpringApplication.run(AdminServerApp.class, args);
+    }
+}
+```
+
+---
+
+### **18장. 클라우드 환경에서의 액추에이터 활용**
+
+#### Kubernetes 헬스체크에 활용
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /actuator/health/liveness
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /actuator/health/readiness
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 10
+```
+
+> `liveness`/`readiness` 구성은 아래처럼 사용자 정의 가능
+
+```java
+@Component("readiness")
+public class ReadinessHealthIndicator implements HealthIndicator {
+    @Override
+    public Health health() {
+        // DB 연결 확인, 외부 API 체크 등
+        return Health.up().build();
+    }
+}
+```
+
+#### AWS CloudWatch 또는 Azure Monitor 연동  
+- Micrometer에서 제공하는 별도 레지스트리 사용  
+- AWS 예시: `micrometer-registry-cloudwatch2` 사용  
+- Azure 예시: `micrometer-registry-azure-monitor`
+
+---
+
+### **19장. Docker + 액추에이터**
+
+#### Dockerfile 예시
+
+```dockerfile
+FROM openjdk:17
+COPY build/libs/app.jar app.jar
+EXPOSE 8080
+ENTRYPOINT ["java", "-jar", "app.jar"]
+```
+
+#### Docker + Prometheus 연동  
+- 동일 네트워크에서 Prometheus가 액추에이터 엔드포인트를 스크래핑하도록 구성  
+- 컨테이너 내에서 보안 설정이나 포트 노출 주의
+
+---
+
+### **요약**
+
+- 액추에이터는 Prometheus, Grafana, Spring Boot Admin 등 외부 도구와 쉽게 통합됨  
+- Kubernetes 등 클라우드 환경에서 liveness/readiness probe로 활용 가능  
+- 실시간 모니터링, 장애 탐지, 자원 사용량 분석에 필수적인 구성 요소임
+
+---
+
+이제 마지막 **5부. 실전 활용과 사례 연구**로 이어지면 완성형 실무서 느낌이 날 거야. 계속 써줄까?
--- a/docs/actuator/05_ex.md
+++ b/docs/actuator/05_ex.md
@@ -0,0 +1,146 @@
+좋아, 마지막 **5부. 실전 활용과 사례 연구**를 작성해볼게. 이 파트는 실무에서 액추에이터를 어떻게 문제 해결, 무중단 배포, 장애 대응에 활용할 수 있는지를 중심으로 구성할게.
+
+---
+
+## **5부. 실전 활용과 사례 연구**
+
+---
+
+### **20장. 액추에이터 기반 장애 진단**
+
+#### 메모리 부족 및 GC 감지
+
+- `/actuator/metrics/jvm.memory.used`, `/jvm.gc.pause` 활용
+- 메모리 사용량이 한계치 근접 시 Slack, 이메일 알림 연동 가능
+
+#### 예시: 알림 트리거 (Spring + Slack Webhook)
+
+```java
+if (memoryUsed > threshold) {
+    slackService.notify("Memory usage high: " + memoryUsed);
+}
+```
+
+---
+
+#### 슬로우 요청 감지
+
+- `/actuator/metrics/http.server.requests`
+- `max`, `mean`, `count`, `percentile` 등 분석 가능
+
+```json
+{
+  "name": "http.server.requests",
+  "measurements": [
+    { "statistic": "count", "value": 1500 },
+    { "statistic": "max", "value": 5.1 },
+    { "statistic": "mean", "value": 0.4 }
+  ]
+}
+```
+
+> 평균 응답 시간이 급증하면 서비스 병목 가능성 있음
+
+---
+
+### **21장. 헬스 체크 기반 무중단 배포 전략**
+
+#### Blue-Green / Rolling 배포
+
+- `readiness` 체크를 통해 트래픽 분산
+- 서비스 준비가 되지 않은 인스턴스는 요청을 받지 않음
+
+#### Kubernetes 예시
+
+```yaml
+readinessProbe:
+  httpGet:
+    path: /actuator/health/readiness
+    port: 8080
+```
+
+> readiness 상태가 `UP`이 될 때까지만 트래픽 전달
+
+---
+
+#### Custom readiness indicator
+
+```java
+@Component("readiness")
+public class CustomReadinessIndicator implements HealthIndicator {
+    public Health health() {
+        if (dbIsReady()) {
+            return Health.up().build();
+        }
+        return Health.down().withDetail("error", "DB not connected").build();
+    }
+}
+```
+
+---
+
+### **22장. 실무 프로젝트 적용 사례**
+
+#### 사례 1. 마이크로서비스 아키텍처 모니터링
+
+- 수십 개의 서비스 각각 `/actuator/health`, `/metrics` 제공
+- Prometheus가 모든 서비스 상태 및 메트릭 수집
+- Grafana에서 전체 시스템 상태 시각화
+
+#### 사례 2. 장애 조기 감지 시스템 구축
+
+- 액추에이터 메트릭 + 슬랙 연동
+- 알림 예시:
+  - DB 커넥션 풀 소진 경고
+  - 평균 응답 시간 증가
+  - 디스크 공간 부족
+
+#### 사례 3. 운영 리소스 최적화
+
+- `/metrics` 기반으로 JVM Heap 사이즈 분석
+- GC 튜닝 전후 성능 비교
+- 특정 컨트롤러 호출 수 분석하여 리팩토링 대상 선정
+
+---
+
+### **23장. 운영 자동화와 연동 사례**
+
+#### Jenkins + 액추에이터 연동
+
+- 배포 후 `/actuator/health`로 상태 확인 후 다음 스텝 진행
+- 실패 시 롤백 스크립트 실행
+
+#### 예시
+
+```groovy
+stage('Health Check') {
+    steps {
+        script {
+            def status = sh(script: 'curl -s http://app:8080/actuator/health | jq -r .status', returnStdout: true).trim()
+            if (status != 'UP') {
+                error("App is not healthy")
+            }
+        }
+    }
+}
+```
+
+---
+
+### **요약**
+
+- 액추에이터는 단순한 상태 확인 도구를 넘어, 장애 진단, 성능 분석, 배포 전략의 핵심 역할을 한다
+- 실시간 모니터링과 연동하면 복잡한 운영 환경에서도 안정성을 확보할 수 있다
+- 마이크로서비스, 클라우드, CI/CD 파이프라인 등 다양한 환경에서 유용하게 쓰인다
+
+---
+
+### **부록**
+
+- A. 주요 설정 정리표
+- B. Micrometer 메트릭 이름과 설명 목록
+- C. 에러 사례별 Trouble Shooting 가이드
+
+---
+
+이걸로 **스프링 부트 액추에이터 실전 가이드**의 전체 구성은 완성이야. 필요하다면 각 부에 대해 더 자세한 세부 목차나 코드 중심 실습 내용도 추가할 수 있어. 출간용 원고로 다듬을 계획이야?
--- a/docs/actuator/06_setting.md
+++ b/docs/actuator/06_setting.md
@@ -0,0 +1,65 @@
+좋아, 주요 설정들을 `application.yml` 형식으로 실무에 바로 적용할 수 있게 정리해줄게. 설명이 필요한 항목에는 주석도 달아뒀어.
+
+---
+
+```yaml
+# Actuator 엔드포인트 노출 설정
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health, info, metrics, prometheus, loggers, customstatus
+      base-path: /actuator  # 기본 경로 변경 가능
+  endpoint:
+    health:
+      show-details: always       # 상세 정보 노출 (UP, DOWN 원인 포함)
+      status:
+        http-mapping:
+          UP: 200
+          DOWN: 503
+          OUT_OF_SERVICE: 503
+          UNKNOWN: 200
+    metrics:
+      enabled: true
+    prometheus:
+      enabled: true
+    loggers:
+      enabled: true
+
+  metrics:
+    export:
+      prometheus:
+        enabled: true  # Prometheus 연동 시 필수
+
+  server:
+    port: 8080  # Actuator 별도 포트 지정 가능
+
+# info 엔드포인트에 표시할 정보
+info:
+  app:
+    name: actuator-demo
+    version: 1.0.0
+  author: your-name
+
+# 보안 설정 예시 (기본 사용자)
+spring:
+  security:
+    user:
+      name: admin
+      password: admin123
+
+# Spring Boot Admin 연동 시
+spring:
+  boot:
+    admin:
+      client:
+        url: http://localhost:8081  # Admin 서버 주소
+
+# 커스텀 readiness 체크용 헬스 인디케이터 활용 시
+# readinessProbe, livenessProbe와 연동 가능
+# (이 설정은 Kubernetes 매니페스트에서 활용됨)
+```
+
+---
+
+필요하다면 `logging`, `management.trace.http`, `custom endpoint` 관련 설정도 추가할 수 있어. 특정 환경(AWS, Docker, K8s 등)에 맞춰 세부 설정도 정리해줄까?
--- a/docs/actuator/07_metric.md
+++ b/docs/actuator/07_metric.md
@@ -0,0 +1,35 @@
+좋아, Spring Boot Actuator에서 Micrometer를 통해 기본 제공되는 **주요 메트릭 이름과 설명**을 실무 중심으로 정리해줄게. 아래 표는 JVM, HTTP, DB 연결, 시스템 리소스 관련 메트릭들을 중심으로 구성했어.
+
+---
+
+### **Actuator 메트릭 이름 정리표**
+
+| 메트릭 이름                           | 설명                                                                 |
+|--------------------------------------|----------------------------------------------------------------------|
+| `jvm.memory.used`                    | JVM 힙/비힙 메모리 사용량                                            |
+| `jvm.memory.max`                     | JVM 최대 힙/비힙 메모리 크기                                         |
+| `jvm.gc.pause`                       | GC 수행 시간 (pause 시간)                                           |
+| `jvm.threads.live`                   | 현재 살아있는 쓰레드 수                                             |
+| `jvm.threads.daemon`                | 데몬 쓰레드 수                                                       |
+| `jvm.threads.peak`                   | 피크 쓰레드 수                                                       |
+| `system.cpu.usage`                   | 시스템 전체 CPU 사용률 (0.0 ~ 1.0)                                   |
+| `process.cpu.usage`                 | 현재 애플리케이션의 CPU 사용률 (0.0 ~ 1.0)                           |
+| `system.load.average.1m`             | 1분 평균 시스템 부하                                                 |
+| `disk.free`                          | 남은 디스크 공간 (바이트)                                            |
+| `disk.total`                         | 전체 디스크 용량 (바이트)                                            |
+| `http.server.requests`              | HTTP 요청 수, 응답 시간, 에러 비율 등                               |
+| `tomcat.sessions.active.current`     | 현재 활성 세션 수                                                    |
+| `tomcat.sessions.rejected`          | 최대 세션 초과로 거절된 세션 수                                      |
+| `tomcat.threads.current`             | 현재 사용 중인 톰캣 쓰레드 수                                        |
+| `logback.events`                     | 로그 수준별 로깅 이벤트 수 (info, warn, error 등)                   |
+| `datasource.connections.active`      | 현재 사용 중인 DB 커넥션 수                                          |
+| `datasource.connections.max`         | 최대 커넥션 수                                                       |
+| `datasource.connections.pending`     | 대기 중인 커넥션 요청 수                                             |
+| `hikaricp.connections.active`        | HikariCP에서 사용 중인 커넥션 수                                     |
+| `hikaricp.connections.idle`          | 유휴 커넥션 수                                                       |
+| `hikaricp.connections.max`           | 최대 커넥션 수                                                       |
+| `hikaricp.connections.pending`       | 커넥션 풀에 요청 대기 중인 수                                        |
+
+---
+
+필요하면 특정 메트릭의 `tag` 구조(예: `uri`, `status`, `exception` 등)나, Prometheus에서 쿼리하는 예시도 함께 정리해줄 수 있어. 원할까?
--- a/docs/actuator/README.md
+++ b/docs/actuator/README.md
@@ -0,0 +1,93 @@
+좋아, 스프링 부트 액추에이터(Spring Boot Actuator)를 주제로 한 책이라면 실무적인 모니터링, 상태 점검, 보안, 커스터마이징까지 다루는 구성이 좋을 것 같아. 아래는 그에 맞춰 제안하는 목차야:
+
+---
+
+### **스프링 부트 액추에이터 실전 가이드**
+
+#### **1부. 개요와 시작**
+
+1. 스프링 부트 액추에이터란?
+   - 모니터링의 필요성
+   - 액추에이터의 기본 개념
+2. 기본 설정과 의존성 추가
+   - Gradle/Maven 설정
+   - 기본 endpoint 확인
+3. `/actuator` 엔드포인트 둘러보기
+   - 기본으로 제공되는 엔드포인트 목록
+   - Health, Info, Metrics 등 소개
+
+---
+
+#### **2부. 주요 엔드포인트 상세 분석**
+
+4. Health 엔드포인트
+   - 커스터마이징
+   - 구성 요소 상태 추가
+5. Info 엔드포인트
+   - Git 정보 연동
+   - 커스텀 정보 추가하기
+6. Metrics 엔드포인트
+   - Micrometer와 통합
+   - 주요 메트릭 수집 항목 설명
+7. Loggers 엔드포인트
+   - 런타임 로깅 레벨 변경
+8. HTTP Trace & Mappings
+   - HTTP 요청 추적
+   - 매핑 정보 노출
+9. Beans, Conditions, Configprops
+   - 빈 목록과 의존성 분석
+   - 자동 구성 진단
+
+---
+
+#### **3부. 보안과 커스터마이징**
+
+10. 액추에이터 엔드포인트 보안
+    - WebSecurityConfigurer 설정
+    - Role 기반 접근 제어
+11. 엔드포인트 커스터마이징
+    - 경로, 활성화 여부, 노출 수준 조정
+    - Management 포트 분리
+12. 사용자 정의 엔드포인트 만들기
+    - @Endpoint, @ReadOperation 등 사용법
+    - RESTful 스타일로 확장
+
+---
+
+#### **4부. 운영 환경 통합**
+
+13. Prometheus, Grafana와의 연동
+    - Micrometer Prometheus 설정
+    - Grafana 대시보드 구성
+14. Spring Boot Admin과 통합
+    - 관리 UI 제공
+    - 서비스 헬스 체크 및 메트릭 확인
+15. 클라우드 환경에서의 액추에이터
+    - Kubernetes, AWS 등에서 활용하기
+    - 헬스 프로브로 활용
+
+---
+
+#### **5부. 실전 활용과 사례 연구**
+
+16. 액추에이터 기반 장애 진단
+    - CPU, GC, Memory 추적
+    - 슬로우 요청 분석
+17. 서비스 헬스 기반 무중단 배포
+    - Readiness / Liveness 체크
+    - 롤링 배포 전략과 연계
+18. 실무 프로젝트 적용 사례
+    - 마이크로서비스에서의 활용
+    - 로깅/모니터링 통합 전략
+
+---
+
+#### **부록**
+
+- A. 액추에이터 전체 설정 옵션 정리
+- B. Micrometer 주요 태그 및 메트릭 종류
+- C. Trouble Shooting 가이드
+
+---
+
+이 구성은 기초부터 시작해 실전 배포 환경까지 연결되도록 구성했어. 필요하면 각 장을 좀 더 쪼개거나, Kubernetes, AWS, Docker 등 특정 환경에 초점을 둔 부록도 추가할 수 있어. 원하면 각 장의 세부 목차도 만들어줄게.