Prometheus — 서버 하나, 스크레이프 대상 둘
이 예제는 작지만 실제로 동작하는 스택, 즉 두 개의 Grafana 대시보드 서버를 스크레이프하는
Prometheus 메트릭 서버를 Developer가 작성한 하나의
Aggregate에서 두 개의 타깃으로 컴파일합니다:
- 로컬 개발용 Docker Compose, 그리고
- 공식
prom/prometheus이미지에 대한 Workload 합성을 통한 Kubernetes.
동일한 aggregate.yaml이 두 대상을 모두 구동합니다. 대상마다 달라지는 것은
Manifest가 선택하는 Recipe 계층뿐입니다.
Grafana는 자체 메트릭을 웹 포트의 /metrics에서 Prometheus 텍스트 형식으로
제공하며, 기본적으로 그렇게 동작하므로 각 Grafana는 실제 스크레이프
대상입니다. 둘 다 같은 Component 유형을 두 번 연결한 것이므로, 두 스크레이프 작업 사이에
달라지는 모든 것은 각 연결에 작성된 내용과 각 Grafana가 메트릭을 제공한다고
밝히는 위치에서 비롯됩니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | Developer 의도: 두 개의 Grafana인 team-dashboards와 ops-dashboards(둘 다 core/observability/grafana), 그리고 각각에 대한 scrape_target 사용을 선언하는 metrics 서버(core/observability/prometheus). |
manifest-compose.yaml | Prometheus 타입을 Compose Recipe(compose/prometheus)에, Grafana 타입을 Grafana Compose Recipe(compose/grafana)에 매핑합니다. |
manifest-helm-synth.yaml | Prometheus 타입을 합성된 helm Recipe(helm/prometheus)에, Grafana 타입을 합성된 Grafana helm Recipe(helm/grafana)에 매핑합니다. 어느 쪽도 차트를 가져오지 않습니다. |
release-compose.yaml / release-helm-synth.yaml | 두 대상에 대한 Operator 레코드. |
하나의 소켓에 두 대상 연결하기
scrape_target은 두 개의 연결을 전달하는 하나의 소켓이며, 각 연결은
하나의 스크레이프 작업이 됩니다:
metrics: type: core/observability/prometheus uses: scrape_target: team-dashboards: target: team-dashboards ops-dashboards: target: ops-dashboards values: job_name: ops-grafana scrape_interval: 30steam-dashboards 연결은 values를 작성하지 않으므로, 그 작업은 소켓이
선언하는 값을 그대로 사용합니다. ops-dashboards 연결은 두 개의 키를 설정하며, 설정하는 각 키는
해당 작업에만 영향을 줍니다 — team-dashboards 작업은 이 키들의 영향을 받지 않습니다.
대상이 메트릭을 제공하는 위치를 알립니다
연결은 Prometheus가 얼마나 자주, 어떤 작업 이름으로 스크레이프하는지를 나타낼 뿐,
어디서 스크레이프하는지는 나타내지 않습니다. 그것은 대상 자신의 사실이며, 대상이 이를 게시합니다:
각 Grafana Recipe는 메트릭의 전체 주소인 metrics_endpoint를 게시합니다.
스킴, 호스트, 포트, 경로로 이루어지며, Compose에서는
http://team-dashboards:3000/metrics와 같습니다. Prometheus는 이 주소로부터 스크레이프
작업을 구성합니다. 즉 스킴, 경로, 그리고 호스트와 포트를 작업의
대상으로 사용합니다.
따라서 메트릭을 제공하지 않는 대상은 주소를 게시하지 않으며, 그런 대상을
scrape_target에 연결하면 아무것도 스크레이프하지 않을 작업을 컴파일하는 대신
해당 대상을 지목하며 빌드가 중단됩니다. 값으로 켜기 전까지 메트릭이 꺼져 있는 제품은
(카탈로그의 많은 제품이 metrics_enabled를 받습니다) 메트릭이 켜져 있는 동안
주소를 게시합니다. Kubernetes에서는 하나의 주소로 모든 메트릭에 도달할 수 없을 때,
대상이 대신 Prometheus가 메트릭을 발견하는 기준인 Service나 파드 셀렉터를 게시할 수
있습니다. Compose 구현에는 발견할 클러스터가 없으므로 이런 대상에서는 중단됩니다.
이 소켓은 서버, 상태 저장 서버, 워커를 모두 받아들이므로 데이터베이스, 로그 저장소, 오퍼레이터도 같은 방식으로 연결합니다. 스크레이프할 수 있는지는 해당 대상이 무엇을 게시하는지에 따라 결정됩니다.
보여 주는 내용
- 하나의 작성 표면, 여러 대상. 하나의 Aggregate가 스택이 무엇인지에 대한 단일 진실 공급원입니다. 각 Manifest는 이를 어떻게 구현할지를 나타냅니다.
- 하나의 소켓, 여러 연결. Prometheus는 Aggregate가
scrape_target에 연결하는 만큼의 대상을 스크레이프합니다. Recipe는 연결마다 스크레이프 작업을 하나씩 생성하므로, 작업 수는 Recipe가 아니라 토폴로지를 따릅니다. - 연결별 구성.
job_name과scrape_interval은 소켓의valueSchema에 선언되므로 서버가 아니라 연결의 속성이 됩니다. 여러 대상을 스크레이프하는 하나의 Prometheus는 Component 전체에 걸친 단일 값으로 여러 주기를 표현할 수 없습니다. - 선언된 기본값이 연결에서 생략한 키를 채웁니다.
scrape_interval은 소켓의valueSchema에 기본값을 가집니다. 이를 생략한 연결(여기서는team-dashboards)은 기본값을 받고, 이를 설정한 연결(ops-dashboards)은 설정한 것만 재정의합니다. - String Pipe를 통한 스크레이프 연결. 각 Grafana Recipe의
metrics_endpoint는 Prometheus로 파이프되어 해당 Grafana의 작업, 즉 스킴, 경로,targets항목으로 렌더링됩니다. 컴파일러는 문자열을 해석하지 않고 전달합니다. 각 Recipe가 자신의 대상이 게시할 주소를 결정하고, 컴파일러는 이를 변경 없이 파이프합니다. - Provider에 맞는 관용적 구성. 두 대상 모두에서 서버는 시작 시 연결된
Grafana들을 가리키는 스크레이프 작업을 담은 최소한의
prometheus.yml을 작성한 다음, 이를 사용해 Prometheus를 exec합니다. Compose에서는 서비스로 실행되고, Kubernetes에서는 같은 컨테이너가 StatefulSet으로 렌더링됩니다. - 영구 상태. Prometheus는 샘플을 데이터 볼륨에 저장하므로 재시작 후에도
유지됩니다. 로컬에서는 이름 있는 Compose 볼륨이, Kubernetes에서는
infra.storage로 크기가 정해지는 레플리카별 PersistentVolumeClaim이 사용됩니다. 각 Grafana는 사용자와 대시보드를 자체 볼륨에 보관합니다. - 재현 가능한 이미지. 여기의 모든 Recipe는
infra.engine_version에서 이미지 태그를 고정하므로, 렌더링된 워크로드는 고정된 이미지를 참조합니다. - 간결한 단일 목적 구조. Kubernetes에서 Prometheus 컴포넌트는 StatefulSet, ClusterIP 및 Headless Service, 데이터 볼륨 클레임으로만 렌더링되며 그 외에는 없습니다. 각 Grafana는 자체 Deployment, Service, 데이터 볼륨 클레임으로 렌더링됩니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example prometheus-scrape그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd prometheus-scrape빌드
이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다.
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (Workload synthesis on prom/prometheus)aggrega build --release release-helm-synth.yaml --auto-pull렌더링된 아티팩트는 dist/ 아래에 생성됩니다. --auto-pull은 빌드 중에 각 Release의
의존성을 해당 lockfile로 해석합니다. 처음에 aggrega pull --release release-compose.yaml을 한 번 실행해도 같은 작업이 수행되며, 이후 빌드는 이 플래그 없이 실행할 수 있습니다. 합성된 대상은 외부 차트를 가져올 필요가 없습니다. 두
Recipes 모두 공식 이미지를 Kubernetes 리소스로 직접 렌더링합니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. Workspace 폴더에 아직 `prometheus-scrape` 폴더가 없으면 `example`을 `prometheus-scrape`로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `prometheus-scrape` 폴더에 예제가 작성됩니다. 그런 다음 각 Release마다 `release-compose.yaml`, `release-helm-synth.yaml` 순서로 `build` 도구를 한 번씩 호출하되, 매번 `workspace_root`를 `prometheus-scrape`로, `release`를 해당 파일로, `auto_pull`을 true로, `write`를 true로 설정하십시오. 각 빌드가 작성한 파일을 알려 주십시오. 파일은 `prometheus-scrape/dist/` 아래에 있습니다.컴파일된 스크레이프 구성의 모습
Compose에서는 서버가 연결된 Grafana마다 job을 하나씩 담은 prometheus.yml을 작성하며,
각 job은 해당 Grafana가 게시하는 metrics_endpoint, 즉 그 compose 서비스 이름과 포트를 대상으로 합니다.
scrape_configs: - job_name: ops-grafana scrape_interval: 30s scheme: http metrics_path: "/metrics" static_configs: - targets: - "ops-dashboards:3001" - job_name: team-dashboards scrape_interval: 15s scheme: http metrics_path: "/metrics" static_configs: - targets: - "team-dashboards:3000"Kubernetes에서는 합성된 StatefulSet의 시작 명령이 같은 두 job을 작성하며,
각 job은 해당 Grafana의 Service를 대상으로 합니다. 이 Service의 이름은 helm
provider가 component와 그 default 서비스 키를 따라 붙입니다.
scrape_configs: - job_name: ops-grafana scrape_interval: 30s scheme: http metrics_path: "/metrics" static_configs: - targets: - "ops-dashboards-default:3001" - job_name: team-dashboards scrape_interval: 15s scheme: http metrics_path: "/metrics" static_configs: - targets: - "team-dashboards-default:3000"두 타깃 모두 같은 두 Aggregate 간선에서 같은 두 job을 컴파일합니다. 각
Grafana의 metrics_endpoint는 자체 scrape_target
연결을 통해 전달되며, 컴파일러는 그 문자열을 해석하지 않고 job으로 그대로
전달합니다. 타깃 간에 다른 점은 각 Grafana가 게시하는 주소(한쪽은 compose 서비스 이름,
다른 쪽은 Service 이름)와 구성이 기록되는 workload(한쪽은 Compose 서비스,
다른 쪽은 StatefulSet)입니다. 여기서는 두 Grafana가 모두
Prometheus와 같은 범위에 있습니다. Kubernetes에서 Release가 다른 네임스페이스에 배치한 Grafana는
해당 네임스페이스로 한정된 Service 이름으로 주소가 지정됩니다.
team-dashboards job과 ops-grafana job을 비교해 읽으면 각
값이 어디에서 오는지 알 수 있습니다. ops-grafana job이 ops-grafana와 30s를 갖는 것은
그 연결이 둘 다 작성하기 때문입니다. team-dashboards job이
job_name으로 team-dashboards를 갖는 것은 Aggregate가 이를 선언하지 않아
Recipe가 연결 별칭, 즉 이 Aggregate가 연결에 붙인 이름으로 대체하기 때문이며,
15s를 갖는 것은 그 연결이 생략한 키에 대해 Component의
scrape_target 소켓이 선언하는 기본값이기 때문입니다. 두 job의
스킴, metrics_path, 타깃은 각 Grafana가 게시하는 주소, 즉 Grafana가 메트릭을 제공하는 위치에서 오므로
어느 연결도 이에 대해 아무것도 지정하지 않습니다. 연결에 키를 설정하면 해당 job에 대해서만
값을 재정의하고 다른 job에는 영향을 주지 않습니다.
이 모든 것은 소비하는 쪽에서 일어납니다. 연결별 구성은 연결을 작성한 노드의 렌더 컨텍스트에만 나타나고 타깃의 렌더 컨텍스트에는 결코 나타나지 않으므로, Grafana로 연결을 잇거나 조정해도 해당 Grafana 자체가 렌더링하는 결과는 전혀 바뀌지 않습니다. 그 Deployment와 Service는 어느 경우든 같은 바이트입니다.
Grafana는 어떤 호출자에게나 메트릭을 응답하므로 어느 연결도
자격 증명을 갖지 않습니다. 메트릭에 자격 증명이 필요한 타깃의 경우 연결이 이를
credential 슬롯에 담고, Prometheus는 이를 파일에서 읽은 bearer 토큰으로 제시합니다.
metrics_credential_required를 true로 게시하는 타깃은 연결에 자격 증명이 없으면
빌드를 중단합니다.
실행하기(Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dRelease는 각 Grafana에 고유한 포트를 부여합니다. team-dashboards에는 3000을, ops-dashboards에는 3001을 부여하므로 두 Grafana가 로컬에서 나란히 실행됩니다. 각 Grafana는 Release가 부여한 포트에서 수신 대기하며, 각 포트는 해당 Grafana가 자신의 스크레이프 작업 대상으로 게시하는 주소에 담겨 전달됩니다.
http://127.0.0.1:9090을 엽니다. 이것은 Prometheus 표현식 브라우저이며, Compose Recipe가 호스트의 루프백 주소에만 게시합니다. Status → Targets 아래에는 두 작업이 컴파일된 구성이 부여한 이름인 ops-grafana와 team-dashboards로 나열되며, 각 작업은 해당 Grafana의 /metrics를 가리킵니다. 모든 Grafana가 1로 설정하고 자신의 버전을 레이블로 붙이는 게이지인 grafana_build_info를 쿼리하면 작업당 하나의 시리즈가 반환됩니다. 종료하려면 docker compose -f dist/app/compose/docker-compose.yaml down을 실행합니다.