어노테이션 기반 모니터링 — 하나의 어노테이션, 여러 컴포넌트
이 예제는 컴포넌트별 features: 블록을 하나도 작성하지 않고 중첩된 토폴로지 전반의 서비스 여섯 개에 모니터링 Feature를 연결합니다. 최상위 경계에 둔 운영자 어노테이션 하나가 두 개의 하위 트리 재정의로 세분화되고, Manifest의 features.annotations 바인딩을 통해 포함된 모든 컴포넌트에 대한
core/prometheus-exporter 연결로 확장되며, 각 컴포넌트는 자체 Prometheus ServiceMonitor를 렌더링합니다.
이것이 어노테이션 기반 Feature 확장 영역입니다. 반복적인 컴포넌트별 Feature 연결을 경계 트리를 따라 아래로 전파되는 단일 어노테이션으로 압축하는 패턴입니다.
구조
- **개발자 의도(
aggregate.yaml)**는example/compute/service컴포넌트 여섯 개, 즉gateway와api/worker/ledger/etl/reconcile만 선언합니다. 어떤 컴포넌트도 모니터링features:블록을 갖지 않습니다. - **Manifest(
manifest.yaml)**는 어노테이션을 Feature에 바인딩합니다.features:type:core/prometheus-exporter: helm/prometheus-exporter:1.0.0 # the FeatureRecipe version bindingannotations:feature.aggrega.ai/monitoring:feature: core/prometheus-exportermaps:infra: [interval, port, path] # structured-value subkeys → the feature's infra - **Release(
release.yaml)**는platform경계에 어노테이션을 한 번 설정하고 하위 트리별로 세분화합니다.platform:annotations:feature.aggrega.ai/monitoring: {interval: 30s, port: metrics, path: /metrics} # gateway inherits thisboundaries:payments:annotations:feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledgerbatch:annotations:feature.aggrega.ai/monitoring: {interval: 120s} # etl/reconcile
core/prometheus-exporter와 그 컴포넌트 범위 ServiceMonitor FeatureRecipe는 표준 카탈로그에서 가져와 사용합니다(이 예제는 로컬 사본을 선언하지 않습니다). 레시피의 차트는 연결된 컴포넌트마다 monitoring.coreos.com/v1 ServiceMonitor 하나를 내보내며, 해석된 어노테이션에서 interval/port/path를 템플릿으로 채웁니다. 세 가지 모두 feature의 infra에 있는 운영자 스크레이프 설정값입니다. (이는 FeatureRecipe 리소스 생성, 즉 helm provider가 렌더링하는 source: + valuesMapping:이며, Wasm 뮤테이터나 파이프라인 단계가 아닙니다.)
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example annotation-driven-monitoring그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd annotation-driven-monitoring빌드
pull이 lockfile을 해석하고 빌드가 그것을 읽습니다:
aggrega pull --release release.yamlaggrega build --release release.yamlAI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 워크스페이스 폴더에 아직 `annotation-driven-monitoring` 폴더가 없으면 `example`에 `annotation-driven-monitoring`을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `annotation-driven-monitoring` 폴더에 쓰입니다. 그런 다음 `workspace_root`에 `annotation-driven-monitoring`, `release`에 `release.yaml`, `auto_pull`에 true, `write`에 true를 지정하여 `build` 도구를 호출하십시오. 빌드가 어떤 파일을 썼는지 알려 주십시오. 파일은 `annotation-driven-monitoring/dist/` 아래에 있습니다.렌더링된 출력이 증명하는 것
lockfile을 해석하고 빌드한 뒤 dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml을 확인합니다.
aggrega pull --release release.yamlaggrega build --release release.yaml이 파일 이름은 해독해 볼 만합니다. 아무도 직접 입력하지 않았기 때문입니다. 이 타깃은
디렉터리 바로 안에 있는 파일만 읽으므로, 연결의 파일은 컴포넌트 자체 파일 옆에 놓이고 두 좌표를 디렉터리 세그먼트 대신 파일 이름에 담습니다. 즉 Feature가 연결된 컴포넌트, 그다음
연결된 이름입니다. 여기서 두 번째 좌표는 누군가 작성한 이름이 아닙니다. 어노테이션이 이를 생성하며, 그것은 어노테이션 키 자체인
feature.aggrega.ai/monitoring입니다. 점과 슬래시는 그대로 파일 이름에 들어갈 수 없으므로 각각 -z와 문자 하나로 바뀝니다. 점은 -zd,
슬래시는 -zs입니다. payments 경계의 api 컴포넌트에 대해 빌드는 다음을 작성합니다.
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yaml이 인코딩 때문에 해당 키의 슬래시는 별도의 디렉터리를 만들지 않습니다. 바로 그것이 핵심입니다. 한 단계 아래에 있는 파일은 경계 디렉터리를 읽는 스크레이프 설정 소비자가 가져가지 않기 때문입니다.
이 예제는 core/prometheus-exporter와 그 ServiceMonitor FeatureRecipe(그리고 helm provider)를 표준 라이브러리에서 가져와 사용합니다. example/compute/service 데모 컴포넌트와 그 레시피는 공유 카탈로그의 example/ 게시자 아래에 해당 표준 라이브러리 엔터티와 함께 있습니다. 이 예제의 .aggrega-config.yaml은 hub.aggrega.ai를 기본 레지스트리로 선언하므로 엔터티는 허브에서 해석됩니다. 두 명령 모두 --catalog 플래그가 필요하지 않습니다.
| Component | 경계 | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s(platform 기본값) | metrics | /metrics |
api / worker / ledger | payments | 15s(재정의) | metrics | /metrics |
etl / reconcile | batch | 120s(재정의) | metrics | /metrics |
표가 구체적으로 보여 주는 세 가지 사실:
- 작성자 선언이 아닌 어노테이션 기반. Aggregate에는 모니터링
features:가 어디에도 없는데도 ServiceMonitor 여섯 개가 렌더링됩니다. 이들은 오직 어노테이션이core/prometheus-exporter를 각 컴포넌트로 확장했기 때문에 존재합니다(빌드 그래프에서 첨부의origin은explicit이 아니라annotation입니다). - 하위 키별 깊은 병합.
payments와batch는interval만 설정하지만, 해당 ServiceMonitor에는port: metrics와path: /metrics가 들어 있습니다. 이는 platform 어노테이션의 구조화된 값에서 상속되어 하위 키별로 병합된 것입니다. 하위 트리는 형제 필드를 상속하면서 필드 하나만 재정의합니다. - 팬아웃. 컴포넌트 여섯 개가 하나의 platform 어노테이션과
두 개의 한 줄짜리 재정의로 모니터링됩니다. 컴포넌트마다 반복되는
features:블록은 없습니다.
ServiceMonitor는 Service의 이름이 지정된 metrics 포트를 스크레이프하므로(합성된
Service는 metrics: 9090을 노출합니다), 바인딩의 port: metrics는
실제 엔드포인트로 해석됩니다.
컴파일 타임과 런타임
이는 Kubernetes/Helm 예제이며, 증거는
dist/에 있는 렌더링된 매니페스트입니다. ServiceMonitor의 port는 Service의 이름이 지정된 포트를 참조하므로
셀렉터와 엔드포인트는 구조상 일치합니다. 연결을 검증하는 데 클러스터가 필요하지 않습니다. 실제 Prometheus Operator는 배포 시점에 렌더링된 ServiceMonitor를 사용하며, 컴파일러의 작업(어노테이션 → 전파로 해석된 프로필을 갖는 컴포넌트별 ServiceMonitor)은 사전에 완료되어 검사할 수 있습니다.
빌드는 결정적입니다. 다시 실행해도 출력은 바이트 단위로 동일합니다.