テーブルについて、そしてそれがどのマシンを表すか

sigiro_* テーブルには、OTLP を送信した任意のソースからのテレメトリが保持されます。sys_* 関数は sigiro が稼働しているマシンを読み取ります。両者を混同すると、誤ったマシンの情報を得ることになります。

sigiro は 2 種類のテーブルを提供しており、クエリ上では両者はよく似て見えます。一方はサービスが送信したテレメトリを保持します。もう一方は sigiro 自身が稼働しているマシンを読み取ります。どちらも CPU、メモリ、ディスクに関する問いに答えますが、どちらもそれがどのマシンを指しているのかを教えてはくれません。

このページはその境界線を引きます。本セクションで最も価値のある内容です。なぜなら、この失敗はエラーメッセージとして現れないからです。失敗の形は、正しく見えるにもかかわらず、あなたが尋ねていないマシンを表している数値なのです。

2 つのファミリー、2 つの対象

sigiro_* という名前はテーブルです。sys_* という名前は関数であり、空の括弧を付けて呼び出します。それが目に見える唯一の違いであり、違いとしては十分ではありません。

罠、ひとつの例で

エージェントが次のように尋ねたとします。checkout サービスのディスクは満杯ですか？

-- WRONG for that question
SELECT * FROM sys_disk_info();

このクエリは成功します。実在するマウントポイントと実在する空きバイト数を返します。その中のすべての数値は、sigiro が稼働しているマシンを表しています。checkout が別のコンテナ、別のホスト、あるいは別のリージョンで稼働しているなら、その答えは checkout とは何の関係もありません。ホステッドサービスでは、その答えは私たちが運用しているマシンを表しており、あなたはそのマシン上で何も稼働させていません。

エージェントにはそれに気づく手立てがありません。エラーもなく、null 列もなく、レスポンス中にメッセージもありません。そのためエージェントは自信を持ってディスクの数値を報告し、その数値は誤ったマシンについてのものなのです。

checkout に関する問いは、あなたのサービスが送信したメトリクスから答えます。

-- RIGHT for that question
SELECT service_name, metric_name, value, timestamp
FROM sigiro_metrics_gauge
WHERE service_name = 'checkout'
  AND metric_name LIKE 'system.filesystem%'
  AND timestamp > now() - INTERVAL '1 hour'
ORDER BY timestamp DESC;

これは checkout 自身の OpenTelemetry ホストメトリクスが報告した内容を、checkout 自身のマシンから、あなたが選んだ期間にわたって読み取ります。履歴データなので、1 つの瞬間ではなく傾向を確認できます。行セットが空であれば、それもまた本物で有用な答えです。そのサービスについてホストメトリクスを送信しているものが存在しないということであり、対処すべきは別のクエリではなく計装なのです。

そもそもなぜ sys_* が存在するのか

sys_* 関数は誤りではありません。これらは 1 つの問いにうまく答えます。このノードは今この瞬間どのような状態か？ セルフホストのフリートを運用するオペレーターは各ノードについてそれを尋ねますし、その答えにテレメトリパイプラインは不要です。ノードが自分自身のカーネルを読み取るからです。

これらはまた、sigiro の SQL ルールに対する意図的な例外でもあります。データベースの外部を読み取る他のすべての関数はブロックされます。呼び出し元がパスを指定できてしまうからです。read_csv('/etc/passwd') はまさにブロックリストが塞ぐ穴です。sys_* 関数は引数を取らないため、呼び出し元が選択できるパスが存在せず、その性質ゆえに許可されています。sigiro は引数を伴う sys_* 呼び出しをすべて拒否します。

その帰結を率直に述べます。セルフホストのノードでは境界はネットワークであり、sys_* はクエリ面に到達できる者なら誰でも読み取れます。ホステッドサービスでは、sys_* は私たちのマシンを表し、決してあなたのマシンを表しません。いずれの場合も規則は同じです。sys_* はあなたに応答しているプロセスについてのものです。

メトリクステーブルが 4 つある理由は書き込みパスにある

メトリクスは 1 つではなく 4 つのテーブルに届きます。

• sigiro_metrics_gauge — ある時点における値
• sigiro_metrics_sum — カウンター、単調増加のものもそうでないものも
• sigiro_metrics_histogram — 明示的なバケット境界
• sigiro_metrics_exp_histogram — 指数バケット

単一の sigiro_metrics テーブルという案は提案され、却下されました。OTLP はすでにこれら 4 つの形状を異なるフィールドで運んでいるため、1 つのテーブルにすると挿入のたびにスキーマ射影が必要になります。該当しない形状のための null 列と、どれを使うか判断するマッパーです。4 つのテーブルであれば、各 OTLP 形状をコピーなしで、射影なしで挿入できます。その代償として、すべてのメトリクスを一度に取得したいときには UNION ALL が必要になります。これは /v1/diagnose が内部で行っていることです。

sigiro_anomalies はこのファミリーの中で異質な存在です。テレメトリは保持しません。スケジュールされた処理がすでに検出したレジームシフトを保持し、GET /v1/anomalies は同じ行を型付き JSON として提供します。ダッシュボードではなくエビデンスについてで、それらの行がどのように生成されるかを説明しています。

スキーマエンドポイントはまだ存在せず、それがギャップです

ここまでの内容はすべて、あなたが今持っていてエージェントが持っていない知識です。

sigiro はスキーマ記述を公開していません。/v1/schema は存在せず、テーブルには列コメントもないため、POST /v1/query にたどり着いたエージェントは推測するか、このサイトの llms-full.txt を読むことになります。どちらも十分な頻度で機能してしまうため危険です。ディスクに関する問いに対する sys_disk_info() という推測は_良い_推測であり、そして誤った答えを生み出します。

まさにその理由から、私たちはこれを利便性のギャップではなく、API における最も価値のあるギャップとして扱っています。マシン可読にすべき区別は「ローカルかリモートか」ではありません。次のことです。sys_* は sigiro が稼働しているマシンのライブ測定値であり、sigiro_metrics_* は OTLP を送信した任意のソースからの履歴テレメトリである、ということです。

そのエンドポイントが存在するまでは、このページがマシン可読版です。/docs/explanation/tables.md で Markdown として提供されており、llms.txt にも含まれています。

毎回適用できる規則

その問いがどのマシンについてのものかを問いましょう。

• あなたが計装したサービスについて — sigiro_* を使い、timestamp で範囲を限定する。
• sigiro プロセス自体について — sys_* を使い、1 つの瞬間の値を期待する。
• 不確かな場合 — sigiro_* を使う。空の結果は誠実です。sys_* の結果は自信に満ちていて、しかもおそらく無関係です。

次に読む

• ダッシュボードではなくエビデンスについて
• ホステッド sigiro にテレメトリを送信する — 適用される SQL ルールとともに示された完全なテーブル一覧