Prometheus 연동
TSE 앞단에는 Prometheus 호환 어댑터가 얹혀 있습니다. 별도 Prometheus 서버 없이 수집(remote_write)과 시각화(PromQL) 를 Prometheus 생태계 그대로 쓸 수 있습니다.
[Prometheus · Grafana Agent] --remote_write--> TSE --> Cassandra
[Grafana (Prometheus 데이터소스)] --PromQL--> TSE
어댑터는 TSE 의 Jetty 안에서 같은 프로세스로 돕니다. 띄울 것도, 포트를 더 열 것도
없습니다 — 경로만 /prometheus 로 갈립니다(TSE 네이티브 API 는 /api/v1/*).
인증도 TSE 의 Basic Auth 를 그대로 씁니다.
1. 값을 밀어 넣기 — remote_write
prometheus.yml 또는 Grafana Agent 설정에 이렇게 적습니다.
remote_write:
- url: http://<TSE 호스트>:7800/prometheus/api/v1/write
basic_auth:
username: tse
password: "<PP_TSE_PASSWORD>"
본문은 snappy 압축 + protobuf(remote_write 1.0)이고 Prometheus·Agent 가 알아서
처리합니다. 성공하면 204, 본문이 잘못됐으면 400(재시도 안 함), 일시 장애면
500(재시도)입니다. NaN 과 ±Inf 는 저장 단계에서 버려집니다.
2. Grafana 에서 보기
데이터 소스 타입을 Prometheus 로 고르고 이렇게 채웁니다.
| 항목 | 값 |
|---|---|
| URL | http://<TSE 호스트>:7800/prometheus |
| Access | Server (proxy) |
| Auth | Basic auth — tse / <PP_TSE_PASSWORD> |
| HTTP Method | POST 권장 |
「Save & Test」를 누르면 Grafana 가 /prometheus/api/v1/status/buildinfo 로 Prometheus
임을 알아봅니다. 그다음부터는 패널에서 PromQL 을 그대로 씁니다.
TSE 에는 전용 데이터 소스 플러그인을 쓰는 번들 PlantPulse Dashboard도 있습니다. 둘 중 하나를 고르면 됩니다 — PromQL 이 익숙하면 이 쪽, 이미 만들어 둔 사전 대시보드를 쓰려면 번들 쪽입니다.
3. 어떻게 매핑되나
| Prometheus | TSE |
|---|---|
__name__ 라벨 | 메트릭 이름 |
| 그 외 라벨 | 태그 |
샘플 (ts_ms, float64) | DataPoint(double, ms) |
Prometheus 의 이름 규칙([a-zA-Z_:][a-zA-Z0-9_:]*)이 TSE 규칙과 호환되어 손실 없이
옮겨집니다.
4. 엔드포인트
모두 /prometheus 아래이고 Prometheus HTTP API 규약({"status":"success","data":…})을 따릅니다.
| 메서드·경로 | 용도 |
|---|---|
POST /prometheus/api/v1/write | remote_write 수신 |
GET·POST /prometheus/api/v1/query | instant 질의 |
GET·POST /prometheus/api/v1/query_range | range 질의 (start·end·step) |
GET /prometheus/api/v1/labels | 라벨 이름 목록 |
GET /prometheus/api/v1/label/{name}/values | 라벨 값 목록 |
GET·POST /prometheus/api/v1/series | 시리즈 매칭(match[]) |
GET /prometheus/api/v1/status/buildinfo | Grafana 인식용 |
시간은 Unix 초(소수 가능) 또는 RFC3339, step 은 15s·1m·1h·500ms 또는 단위 없는 초.
응답의 타임스탬프는 초, 값은 문자열입니다(Prometheus 규약).
5. 되는 PromQL
| 갈래 | 되는 것 |
|---|---|
| 셀렉터 | bare · 매처(= != =~ !~) · __name__ 매처 · range 셀렉터([5m], 단위 ms s m h d w y) |
| 산술 | 숫자 리터럴 · 단항 - · 괄호 · + - * / (scalar∘scalar, vector∘scalar, vector∘vector 1-to-1) |
| 비교 | == != > < >= <= (+ bool) |
| 함수 | rate irate increase delta · abs clamp_min clamp_max · histogram_quantile |
| 집계 | sum avg min max count + by/without · topk bottomk |
rate(errors[5m]) / rate(total[5m])
topk(5, sum(rate(req_total[5m])) by (path))
histogram_quantile(0.95, rate(latency_seconds_bucket[5m]))
6. 안 되는 것 — 조용히 틀리지 않고 400 으로 거부합니다
| 갈래 | 미지원 |
|---|---|
| 벡터 매칭 | on(…) · ignoring(…) · group_left · group_right |
| 집합 연산 | and · or · unless |
| 시간 함수 | *_over_time · predict_linear · holt_winters |
| 변형 | subquery(expr[5m:1m]) · @ 수식어 · offset |
| 기타 | scalar() vector() label_replace() label_join() sort() sort_desc() absent() |
| 프로토콜 | remote_read · remote_write 2.0 · exemplars · native histogram |
미지원 구문은 400 {"status":"error","errorType":"bad_data",…} 로 끊깁니다.
조용히 그럴듯한 숫자를 주지 않는다는 뜻이라, 대시보드가 말없이 거짓말하는 일은
없습니다.
7. 미세하게 다른 지점
완전한 Prometheus 가 아니라 호환 어댑터입니다. 실용상 대개 문제되지 않지만 값을 정밀하게 비교할 때는 알고 있어야 합니다.
| 무엇 | 어떻게 다른가 |
|---|---|
rate·increase 외삽 | 관측 구간을 range 전체로 선형 외삽합니다(Prometheus 의 경계 외삽 캡은 미구현) — 구간 경계에서 미세 차이 |
| range 윈도우 | [t-range, t] 양끝 포함(Prometheus 는 좌개구간). instant 셀렉터의 lookback 은 (t-5m, t] 로 동일하고 기본 5분 |
/label/<name>/values | __name__ 은 정확하지만 그 밖의 라벨은 전역 태그값으로 과대근사합니다 — 자동완성용으로는 충분 |
| scalar 비교 | 항상 0·1 로 평가합니다(Prometheus 는 bool 을 요구). 3 > 2 가 곧장 1 |
함께 보기
- TQL 과 JDBC 드라이버 — TSE 네이티브 길
- PlantPulse Dashboard 로 대시보드 만들기 — 번들 PlantPulse Dashboard
- 시계열 엔진 개요 — 데이터베이스와의 차이