Summary
모든 Croco 앱이 표준 operational surface를 갖도록 health, readiness, diagnostics, metrics, runtime metadata, CLI status view를 정리한다.
이 기능은 “앱이 실행된다”를 넘어 “앱을 운영할 수 있다”를 Croco의 기본값으로 만드는 작업이다. 첫 버전의 목표는 대시보드가 아니라 안정적인 JSON contract와 CLI viewer다.
Product Narrative
운영자는 Croco 앱이 어떤 상태인지 빠르게 알고 싶다.
- 앱이 살아 있는가?
- dependency가 준비되었는가?
- diagnostics provider 중 실패하거나 느린 것이 있는가?
- 최근 error history는 무엇인가?
- 어떤 Croco modules/runtime/build version으로 실행 중인가?
- telemetry가 활성화되어 있고 flush 가능한가?
이 정보는 runtime과 deployment target이 달라도 같은 shape로 노출되어야 한다.
Why This Matters
- SaaS/B2B 백엔드에서 즉시 체감되는 완성도다.
- Runtime Contract Matrix와 직접 연결된다.
- diagnostics/health 구현 중복과 contract divergence를 줄인다.
- 이후 web console이 필요해져도 안정적인 API foundation이 생긴다.
MVP Scope
Standard endpoints
/health: process liveness 중심./ready: dependency readiness 중심./diagnostics: component-level status, runtime/build/module metadata, recent errors./metrics: 최소한의 framework metrics 또는 exporter integration point.
Diagnostics policy
- provider name duplicate 정책.
- provider timeout과 degraded fallback.
- provider failure message truncation과 safe serialization.
- recent error ring buffer contract.
CLI viewer
croco ops status <url> 형태의 JSON/pretty output.- CI나 smoke test에서 사용할 수 있는 machine-readable output.
Non-Goals
- 첫 버전에서 full web dashboard를 만들지 않는다.
- vendor-specific APM/observability integration은 표준 contract 이후로 미룬다.
- 모든 package가 처음부터 provider를 구현해야 하는 것은 아니다.
Design Constraints
- health와 diagnostics의 status vocabulary를 한 곳에서 정의한다.
- 느린 provider 하나가 전체 diagnostics response를 멈추면 안 된다.
- 운영 endpoint는 기본적으로 민감정보를 노출하지 않아야 한다.
- HTTP adapter는 core contract를 표현하는 역할에 집중한다.
Suggested Breakdown
health-core, diagnostics-core, transports-http의 현재 health/diagnostics shape를 비교한다.- canonical operational contract와 status vocabulary를 정의한다.
- diagnostics provider duplicate/timeout policy를 구현한다.
- HTTP endpoint serializer를 표준 contract에 맞춘다.
- runtime/build/module metadata provider를 추가한다.
- error history provider를 안정화한다.
- CLI viewer를 추가한다.
- docs에 endpoint 보안/노출 정책을 명시한다.
Acceptance Criteria
- 운영 endpoint가 runtime별로 일관된 JSON shape를 반환한다.
- diagnostics provider가 hang되어도 전체 report는 timeout 안에 반환된다.
- duplicate provider name은 조용히 overwrite되지 않는다.
- health/readiness aggregate status vocabulary가 하나로 정리된다.
- CLI viewer가 endpoint output을 읽고 사람이 볼 수 있는 상태 요약을 출력한다.
Validation Strategy
pnpm test --filter=@croco/diagnostics-corepnpm test --filter=@croco/health-corepnpm test --filter=@croco/transports-http- endpoint contract snapshot or schema tests
- hanging provider fake timer test
- CLI status smoke test
Related Issues
Seed issues:
Done When
새 Croco 앱이 별도 구현 없이 표준 운영 endpoint와 CLI status view를 제공하고, 운영자가 runtime/package/module 상태를 안전하게 확인할 수 있을 때 완료로 본다.
Summary
모든 Croco 앱이 표준 operational surface를 갖도록 health, readiness, diagnostics, metrics, runtime metadata, CLI status view를 정리한다.
이 기능은 “앱이 실행된다”를 넘어 “앱을 운영할 수 있다”를 Croco의 기본값으로 만드는 작업이다. 첫 버전의 목표는 대시보드가 아니라 안정적인 JSON contract와 CLI viewer다.
Product Narrative
운영자는 Croco 앱이 어떤 상태인지 빠르게 알고 싶다.
이 정보는 runtime과 deployment target이 달라도 같은 shape로 노출되어야 한다.
Why This Matters
MVP Scope
Standard endpoints
/health: process liveness 중심./ready: dependency readiness 중심./diagnostics: component-level status, runtime/build/module metadata, recent errors./metrics: 최소한의 framework metrics 또는 exporter integration point.Diagnostics policy
CLI viewer
croco ops status <url>형태의 JSON/pretty output.Non-Goals
Design Constraints
Suggested Breakdown
health-core,diagnostics-core,transports-http의 현재 health/diagnostics shape를 비교한다.Acceptance Criteria
Validation Strategy
pnpm test --filter=@croco/diagnostics-corepnpm test --filter=@croco/health-corepnpm test --filter=@croco/transports-httpRelated Issues
Seed issues:
Done When
새 Croco 앱이 별도 구현 없이 표준 운영 endpoint와 CLI status view를 제공하고, 운영자가 runtime/package/module 상태를 안전하게 확인할 수 있을 때 완료로 본다.