リントは静かだったのにバケットが逆さまだった

목표

규약을 어긴 익스포터 출력을 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 · Metric and label naming · Writing exporters

promtool 이 거절한 여섯 줄

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=(린트는 조용하지만 버킷이 누적되지 않아 틀린 계열 이름)을 적으세요.

린터는 이름·HELP·접미사 규약을 봅니다. 히스토그램 버킷이 누적인지는 보지 않으니 _bucket 값을 le 순서로 직접 읽으세요.

이름과 단위를 규약에 맞추기

/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 가 아무것도 지적하지 않아야 합니다.

카운터만 _total 로 끝납니다. _count·_sum·_bucket 은 히스토그램과 서머리가 쓰는 접미사입니다. 단위는 기본 단위(초·바이트)로 바꾸고 값도 함께 환산합니다.

CSV 에서 누적 버킷 다시 세기

/root/pca-exposition/payload-sizes.csv 의 요청 크기로 히스토그램 http_request_size_bytes 를 만들어 fixed.prom 끝에 붙입니다. 경계는 100, 1000, 10000, +Inf, _sum·_count 도 씁니다. 각 버킷은 그 경계 이하(경계 포함) 요청의 누적 개수입니다. 린트는 계속 깨끗해야 합니다.

legacy 의 payload_bytes 는 구간별 개수를 적어 누적이 아니었습니다. le="+Inf" 는 언제나 _count 와 같습니다.

OpenMetrics 로 적재해 시계열 세기

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)를 적으세요.

OpenMetrics 는 # EOF 가 없거나 타임스탬프가 없으면 적재를 거절합니다. 히스토그램 하나는 버킷마다, 그리고 _sum·_count 가 각각 시계열이 됩니다.

레이블 하나와 버킷 12개의 값

/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= 에 적으세요.

시계열 수는 레이블 값 조합의 곱입니다. 히스토그램 하나는 (경계 수 + 1) 개의 버킷과 _sum, _count 를 냅니다.

직접 만든 익스포터를 긁어 보기

/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 을 확인하고 끕니다.

버킷은 경계 이하를 누적해 셉니다. 한 요청은 자기보다 큰 모든 경계와 +Inf 에 더해집니다. 채점기가 PORT 를 주므로 포트를 고정하지 마세요.

큐 이름에 따옴표가 들어왔다

exporter.py 의 카운터에 queue 레이블을 붙입니다. GET /work?d=초&queue=이름 의 이름을 쓰고 없으면 default 입니다. 레이블 값은 노출 형식 규칙대로 역슬래시·큰따옴표·줄바꿈을 이스케이프합니다. 채점기는 exports, say "hi", c:\tmp, 줄바꿈이 든 이름을 보내고 promtool 이 노출을 받아들이는지, 네 이름이 원래 값 그대로 한 번씩 되읽히는지 확인합니다.

노출 형식의 레이블 값에서 이스케이프하는 문자는 세 가지뿐입니다. 순서가 중요합니다 — 역슬래시를 먼저 바꾸지 않으면 새로 넣은 역슬래시가 다시 바뀝니다.