spakky-actuator 6.8.0

Transport-neutral actuator health and info contracts for Spakky Framework

Spakky Actuator

Spakky Framework를 위한 transport 중립 actuator 계약입니다. Health, readiness, liveness, info 상태를 HTTP나 CLI adapter와 분리된 모델로 집계합니다.

설치

pip install spakky-actuator

주요 기능

• Health/readiness/liveness 결과: HTTP, CLI 등 adapter가 공유하는 result 계약
• Probe 확장 지점: Spakky DI로 등록되는 동기/비동기 health probe
• Info contributor: 동기/비동기 info contributor의 결정적 병합
• Startup diagnostics contributor: SpakkyApplication startup report를 actuator info로 노출
• 예외 처리: Probe 예외를 구조화된 에러 상세가 포함된 비정상 component result로 변환
• Transport 중립 core: FastAPI, Typer, plugin adapter 의존성 없음

Endpoint Semantics

Surface	Meaning	Default behavior
health	operator-facing status check용 aggregate application health	ActuatorEndpoint.HEALTH를 endpoints에 포함하는 probe 평가
readiness	app이 traffic 또는 work를 받을 준비가 되었는지	readiness probe 평가; 필수 unhealthy probe가 있으면 결과 unhealthy
liveness	process/framework 생존 여부	외부 dependency readiness와 분리; custom liveness probe가 없으면 healthy baseline 반환
info	결정적 application metadata	등록된 info contributor를 contributor 이름 기준으로 병합

기본적으로 health probe는 liveness가 아니라 health와 readiness에 참여합니다. 외부 의존성을 사용할 수 없다는 이유로 실패하면 안 되는 프로세스 내부 check에만 ActuatorEndpoint.LIVENESS를 사용하세요.

빠른 시작

from spakky.actuator import (
    AbstractHealthProbe,
    ActuatorAggregationService,
    ComponentHealthResult,
)
from spakky.core.application.application import SpakkyApplication
from spakky.core.application.application_context import ApplicationContext
from spakky.core.application.plugin import Plugin
from spakky.core.pod.annotations.pod import Pod


@Pod()
class DatabaseProbe(AbstractHealthProbe):
    @property
    def name(self) -> str:
        return "database"

    def check(self) -> ComponentHealthResult:
        return ComponentHealthResult.healthy(self.name)


app = (
    SpakkyApplication(ApplicationContext())
    .load_plugins(include={Plugin(name="spakky-actuator")})
    .add(DatabaseProbe)
    .start()
)
service = app.container.get(type_=ActuatorAggregationService)
health = service.evaluate_health()
readiness = service.evaluate_readiness()

Extension Points

Component health를 제공하려면 AbstractHealthProbe 또는 AbstractAsyncHealthProbe Pod를 등록하세요. info에 metadata를 제공하려면 IInfoContributor 또는 IAsyncInfoContributor Pod를 등록하세요. Actuator 플러그인은 ActuatorExtensionPostProcessor를 추가하여 DI가 관리하는 extension Pod를 발견하고 ActuatorExtensionRegistry에 저장합니다.

from spakky.actuator import (
    AbstractHealthProbe,
    IInfoContributor,
    ActuatorEndpoint,
    ComponentHealthResult,
)
from spakky.core.pod.annotations.pod import Pod


@Pod()
class ProcessProbe(AbstractHealthProbe):
    @property
    def name(self) -> str:
        return "process"

    @property
    def endpoints(self) -> tuple[ActuatorEndpoint, ...]:
        return (ActuatorEndpoint.LIVENESS,)

    def check(self) -> ComponentHealthResult:
        return ComponentHealthResult.healthy(self.name)


@Pod()
class BuildInfo(IInfoContributor):
    @property
    def name(self) -> str:
        return "build"

    def contribute_info(self) -> dict[str, object]:
        return {"version": "1.0.0"}

Backend plugin은 자신이 소유한 외부 의존 상태를 first-party probe/contributor로 등록합니다. 예를 들어 spakky-redis는 Redis 연결 상태와 cache metrics를 actuator health/info에 연결합니다. 애플리케이션은 transport adapter를 바꾸지 않고 같은 계약으로 자체 check를 추가할 수 있습니다.

라이선스

MIT License