본문으로 건너뛰기

Health Check 통합 가이드

Caffeine Framework의 Health Check 엔드포인트 구성 및 운영 가이드입니다.

개요​

Caffeine은 ASP.NET Core의 Health Checks 미들웨어를 기반으로 두 가지 엔드포인트를 제공합니다:

엔드포인트용도설명
GET /healthLiveness서비스 전체 생존 여부 확인 (Kubernetes liveness probe)
GET /health/readyReadiness드라이버 준비 상태 확인 (Docker/Nginx/Traefik 연동)

Bridge.Host HealthCheck​

Caffeine.Bridge.Host는 v2.0.4부터 포트 5100에서 HTTP HealthCheck 엔드포인트를 제공합니다.

아키텍처​

Bridge.Host (port 5100)
  ├─ GET /health        → 전체 liveness
  └─ GET /health/ready  → DriverHealthCheck (readiness 태그 필터)

엔드포인트 응답​

정상 상태 (/health):

{
  "status": "Healthy",
  "results": {
    "driver": {
      "status": "Healthy",
      "description": "드라이버 정상 동작 중",
      "data": {
        "driverId": "modbus-tcp-01",
        "driverType": "ModbusTcp"
      }
    }
  }
}

이상 상태 (/health/ready):

{
  "status": "Unhealthy",
  "results": {
    "driver": {
      "status": "Unhealthy",
      "description": "드라이버 ID 미설정"
    }
  }
}

HTTP 상태 코드: 정상 200 OK, 이상 503 Service Unavailable

DriverHealthCheck 구현​

src/Caffeine.Bridge.Host/Health/DriverHealthCheck.cs:

public sealed class DriverHealthCheck : IHealthCheck
{
    private readonly IDriverModule _driver;

    public DriverHealthCheck(IDriverModule driver) => _driver = driver;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var data = new Dictionary<string, object>
        {
            ["driverId"]   = _driver.DriverId,
            ["driverType"] = _driver.DriverType
        };

        var isReady = !string.IsNullOrEmpty(_driver.DriverId);
        return Task.FromResult(isReady
            ? HealthCheckResult.Healthy("드라이버 정상 동작 중", data)
            : HealthCheckResult.Unhealthy("드라이버 ID 미설정", data: data));
    }
}

Program.cs 등록 패턴​

Host 앱에서 HealthCheck를 등록하는 표준 패턴입니다:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((ctx, services) =>
    {
        services.AddHealthChecks()
            .AddCheck<DriverHealthCheck>("driver", tags: new[] { "readiness" });
    })
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseUrls("http://*:5100");
        webBuilder.Configure(app =>
        {
            app.UseRouting();
            app.UseEndpoints(endpoints =>
            {
                // Liveness — 전체 체크
                endpoints.MapHealthChecks("/health");

                // Readiness — "readiness" 태그만 필터
                endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions
                {
                    Predicate = check => check.Tags.Contains("readiness")
                });
            });
        });
    })
    .Build();

MQTT HealthCheck​

CoreFarm 모듈은 MQTT 연결 상태를 체크하는 MqttHealthCheck를 AddCoreFarm() 시 자동 등록합니다:

// AddCoreFarm()이 내부적으로 등록
services.AddHealthChecks()
    .AddCheck<MqttHealthCheck>("mqtt", tags: new[] { "readiness" });

Host 앱에서 MapHealthChecks를 등록해야 외부에 노출됩니다.

Docker Compose 연동​

services:
  bridge-host:
    image: caffeine/bridge-host:2.0.4
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5100/health/ready"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    ports:
      - "5100:5100"

Kubernetes Probe 설정​

livenessProbe:
  httpGet:
    path: /health
    port: 5100
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health/ready
    port: 5100
  initialDelaySeconds: 15
  periodSeconds: 5

Nginx 리버스 프록시​

upstream bridge_health {
    server bridge-host:5100;
}

location /health {
    proxy_pass http://bridge_health/health;
}

문제 해결​

503 Service Unavailable​

  1. 드라이버가 올바르게 DI에 등록되었는지 확인
  2. driver_settings.json에 드라이버 정의가 있는지 확인
  3. Bridge.Host 로그에서 드라이버 초기화 오류 확인

포트 충돌​

Bridge.Host 기본 포트 5100이 이미 사용 중이면 환경변수로 변경:

ASPNETCORE_URLS=http://*:5200 dotnet run --project src/Caffeine.Bridge.Host

관련 문서​

작성일: 2026-02-28 버전: 2.0.4