observability を育てた team は、いずれ具体的な帳尻合わせに当たる。metrics は Prometheus、logs は Loki、traces は Tempo。Grafana dashboard と query はすでに手に馴染んでいても、storage、retention、backup、運用は三組になる。三種類の OpenTelemetry signal を ClickHouse に集めるのは有力な収束策だが、本当に置き換えにくいのは write side より、Grafana、alerting、CLI に定着した read API であることが多い。

今日見るのは tsouza/cerberus。read-only の HTTP gateway で、PromQL、LogQL、TraceQL を parse、optimize して ClickHouse SQL に変換する。返すのは Prometheus、Loki、Tempo それぞれの wire format のままだ。Grafana では三つの普通の datasource として設定でき、既存 dashboard と query を最初から書き換える必要がない。telemetry を受けたり保存したりはせず、write side は OpenTelemetry Collector から ClickHouse へ直接向かう。

GitHub repository API、README、LICENSE、main branch の commit API、Releases API を 2026-09-16 18:05 Asia/Shanghai 時点で確認すると、tsouza/cerberus は 68 stars、3 forks。主要 language は Go、license は Apache-2.0。repository は 2026-05-05 21:29:01 UTC に作成され、latest push は 2026-09-16 09:59:04 UTC。最新 main commit は 26450b5、commit time は 2026-09-16 09:59:02 UTC で、developer と agent 向けの compact semantic guide を主に追加している。最新 GitHub Release は v1.20.0、published at は 2026-09-07 16:39:22 UTC だ。

プロジェクト概要

項目内容
リポジトリtsouza/cerberus
位置づけPrometheus / Loki / Tempo HTTP API から ClickHouse への read-only query gateway
Stars / Forks68 / 3
主要 languageGo
ライセンスApache-2.0
作成日2026-05-05 21:29:01 UTC
Latest push2026-09-16 09:59:04 UTC
最新 commit26450b5、compact semantic guide を追加
最新 Releasev1.20.0、2026-09-07 16:39:22 UTC
最低 ClickHouse version24.8
データの前提standard OpenTelemetry ClickHouse schema

Grafana を替えるのでなく、query の習慣を残す

Cerberus の境界ははっきりしている。新しい telemetry backend でも exporter や rule engine でもなく、read だけを担う。OTel Collector は metrics、logs、traces を ClickHouse の standard table layout に書き続け、Cerberus は反対側で /api/v1/query_range、/loki/api/v1/query_range、/api/search などの互換 endpoint を出す。移行の一歩目を datasource URL の差し替えにでき、dashboard owner 全員に新しい query language を覚えてもらう必要がない。

PromQL recording rule、Loki log panel、Tempo trace drill-down を多く持つ team には特に現実的だ。ただし「移せば必ず正しい」とは言っていない。project には migrate command があり、rule と export した dashboard query を集め、SQL を preview し、元 backend と Cerberus の両方に replay して結果を diff できる。この順序はよい。まず実際の query で compatibility を証明し、その後で cutover を考える。

三つの language を一つの optimizer に通す

README の execution path は parse → shared plan → optimize → ClickHouse SQL → upstream wire format。PromQL は upstream の prometheus/promql/parser を使い、LogQL と TraceQL は public grammar を元に実装し、実際の Grafana parser との differential test で検証する Apache-licensed implementation だ。具体的な compatibility score がどうであれ、この構成は三種類の signal ごとに三つの query engine を作らなくて済む。

使う側にとって面白いのは、SQL を書けることそのものではない。Grafana の browse、alert、explore という同じ workflow から data に入れる。ClickHouse 側には parse と optimize を通った SQL が届くので、dashboard の利用者全員が個別に query を書く必要もない。project は rate() の range query で default では Prometheus と同じ結果を目指す。大規模 data 向けの native ClickHouse fast path は experimental と明記され、precision と resource use の trade-off を隠していない。

まず同梱の local stack で確かめる

最短の試用は自分の ClickHouse を先に接続しなくてもよい。README の compose は single-node ClickHouse、provision 済み datasource を持つ Grafana、Cerberus、deterministic な OTel fixture を起動する。

git clone https://github.com/tsouza/cerberus.git
cd cerberus
docker compose up --wait

# Grafana: http://localhost:3000
# Cerberus: http://localhost:8080

production dashboard をいきなり最初の test にするより安全だ。metrics、logs、traces の一般的な query が期待通りに動くのを見てから、control できる実 dashboard export を cerberus migrate に渡す。diff の結果、latency、resource use を確認した後で、Grafana datasource を本番環境に向ける価値がある。

install command より前提と境界を確認する

Cerberus が想定する土台は ClickHouse 24.8+ で、data は OpenTelemetry Collector ClickHouse exporter の standard schema に沿う。trace、log、異なる type の metric は別 table に置かれる。既存 table layout が違っても必ず使えないわけではないが、CERBERUS_SCHEMA_* で明示的に mapping する必要がある。「ClickHouse にある」だけで互換だと考えない方がよい。

また、全ての component を置換するわけではない。README は ingest も storage も rule engine も持たないと明記する。recording と alerting rule は既存 evaluator などが担い続ける。Grafana の query side には compatibility の取り組みがある一方、young project は速く動いている。複雑な LogQL、TraceQL、version 差、非常に高い cardinality、広い範囲の rate() query は、自分の data と元 backend で differential test すべきだ。README の stable wire API は、どの deployment でも production 適性を証明するものではない。

まとめ

tsouza/cerberus のよさは、「storage を一つに寄せること」と「観測の習慣を残すこと」の間の切れ目を埋める点にある。PromQL、LogQL、TraceQL を一斉に ClickHouse SQL へ書き換えさせるのではなく、移行の risk を test 可能な gateway と datasource 切り替えに集めている。OpenTelemetry data をより多く ClickHouse に置きつつ、Grafana にある長年の積み重ねを一度に壊したくないなら、まず隔離環境で実 query の differential test を一回走らせる価値がある小さな project だ。

プロジェクト: https://github.com/tsouza/cerberus