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をそのまま 使用できます。

バンドル PlantPulse Dashboardとは異なるパスです

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`	即時クエリ
`GET`・`POST` `/prometheus/api/v1/query_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`

1. 値をプッシュする — remote_write​

2. Grafanaで表示する​

3. どのようにマッピングされるか​

4. エンドポイント​

5. 対応しているPromQL​

6. 非対応のもの — 静かに誤らず、400で拒否します​

7. 微妙に異なる点​

関連項目​