signoz-managing-views

保存済みビューの管理

SigNoz MCP サーバーを通じて、SigNoz の保存済み Explorer ビューを作成、読み取り、更新、削除できます。保存済みビューは、Logs、Traces、Metrics、Cost Meter ページ上の Explorer クエリを再利用できるスナップショットです。名前、フィルター、パネルタイプを含み、1 つの source にスコープされます。ダッシュボードでもアラートでもありません。

このツールでは、v2 /api/v2/saved_views API を呼び出します。作成／更新ペイロードには、旧 v1 の compositeQuery／category／tags／extraData 形式ではなく、型付きの v2 形式（source + spec）を使用します。sourcePage パラメーターは source に名称変更されました。

各操作は同じスキーマ、同じ識別モデル（ビューごとの UUID）、同じ前提リソースを共有するため、このスキルでは CRUD 操作全体を 1 か所で扱います。実際に大きな影響を及ぼす操作は削除だけであり、更新には注意すべき点（リクエスト本文全体の置換）があります。以下で、どちらにも明示的なガードを設けています。

前提条件

このスキルでは、SigNoz MCP サーバーのツール（signoz_create_view、 signoz_list_views、signoz_get_view、 signoz_update_view、signoz_delete_view、 signoz_get_field_keys、signoz_get_field_values）を呼び出します。 ワークフローを実行する前に、signoz_* ツールを利用できることを確認してください。利用できない場合は、まず signoz-mcp-setup を実行して、MCP 接続を初期化または修復してください。MCP ツールを使わずに、直接 HTTP 呼び出しを行ったり、ビューのペイロードを捏造したりしないでください。

使用するタイミング

ユーザーが次のことを希望している場合に、このスキルを使用します。

• 作成：現在の、または説明された Explorer クエリから保存済みビューを作成する。
• 一覧表示／検索：既存のビューを source または名前で検索する。
• 確認：1 つのビューのフィルターまたはパネルタイプを確認する。
• 更新：ビューの表示ラベルの名前を変更する、またはフィルター、パネルタイプ、集計を変更する。
• 削除：不要になったビューを削除する。

ユーザーが次のことを希望している場合は使用しないでください。

• ダッシュボードパネルを作成する → signoz-creating-dashboards / signoz-modifying-dashboards。
• 保存せずにアドホックな Explorer クエリを実行する → signoz-generating-queries。
• アラートルールを作成または変更する → signoz-creating-alerts。

スキーマの参照

作成または更新のペイロードを組み立てる前に、両方のリソースを読み取ってください。 spec を記憶だけで手作業で組み立てないでください。正しいスキーマは、これらのリソースで説明されている型付き v2 仕様（schemaVersion: "v2"）です。旧 v1 フィールド（compositeQuery、category、tags、extraData）は受け付けられません。

クライアントのリソース読み取り機能を使い、URI で両方の MCP リソースを読み取ってください。

• signoz://view/instructions：SavedView のフィールドリファレンス、source のルール、spec のフィールド、GET 後に置換する更新フロー、最小限の作成本文。
• signoz://view/examples：現在の意図とスキーマに合致する箇所のみ適用する、往復済みの v2 ペイロード。

操作の流れ

ビューを作成する

1. sourceを解決します：traces、logs、metrics、meterのいずれか1つに厳密に限定してください。ユーザーの意図が曖昧な場合（「このクエリを保存して」など）は、どのExplorerを指しているのか確認してください。フィルター文字列だけから推測することはできません。Cost Meter（使用状況／請求）のビューにはmeterを使ってください。クエリはmetricsシグナルに対して実行されますが（ステップ4を参照）、metricsとは別のExplorerページです。

2. スキーマリソースを読み込みます。 ペイロードを作成する前に、クライアントのリソース読み取り機能を使ってsignoz://view/instructionsとsignoz://view/examplesの両方を読み込んでください。スキーマを把握しているつもりでも、この手順を省略しないでください。

3. 必須のsignoz-generating-queriesを使ってクエリを作成します。 Skillツールを使ってsignoz-generating-queriesを呼び出してください。このサブスキルは、フィールドの検出、型チェック、ライブデータの検証を1回で行います。signoz://view/examplesのペイロード例を流用したり、単独でsignoz_search_tracesを実行したりすると、サイレントな400エラーを未然に防ぐフィールド型チェックとサービス名の解決を省略してしまいます。これを省略すると、不正なフィルターが保存済みビューになり、削除して作り直す必要があります。 meterビューの場合は、signoz-generating-queriesにCost Meterクエリ（source=meter）であることを伝え、デフォルトのストアではなくmeterストアを検索させてください。 signoz_execute_builder_queryの検証呼び出しが成功した際のqueries配列をそのまま保持し、明示的に変換してください：

   execution query.compositeQuery.queries
     -> saved spec.queries
   

   signoz_create_view の spec 引数は、次の形式で構築します。 { "displayName": "<human label>", "panelType": "<list|graph|table|value|trace>", "requestType": "<raw|time_series|scalar|trace>", "queries": <copied queries> }。 Explorer のレイアウトに応じて、selectedFields／display を追加します。 queries 配列は損失なくコピーします。ただし、実行専用の エンベロープフィールド schemaVersion、start、end、requestType（実行エンベロープのもの）、 formatOptions、variables はコピーしないでください。保存する spec に query キーや compositeQuery オブジェクトを含めないでください。 panelType と requestType は保存するビューの意図から選択し、実行エンベロープから 推測して作り出さないでください。 トップレベルの name（DNS-1123 ラベル。小文字、数字、ハイフン）を設定するか、 generateName: true を渡して spec.displayName から生成します。schemaVersion は常に "v2" です。 省略した場合はサーバーが設定します。 コピーしたクエリでは、正の値を持つすべての spec.limit と v5 の spec.order エントリを損失なく保持する必要があります。これらをダッシュボードの orderBy に 変換してはいけません。 Raw／list ビューでは 100 行（ログ：timestamp/id の降順、トレース：timestamp の降順）を使用します。 スタンドアロンの集計ビューと数式の結果では 100 グループを使用します。 数式で参照されるビルダークエリでは、評価前に limit が適用されるため 10000 を使用します。 適切に、主集計または __result の降順で並べ替えます。時系列のトップ N は選択した期間全体で グループを順位付けするため、短時間の局所的な急増を見落とすことがあります。 v2 リソースで許可される範囲で、無効化フラグや PromQL／SQL エンベロープを含め、 Raw クエリエントリをそのまま保持します。作成時に PromQL または SQL エンベロープを使う場合、 ユーザーまたは既存のビューから逐語的に取得する必要があります。 signoz-generating-queries は作成しないため、ステップ 5 で検証してください。

4. すべての builder_query の spec でシグナルルールを適用します。

   • traces／logs／metrics の場合：signal == source。signal:"logs" を指定した source:"traces" のビューはサーバー側でエラーになります。
   • meter（Cost Meter）の場合：signal:"metrics" かつ source:"meter"： Cost Meter ビューは、meter ストアに対して metrics シグナルを使ってクエリされます。 source:"meter" を省略すると、デフォルトの metrics ストアが暗黙的にクエリされます。 meter 以外のソースのビューに source:"meter" を設定すると、拒否されます。

5. 保存前のサンプル取得は必須です。 spec.queries[0].spec のフィルターをそのまま使って、 宛先のシグナルを確認します。

   • source=traces → limit=1 を指定して signoz_search_traces
   • source=logs → limit=1 を指定して signoz_search_logs
   • source=metrics → spec.aggregations[0].metricName の metricName と同じ フィルターを指定し、timeRange=1h、requestType=scalar で signoz_query_metrics。 ビューに複数のメトリクスクエリがある場合は、それぞれについて繰り返します。このツールには metricName が必要です。フィルターのみの確認には対応していません。
   • source=meter → spec.aggregations[0].metricName の metricName、source=meter、 同じフィルターを指定し、timeRange=24h（Cost Meter は時間単位で集計されるため、1h の期間では 不完全なバケットが 1 つだけになる場合があります）、requestType=scalar で signoz_query_metrics。
   • PromQL または SQL エンベロープ → そのエンベロープをそのまま使い、直近の短い期間を対象に signoz_execute_builder_query を実行します。上記のビルダー確認は適用されません。 Step 3 が問題なく完了した場合でも必須です。このサブスキルが検証するのは、サブスキル自身が作成したクエリであり、編集やリフト後に保存する内容ではありません。空の場合は、そのまま保存する／修正する／中止する、のいずれかを選びます。空のビューを保存する権限がない自律モードでは、中止してエスカレーションします。

6. 書き込む前にプレビューします。この手順は省略できません。 signoz_create_view を呼び出す前に、名前、ソース、panelType、フィルター式の全体、および Step 5 のプローブ結果（「サンプル取得：直近 1h に N 行」。meter ビューの場合、プローブの時間枠は 24h なので、そのように報告します）の概要をユーザーに提示します。人間が介在する場合は、確認を待ちます。自律型エージェントの場合は、プレビューをログに記録して処理を続行します。

7. signoz_create_view を呼び出します。成功すると、レスポンスの data に新しいビューの id が含まれます（上流での HTTP 201）。サーバーが id、createdAt/By、updatedAt/By を設定するため、これらを送信しないでください。

保存するログフィルターでは、明示的なフィールド横断の全文検索に search('timeout') を使用します。search('timeout', body) のようなスコープ指定形式は、そのスコープを明確に意図している場合にのみ使用します。フィールドの特定によって対象が判明したら、body CONTAINS 'timeout' のような標準的なフィールド条件を優先します。リテラル値では、アポストロフィより先にバックスラッシュをエスケープしてください。signoz_search_logs.searchText の簡易機能（searchScope で検索対象を選択し、既定ではログ本文が対象になります）は、作成した search() フィルターを保持する代わりにはなりません。

ビューの一覧表示または検索

signoz_list_views には source が必要です。ユーザーが source を指定しておらず、名前で検索している場合は、ソースごとに（traces、logs、metrics、meter）1 回ずつ呼び出して結果を統合します。推測してはいけません。ユーザーが部分文字列を指定した場合は、サーバー側の部分一致フィルターに name パラメーターを使用します。すべてを取得してクライアント側で grep してはいけません。category フィルターはありません。これは v2 API で削除されました。

レスポンスはページ分割されます。ビューが存在しないと結論付ける前に、必ず pagination.hasMore を確認してください。既定のページサイズは 50 です。続行するには、offset = pagination.nextOffset を渡します。特定の source についてビューが存在しないと確定できるのは、hasMore = false になるまでページをすべて確認した場合のみです。hasMore = true の間はページネーションを続けてください。ページ数の上限はありません。

単一のビューを取得

UUID（id。旧形式の別名 viewId も使用できます）を指定して signoz_get_view を使用します。返される data オブジェクトは標準の SavedView 形式であり、signoz_update_view に渡す値です。ユーザーの記憶に基づく説明ではなく、このデータを信頼できる唯一の情報源として扱ってください。

ビューの更新（GETしてから置き換え）

signoz_update_view は全置換です。一部のフィールドだけを含むボディを送信すると、指定されていないフィールドは消去されます。マシン用の name はサーバー側で変更できません。ビューの名前を変更するには、spec.displayName を変更します。手順は次のとおりです。

1. ビューの id を指定して signoz_get_view を実行します → { "status": "success", "data": { ...SavedView... } } が返されます。
2. data オブジェクトを取得します。サーバーが設定するフィールド（id、createdAt、createdBy、updatedAt、updatedBy）を取り除き、name も削除します。MCP サーバーがこれらのフィールドを削除しますが、あらかじめ省いておくと差分が読みやすくなります。
3. 更新によって spec.queries が変更される場合（新しいフィルター、異なるパネルタイプ、異なる集計）、先に signoz-generating-queries を呼び出して、新しいクエリを作成し、検証します。ユーザーの説明をもとに spec.queries を手動で編集しないでください。同じ Step 4 のシグナルルールが適用されます（meter の場合も含め、signal:"metrics" と source:"meter" を指定します）。また、panelType の変更に伴い stepInterval の変更が必要になることもよくあります。meter ビューの場合は、signoz-generating-queries に Cost Meter クエリ（source=meter）であることを伝え、メーターストアを検出して検証するようにします。実行に成功したクエリから、Create と同じ明示的な変換方法で置き換え後の spec.queries を導き出します。query.compositeQuery.queries のみをコピーし、実行専用のエンベロープフィールドは除外します。純粋なメタデータの変更（表示ラベルの変更）の場合、この手順は省略し、spec.queries に触れないでください。
4. ユーザーが変更を求めたフィールドのみを変更します。source は変更しないでください。別のソースへの移動は拒否されます。
5. spec.queries が変更された場合は、保存前に必ずサンプルを取得します。 新しいフィルターに対して、Create フローの Step 5 にある1行プローブを実行します。結果が空の場合は、そのまま保存するか、修正するか、中止します。純粋なメタデータの変更（表示ラベルの変更）の場合に限り、省略できます。
6. 書き込む前に、差分形式のプレビューを表示します。 変更したフィールドを1行ずつ示します。例：spec.displayName: "slow-checkout" → "slow-checkout-p99"。変更されていないフィールドも明記します（例：「queries：変更なし」）。spec.queries が変更された場合は、Step 5 のプローブ結果も含めます。これにより、気付かないまま誤った変更が行われるのを防ぎ、対象のビューが間違っていないかユーザーが確認できるようになります。spec.queries を変更するとビューの実際の表示内容が変わるため、変更する場合は必ず確認を待ってください。
7. { "id": "<id>", "view": <modified data> } を指定して signoz_update_view を呼び出します。view には source と spec 全体を含める必要があります。成功時、上流からは空の 204 が返されます。

ビューを削除する

削除は取り消せない操作であり、共有リストからビューが直ちに削除されます。そのビューをブックマークしていたチームメンバーには、ビューが消えたように表示されます。ホストアプリケーションによっては、削除直後にワンクリックで復元できる場合があります（SigNoz Assistant はスナップショットを取得し、restore アクションを提供します）。ただし、これは復旧のための手段であり、削除を慎重に行うことの代わりにはなりません。共有テーブルから行を削除する場合と同じように扱ってください。

1. 一覧で特定します。 signoz_list_views を呼び出し、名前でビューを検索します。source が不明な場合は、4 つのソース（traces、logs、metrics、meter）すべてを検索します。
2. 確認のために取得します（必須）。 手順 1 の UUID を使って signoz_get_view を呼び出します。正しいと思われる一覧結果から UUID を取得した場合でも、この手順を省略してはいけません。一覧の結果はページ分割されており、名前が一致しても UUID が正しいとは限りません。signoz_get_view によって、UUID がユーザーの指定したビューに対応することを確認します。 一致する名前と source を signoz_get_view で事前に確認せずに、signoz_delete_view を UUID に対して呼び出してはいけません。
3. 提示して確認を求めます。 特定したビューの名前と source を提示し、明示的に確認を求めます。元のプロンプトが強く要求している場合でも、自動的に確認済みとして扱ってはいけません。破壊的な操作では、特定した対象について改めて確認を得る必要があります。
4. signoz_delete_view を呼び出します。成功した場合は、UUID だけでなく、削除したビューの名前を伝え、ユーザーが対象を認識できるようにします。

人間が介在しない自律型エージェントの場合、呼び出し元のコンテキストで保存済みビューに対する破壊的な操作が明示的に許可されていない限り、削除を拒否してください。また、呼び出し前に特定したビューのメタデータを記録してください。

ガードレール

• 作成時および spec.queries の更新時には、保存前に必ずサンプルを取得します。 各フローの手順 5 では、保存しようとしているペイロードとまったく同じフィルターを使い、保存先のシグナルに対して 1 行のプローブを実行します。この手順の省略は、削除前の取得を省略するのと同じです。手順 3 の signoz-generating-queries への委任は必要ですが、それだけでは不十分です。そこで検証されるのは、委任先が作成したクエリであり、編集後に保存するフィルターではありません。

  シグナル間で属性を流用する際の落とし穴： フィールドキーはシグナルごとに異なります。同じテナント内で同じサービスが出力した属性でも、metrics で観測された属性（たとえばカウンターの oauth.error_code）が、traces や logs に存在するとは限りません。別のシグナルを対象とする兄弟ダッシュボードのパネル、アラートルール、またはビューから属性を流用することは、保存したビューが空になる最も一般的な原因です。signoz_get_field_keys signal=<destination signal> は必要ですが、それだけでは不十分です。まばらにしか出力されない属性では、結果が 0 件のビューが生じます。確認できるのはサンプル取得だけです。保存先のシグナルは、traces/logs/metrics の場合は source と同じです。一方、meter ビューでは source=meter とし、シグナルは signal=metrics です（signal=meter にはしないでください）。

  独自のフィルターで 0 件の行を返す保存済みビューは、共有ワークスペースに残る永続的な成果物です。人間によるプレビューでは、JSON を見てもフィルターが一致しないことは分かりません。また、自律モードにはプレビューがありません。そのため、サンプル取得だけが安全策となります。

• 保存前に実行用エンベロープを変換します。 実行可能なクエリと保存済みビューの仕様では、外側の構造が意図的に異なります。作成呼び出しまたは view.spec には、spec: {displayName, panelType, requestType, queries, ...} の形式をそのまま保存してください。queries には、検証済みの実行用 query.compositeQuery.queries を使用します。ビューに range、request、formatting、variables のエンベロープをコピーしてはいけません。

クイックリファレンス

操作	呼び出すツール	主なガード
作成	signoz://view/instructions + signoz://view/examples を読み込む → signoz-generating-queries → 完全一致するフィルターでサンプルを取得 → プレビュー → signoz_create_view	保存前のサンプル取得が必須。書き込み前にプレビューする。v1 のフィールドは使用しない
一覧表示	signoz_list_views（ソースが指定されていない場合は × 4：traces/logs/metrics/meter）	pagination.hasMore を確認する
取得	signoz_get_view(id)	更新用の正規の本文を返す
更新	signoz_get_view → 変更 → spec.queries が変更された場合はサンプルを取得 → 差分をプレビュー → signoz_update_view	全体置換。name は変更不可（名前変更には spec.displayName を使用）。差分のプレビューが必須
削除	signoz_list_views → signoz_get_view → 確認 → signoz_delete_view	削除前の取得が必須。直前の確認が必要

よくある間違い

間違い	修正方法
例や記憶を頼りに spec.queries を手作業で作成する（signoz://view/examples を読んだ後でも）	Skill ツールを使って signoz-generating-queries を呼び出します。例を読んで signoz_search_traces で検証するだけでは代わりになりません
廃止された v1 の形式を送信する：compositeQuery、category、tags、extraData、または sourcePage パラメーター	v2 API では source + spec を使用します。まず両方のスキーマリソースを読み込んでください
実行可能なクエリーエンベロープ全体を保存する spec にコピーする	query.compositeQuery.queries のみをコピーし、spec {displayName, panelType, requestType, queries} を構成します。実行時のみの schemaVersion、start、end、requestType、formatOptions、variables は除外してください
メトリクス、アラートルール、または同種のビューから属性名を取得し、対象のシグナルで再確認せずに source=traces / =logs のビューのフィルターに使用する	フィールドキーはシグナルごとに異なります。メトリクスの属性が traces や logs に存在するとは限りません。必ず signoz_get_field_keys signal=<destination signal> で再確認し（meter ビューの場合は signal=metrics source=meter を使用し、signal=meter は使用しないでください）、さらに必須の保存前サンプル取得を実行します。キーの確認は必要ですが、それだけでは不十分です
signoz-generating-queries がすでにクエリーを検証したため、保存前のサンプル取得を省略する	サブスキルが検証するのは、それが作成したクエリーです。保存するフィルターは、その後に編集されたり、別の場所から取得されたりしている可能性があります。ステップ 5 のサンプル取得は、いずれの場合も必須です
削除前に signoz_get_view を呼び出さない（一覧の UUID だけを頼りにする）	signoz_delete_view の前に、必ず signoz_get_view を呼び出して名前とソースを確認します
更新時に機械向けの name を変更しようとする	name はサーバー側で変更できません。表示ラベルを変更するには spec.displayName を変更します
ビルダークエリーで signal ≠ source	traces/logs/metrics では、すべての builder_query.signal をビューの source と一致させる必要があります。meter ビューでは signal:"metrics" + source:"meter" を使用します（signal:"meter" ではありません）
Cost Meter ビューを source:"metrics" の下に登録する（source:"meter" を使用）	Cost Meter ビューは source:"meter" の下に登録します。そうしないと Meter Explorer に表示されず、Metrics の下に誤って登録されます。サーバーは、meter 以外のソースに対する source:"meter" を拒否します
一部のフィールドを省略した更新本文を送信する（変更していないフィールドを省略する）	まず GET で本文全体を取得 → 変更するフィールドのみを編集 → source + 完全な spec で置換します
1 ページ目だけを確認して「そのビューは存在しない」と判断する	pagination.hasMore を確認し、offset = pagination.nextOffset で続行します
PromQL、SQL、無効化フラグ、選択済みフィールド、または作成者が指定した未知の内容を正規化して削除する	読み取り・変更・書き込みの間、現在の型付きリソースで許可されるすべてのフィールドを保持し、サーバーによって設定されたことが分かっているフィールドのみを削除します

操作結果の報告

書き込み（作成／更新／削除）の後は、返信に以下を含めてください。

• ビューの名前と UUID。
• source。
• 直接リンクは、MCP の応答または SigNoz のフロントエンドに正式な URL がある場合、またはユーザーが明示的に求めた場合にのみ記載してください。フロントエンドのルートを捏造しないでください。保存済みビューのパスはシグナルごとに異なり、時間とともに変わります。判断に迷った場合はリンクを省略し、UUID と source を報告してください。
• 更新の場合は、変更内容（一行の差分）。
• 削除の場合は、名前を明記して「削除しました」と確認してください。

フォローアップの提案

ビューの操作後は、直前の操作に合ったフォローアップの意図を最大 3 つ提示できます。ホストアプリケーションが表示するため、具体的な方法はホストの UI 表示ルールに従ってください。ユーザーの状況に自然なものを判断して提示し、無理に 3 つまで増やさないでください。

判断よりも優先される、次の 2 つの禁止事項があります。

• 読み取り専用の操作は、チップも読み取り専用にしてください。 list / get / find の後に、書き込みを提案するチップ（「このビューを更新」「このビューを削除」など）を提示しないでください。これは、以下の「操作結果の報告」にある読み取り専用の終了ルールに反します。ビューの基盤となるクエリを再実行するチップは問題ありません。読み取りパスにとどまるためです。ユーザーが次のメッセージで更新または削除を指定した場合は、そこから処理してください。
• ホストが挿入するアクションと重複させないでください。 削除後にホストが復元アクションを表示する場合（SigNoz Assistant が該当します）、復元をフォローアップとして提示しないでください。重複して表示されます。

ユーザーが単に内容を確認しているだけ（「自分のビューを一覧表示して」「ここには何がある？」など）で、これ以上の意図を示していない場合は、フォローアップを提示しないでください。不適切な提案をするより、何も提示しない方が適切です。

フォローアップは、ツール名やスキル名ではなく、ユーザーの意図として説明してください。ユーザーがクリックするラベルは、次に入力するプロンプトのようにしてください。

読み取り専用の操作（list、get）では、簡潔に報告（名前、ID、source、フィルター式、パネルタイプ）して終了してください。スキーマをユーザーに説明し直さないでください。