관찰성 — Health Check, Metrics, OpenTelemetry로 운영 준비하기

./mvnw quarkus:add-extension -Dextensions="smallrye-health"

// GET /q/health
{
  "status": "UP",
  "checks": [
    {
      "name": "Database connections health check",
      "status": "UP",
      "data": {
        "<default>": "UP"
      }
    }
  ]
}

@Liveness
@ApplicationScoped
public class ExternalApiHealthCheck implements HealthCheck {

    @Inject
    ExternalApiClient apiClient;

    @Override
    public HealthCheckResponse call() {
        try {
            apiClient.ping();
            return HealthCheckResponse.up("외부 API 연결");
        } catch (Exception e) {
            return HealthCheckResponse.named("외부 API 연결")
                .down()
                .withData("error", e.getMessage())
                .build();
        }
    }
}

@Readiness
@ApplicationScoped
public class CacheHealthCheck implements HealthCheck {

    @Inject
    CacheManager cacheManager;

    @Override
    public HealthCheckResponse call() {
        boolean cacheAvailable = cacheManager.isAvailable();
        return HealthCheckResponse.named("캐시 서비스")
            .status(cacheAvailable)
            .withData("provider", "Redis")
            .build();
    }
}

# Health Check + Kubernetes 확장이 함께 있으면 자동 설정
# 필요시 커스터마이징
quarkus.kubernetes.liveness-probe.initial-delay=5s
quarkus.kubernetes.liveness-probe.period=10s
quarkus.kubernetes.readiness-probe.initial-delay=5s
quarkus.kubernetes.readiness-probe.failure-threshold=3
quarkus.kubernetes.startup-probe.initial-delay=0s
quarkus.kubernetes.startup-probe.period=2s
quarkus.kubernetes.startup-probe.failure-threshold=30

./mvnw quarkus:add-extension -Dextensions="micrometer-registry-prometheus"

# GET /q/metrics 응답 일부

# HTTP 요청 메트릭
http_server_requests_seconds_count{method="GET",uri="/api/users",status="200"} 1523.0
http_server_requests_seconds_sum{method="GET",uri="/api/users",status="200"} 45.3

# JVM 힙 메모리
jvm_memory_used_bytes{area="heap",id="G1 Eden Space"} 52428800.0
jvm_memory_max_bytes{area="heap",id="G1 Old Gen"} 536870912.0

# 커넥션 풀
agroal_active_count{datasource="default"} 5
agroal_available_count{datasource="default"} 15

@ApplicationScoped
@Path("/orders")
public class OrderResource {

    @Inject
    MeterRegistry registry;

    // Counter: 주문 생성 횟수
    @POST
    public Response createOrder(OrderDto order) {
        Order created = orderService.create(order);

        registry.counter("orders.created",
            "type", order.getType(),
            "region", order.getRegion()
        ).increment();

        return Response.created(URI.create("/orders/" + created.getId())).build();
    }

    // Timer: 외부 결제 API 호출 시간 측정
    public PaymentResult processPayment(PaymentRequest request) {
        return registry.timer("payment.processing")
            .record(() -> paymentClient.process(request));
    }

    // Gauge: 현재 처리 대기 중인 주문 수
    @PostConstruct
    void initGauges() {
        registry.gauge("orders.pending", orderQueue, Queue::size);
    }
}

@ApplicationScoped
public class NotificationService {

    @Counted(value = "notifications.sent", description = "발송된 알림 수")
    @Timed(value = "notifications.duration", description = "알림 발송 소요 시간")
    public void sendNotification(String userId, String message) {
        // 알림 발송 로직
    }
}

# prometheus.yml
scrape_configs:
  - job_name: 'quarkus-app'
    metrics_path: '/q/metrics'
    scrape_interval: 15s
    static_configs:
      - targets: ['my-app:8080']

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-app-monitor
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: my-app
  endpoints:
    - port: http
      path: /q/metrics
      interval: 15s

./mvnw quarkus:add-extension -Dextensions="opentelemetry"

# application.properties

# OTLP 엔드포인트 설정 (Jaeger, Tempo 등)
quarkus.otel.exporter.otlp.endpoint=http://jaeger:4317

# 서비스 이름
quarkus.otel.resource.attributes=service.name=my-app

# 샘플링 비율 (1.0 = 100%, 0.1 = 10%)
quarkus.otel.traces.sampler=parentbased_traceidratio
quarkus.otel.traces.sampler.arg=1.0

@ApplicationScoped
public class RecommendationService {

    @Inject
    Tracer tracer;

    public List<Product> getRecommendations(String userId) {
        Span span = tracer.spanBuilder("recommendations.compute")
            .setAttribute("user.id", userId)
            .startSpan();

        try (Scope scope = span.makeCurrent()) {
            // 추천 알고리즘 실행
            List<Product> candidates = fetchCandidates(userId);
            span.addEvent("후보 상품 조회 완료", Attributes.of(
                AttributeKey.longKey("candidate.count"), (long) candidates.size()
            ));

            List<Product> ranked = rankProducts(candidates, userId);
            span.addEvent("랭킹 완료");

            return ranked;
        } catch (Exception e) {
            span.setStatus(StatusCode.ERROR, e.getMessage());
            span.recordException(e);
            throw e;
        } finally {
            span.end();
        }
    }
}

@ApplicationScoped
public class PaymentService {

    @WithSpan("payment.process")
    public PaymentResult processPayment(
            @SpanAttribute("payment.method") String method,
            @SpanAttribute("payment.amount") double amount) {
        // 결제 로직
        return new PaymentResult(true);
    }
}

docker run -d --name jaeger \
  -p 16686:16686 \   # Jaeger UI
  -p 4317:4317 \     # OTLP gRPC
  jaegertracing/all-in-one:latest

import io.quarkus.logging.Log;

@ApplicationScoped
public class UserService {

    public User findUser(String id) {
        Log.infof("사용자 조회: id=%s", id);
        // ...
    }
}

./mvnw quarkus:add-extension -Dextensions="logging-json"

# JSON 로깅 활성화
quarkus.log.console.json=true

# 추가 필드
quarkus.log.console.json.additional-field.service.value=my-app
quarkus.log.console.json.additional-field.environment.value=production

{
  "timestamp": "2026-03-28T10:15:30.123Z",
  "level": "INFO",
  "loggerName": "c.e.UserService",
  "message": "사용자 조회: id=user-123",
  "service": "my-app",
  "environment": "production",
  "traceId": "abc123def456",
  "spanId": "789ghi"
}

# 전체 로그 레벨
quarkus.log.level=INFO

# 패키지별 로그 레벨
quarkus.log.category."com.example".level=DEBUG
quarkus.log.category."org.hibernate.SQL".level=DEBUG

# 파일 출력
quarkus.log.file.enable=true
quarkus.log.file.path=/var/log/my-app.log
quarkus.log.file.rotation.max-file-size=10M
quarkus.log.file.rotation.max-backup-index=5

# Dev Mode 실행
./mvnw quarkus:dev

# DevServices 관련 설정 (기본값으로도 충분하지만 커스터마이징 가능)
quarkus.otel.exporter.otlp.endpoint=http://localhost:4317

# Dev Mode에서만 전체 트레이스 수집
%dev.quarkus.otel.traces.sampler.arg=1.0

# 프로덕션에서는 10%만 수집
%prod.quarkus.otel.traces.sampler.arg=0.1

Quarkus App
  ├── /q/health → Kubernetes Probe
  ├── /q/metrics → Prometheus → Grafana (대시보드)
  └── OTLP export → Tempo/Jaeger (트레이싱)
                  → Loki (로그 수집)

# application.properties — 관찰성 통합 설정

# Health
# (smallrye-health 확장만 추가하면 자동 설정)

# Metrics → Prometheus
# (micrometer-registry-prometheus 확장)
quarkus.micrometer.export.prometheus.path=/q/metrics

# OpenTelemetry → Tempo/Jaeger
quarkus.otel.exporter.otlp.endpoint=http://tempo:4317
quarkus.otel.resource.attributes=service.name=my-app,service.version=1.0.0

# 프로파일별 샘플링 비율
%dev.quarkus.otel.traces.sampler.arg=1.0
%prod.quarkus.otel.traces.sampler.arg=0.1

# JSON 로깅
%prod.quarkus.log.console.json=true