린트는 조용했는데 버킷이 거꾸로였다

목표

규약을 어긴 익스포터 출력을 promtool 린터로 진단해 고치고, 히스토그램 노출을 원자료에서 다시 세며, OpenMetrics 로 TSDB 에 적재해 시계열 수를 확인한 뒤 표준 라이브러리만으로 익스포터를 만들어 실제로 긁어 봅니다.

왜 중요한가

Prometheus 는 익스포터가 내놓는 텍스트를 그대로 믿습니다. 카운터에 _total 이 없거나 단위가 밀리초로 섞이면 대시보드와 규칙이 서로 다른 뜻으로 읽고, 버킷이 누적이 아니면 분위수가 조용히 틀립니다. 레이블 하나와 버킷 몇 개가 시계열을 몇 개로 늘리는지도 적재해 보기 전에는 감이 오지 않습니다. 린터가 잡는 것과 못 잡는 것을 구별하는 것이 계측 리뷰의 출발점입니다.

준비된 환경

python3 /opt/fixtures/pca_exposition_lab.py init 이 /root/pca-exposition/ 에 legacy.prom(규약을 어긴 옛 익스포터 출력)과 payload-sizes.csv(요청 크기 40건)를 둡니다. lab-k8s 이미지의 promtool 3.0.1 로 check metrics(린트)와 tsdb create-blocks-from openmetrics(블록 생성)를 실제로 실행합니다. Prometheus 서버는 띄우지 않습니다. 6·7단계의 익스포터는 채점기가 빈 포트로 잠깐 띄웠다가 끄므로, 여러분이 띄운 프로세스는 채점과 무관합니다.

단계

1. python3 /opt/fixtures/pca_exposition_lab.py init 으로 재료를 만든 뒤 promtool check metrics < /root/pca-exposition/legacy.prom 을 실행합니다. /root/pca-exposition/01-lint.txt 에 problems=(지적한 줄 수), metrics=(지적받은 지표 이름을 쉼표로, 중복 없이), missed_by_lint=(린트는 조용하지만 버킷이 누적되지 않아 틀린 계열 이름)을 적으세요.
2. /root/pca-exposition/fixed.prom 을 만들어 legacy.prom 의 다섯 계열을 옮깁니다. http_requests 는 카운터 http_requests_total(두 표본 유지), request_latency_ms 212 는 게이지 request_latency_seconds 0.212(HELP 추가), queueDepth 는 queue_depth, cache_hits_total 은 게이지 cache_entries, job_duration_count 는 게이지 batch_jobs_running 입니다. payload_bytes 는 옮기지 않습니다. promtool check metrics 가 아무것도 지적하지 않아야 합니다.
3. /root/pca-exposition/payload-sizes.csv 의 요청 크기로 히스토그램 http_request_size_bytes 를 만들어 fixed.prom 끝에 붙입니다. 경계는 100, 1000, 10000, +Inf, _sum·_count 도 씁니다. 각 버킷은 그 경계 이하(경계 포함) 요청의 누적 개수입니다. 린트는 계속 깨끗해야 합니다.
4. fixed.prom 과 같은 표본을 OpenMetrics 형식 /root/pca-exposition/scrape.om 으로 옮깁니다. 모든 표본 끝에 타임스탬프(초, 예: 1700000000)를 붙이고 마지막 줄은 # EOF 입니다. promtool tsdb create-blocks-from openmetrics /root/pca-exposition/scrape.om /root/pca-exposition/tsdb 로 적재한 뒤 /root/pca-exposition/04-import.txt 에 series=(NUM SERIES)와 samples=(NUM SAMPLES)를 적으세요.
5. /root/pca-exposition/cardinality.om 에 http_request_size_bytes 히스토그램을 route 레이블 /checkout, /search, /upload 세 값으로, 유한 경계 12개와 +Inf 로 씁니다(경로마다 _sum·_count 포함, 타임스탬프와 # EOF). 적재하기 전에 시계열 수를 계산해 /root/pca-exposition/05-cardinality.txt 의 predicted_series= 에 적고, 적재 결과를 imported_series= 에 적으세요.
6. /root/pca-exposition/exporter.py 를 표준 라이브러리만으로 작성합니다. 환경변수 PORT(없으면 9464)의 127.0.0.1 에서 듣고, GET /work?d=초 마다 카운터 demo_jobs_processed_total 을 1 올리고 히스토그램 demo_job_duration_seconds(경계 0.1, 0.5, 1, 5)에 d 를 기록합니다. GET /metrics 는 Content-Type: text/plain; version=0.0.4 로 HELP·TYPE 을 갖춘 노출 형식을 돌려줍니다. 채점기는 빈 포트로 새로 띄워 d=0.05, 0.5, 2, 7 을 보낸 뒤 긁어 린트·카운터 증가·누적 버킷·_sum 을 확인하고 끕니다.
7. exporter.py 의 카운터에 queue 레이블을 붙입니다. GET /work?d=초&queue=이름 의 이름을 쓰고 없으면 default 입니다. 레이블 값은 노출 형식 규칙대로 역슬래시·큰따옴표·줄바꿈을 이스케이프합니다. 채점기는 exports, say "hi", c:\tmp, 줄바꿈이 든 이름을 보내고 promtool 이 노출을 받아들이는지, 네 이름이 원래 값 그대로 한 번씩 되읽히는지 확인합니다.

참고

• 텍스트 형식에서는 카운터 TYPE 줄에 _total 까지 쓴 이름을 씁니다. OpenMetrics 는 계열 이름과 표본 이름을 구별하고 # EOF 로 끝납니다.
• 흔한 실수: 버킷을 구간별 개수로 쓰는 것, 경계와 같은 값을 다음 버킷에 넣는 것, 레이블 값을 이스케이프하지 않아 줄이 깨지는 것.
• promtool 의 린트 규칙은 이 버전(3.0.1)에서 본 결과입니다. 다른 버전은 지적 문구가 다를 수 있습니다.
• [Exposition formats](https://prometheus.io/docs/instrumenting/exposition_formats/) · [Metric and label naming](https://prometheus.io/docs/practices/naming/) · [Writing exporters](https://prometheus.io/docs/instrumenting/writing_exporters/)

단계 7개

1. promtool 이 거절한 여섯 줄
2. 이름과 단위를 규약에 맞추기
3. CSV 에서 누적 버킷 다시 세기
4. OpenMetrics 로 적재해 시계열 세기
5. 레이블 하나와 버킷 12개의 값
6. 직접 만든 익스포터를 긁어 보기
7. 큐 이름에 따옴표가 들어왔다