kubesense-rum

KubeSense RUM

KubeSense MCP サーバーが必要です。接続、認証、共通の WHERE 句のリファレンスについては、kubesense-mcp を参照してください。RUM クエリは RUM モジュールに対して RBAC を解決します（rbac(rum)）。この権限がないキーでは、rbac(rum): this API key does not have access to this resource が返されます。再試行するのではなく、RUM 権限を付与するよう依頼してください。search-rum にも同じ権限が必要です。読み取りに使用する RUM のリストルート（POST /rum/explorer/{sessions,views,actions,errors,resources,longtasks}）にも同じ権限が必要で、これらのルートが RUM ページも保護します。

シグナル

RUM には、イベントタイプごとに 1 つずつ、6 つのシグナルがあります。それぞれが専用のテーブルを読み取ります。

シグナル	1 行が表すもの	典型的な質問
rum_session	ユーザーセッション	セッション数はいくつか、エラーが発生したセッションはいくつか
rum_view	終了したページまたは画面の表示	LCP、読み込み時間、ページあたりの表示回数
rum_action	クリック、タップ、スクロール	遅い、または操作しづらいアクションはどれか
rum_error	記録されたエラーまたはクラッシュ	どのようなエラーか、クラッシュは何件か
rum_resource	HTTP リクエストまたはアセットリクエスト	ホスト別の遅いリクエストや失敗したリクエスト
rum_long_task	メインスレッドの長時間タスク	UI をブロックしているものは何か

rum_view が数えるのは、終了した非システムセッションのビューのみです。各行は独自の start_timestamp によって時間に配置されるため、長時間のセッションは開始した時間枠で数えられます。

ツール

ツール	使用する場面	備考
get-fields（signal: "rum_view"、…）	常に最初に使用	イベントタイプごとのフィールドカタログ
analyze-telemetry	件数、率、パーセンタイル、傾向	シグナルごとにサブクエリを 1 つ使用し、selectedMode で設定します
search-rum	個別のセッション、エラー、リクエストを読み取る場合	1 つのシグナルの生データ行。search-rum を参照してください

analyze-rum はありません。analyze-logs と analyze-traces は RUM シグナルを受け付けません。RUM とログまたはトレースを比較したり、率を計算したりするには、1 回の analyze-telemetry 呼び出しに複数のサブクエリを含め、数式を追加してください。マルチクエリを参照してください。

まず調べる

クエリするシグナルを指定して get-fields を呼び出してください。フィールドセットはイベントタイプによって異なります。lcp は rum_view にのみ存在し、error_type は rum_error にのみ存在します。また、view_name では rum_view でのみ LIKE を使用できます。各イベントタイプの完全なカタログは references/field-catalog.md にあります。呼び出し前にフィールド名を確認するにはこのカタログを使用し、実際に接続しているデプロイメントでの正確な情報は get-fields を参照してください。

RUM の get-fields は、通常の TSV 形式で静的カタログのみを返します。

• ヘッダー行は # signal=rum_view total_count=<N> truncated=<bool> note=RUM has no attribute-key scan; ... です。attribute_scan_error はありません。注記には、カスタム属性は @key として指定すること（属性には LIKE を使用できません）、フィーチャーフラグは feature_flag.<key> とすることが記載されています。
• 演算子はセットで返されます（# ops.o1=EQ|NEQ|IN|NIN|LT|GT|LTE|GTE）。LIKE を使用できるフィールドのセットには LIKE／ILIKE が含まれます。user_email などの完全一致フィールドには含まれません。フィールドについての想定よりも、このセットを優先してください。
• いずれかのフィールドに注記がある場合、末尾に notes 列が表示されます。たとえば、lcp_ms には filter-only: use it in WHERE only (milliseconds); aggregate the base field lcp instead; platform: browser、lcp_target_selector には filter-only: not groupable; platform: browser が表示されます。
• enum_values には、severity の crash と error が含まれます。
• search を渡すとリストを絞り込めます（search=lcp は lcp、lcp_ms、lcp_s、lcp_target_selector を返します）。

属性キーの検出機能はありません。ユーザーがカスタム属性を必要としている場合は、キーを尋ねるか、インストルメンテーションから推測し、@ プレフィックスを付けて指定してください。誤ったキーは何も一致せず、エラーではなく空の結果を返します。

search-rum

search-rum は、1 つのシグナルの生の行を読み取ります。これは Data Explorer の List パネルに表示されるものと同じ行です。個々のイベント（クラッシュしたセッション、最も遅いリクエスト、エラーのテキストなど）を確認する場合に使います。数値を扱う場合は、件数、割合、パーセンタイル、傾向など、analyze-telemetry を使ってください。行を読み取って件数を計算すると時間がかかり、ページ上限で打ち切られます。

最初に同じ signal を指定して get-fields を呼び出してください。where と required_fields には、カタログのラベル、属性の場合は @key、フラグの場合は feature_flag.<key>（ビューとエラーのみ）を指定します。from_time、to_time、signal は必須です。clusters 引数はありません。指定すると拒否されます。application_id = "<id>" または env = production でアプリを絞り込んでください。

過去 1 時間で失敗したリクエストのうち、最も遅いものを 1 ページあたり 20 件表示

{
  "signal": "rum_resource",
  "from_time": "2026-10-20T10:00:00Z",
  "to_time": "2026-10-20T11:00:00Z",
  "where": "status_code >= 500",
  "sort_by": "duration_ms",
  "sort_order": "desc",
  "page_size": 20
}

共通の検索引数に加えて指定できる引数は、sort_by（カタログのラベル。デフォルトは start_timestamp）、sort_order（asc または desc。デフォルトは desc）、cursor です。 required_fields で列を選択します。空の場合は、種類ごとのデフォルトが使われます。

シグナル	デフォルトの列
rum_session	start_timestamp、session_type、time_spent_ms、view_count、error_count、action_count、frustration_count、first_view_name、last_view_name
rum_view	start_timestamp、view_name、frustration_count、loading_type、loading_time_ms、view_time_spent_ms、country、browser_name
rum_action	start_timestamp、action_type、action_name、frustration_type、view_name
rum_error	start_timestamp、view_name、error_source、error_message
rum_resource	start_timestamp、view_name、resource_url、duration_ms、response_size、status_code、resource_type
rum_long_task	start_timestamp、duration_ms、view_name

デフォルトでは、_ms 版が使われます。名前を指定して生の時間値（duration）をリクエストすると、ナノ秒で返されます。代わりに duration_ms または duration_s を指定してください。

出力は TSV です。最初の行は # total_count=unknown returned_rows=<N> truncated=<bool> next_cursor=<c> window_clamped=<bool> ... で、何か通知すべきことがある場合は、その後に # notice=<n> の行が続き、ヘッダー、各行のデータが続きます。各行には application_id、session_id、row_id（イベント自体の ID）、timestamp、has_replay（セッションに保存済みのリプレイがある場合に設定）、severity（エラーの場合は error または crash）も含まれます。どの required_fields を指定しても、行を識別する列はすべての行に常に含まれます。セッションでは application_id、session_id、session_start、session_has_replay、ビューではこれらに view_id、view_start が追加されます。アクションでは action_id、action_start、エラーでは error_id、error_start、is_crash、リソースでは resource_id、resource_start、長時間タスクでは task_id、task_start が追加されます（セッション以外には、それぞれ view_id も含まれます）。

ページ分割。 合計数はありません（total_count=unknown）。next_cursor が空でない間は、同じ from_time、to_time、where、sort_by、sort_order、 page_size、required_fields を指定して再度呼び出し、cursor=<next_cursor> を渡してください。カーソルはクエリに紐づくページトークンのため、異なるクエリで再利用したカーソルは拒否されます。

• ページ分割はすべての sort_by でページ単位で行われ、深さの制限はありません。キーセット方式はありません。
• page_size のデフォルトは 10 で、上限は 200 です。Data Explorer の List パネルでは、1 ページあたり 50 行が読み込まれます。

行とは何か

• 行は RUM ページのテーブルと一致します。セッションとビューは重複排除されます。ライブ（まだ開いている）ビューも一覧表示されます。
• アクション、エラー、リソース、長時間タスクは ID ごとにグループ化されます。ID ごとに 1 行となり、開始時刻は最初に発生した時刻、リソースの所要時間は中央値、長時間タスクの所要時間は平均値です。
• rum_error にはエラー（type = 3）のみが表示されます。
• Blob フィールドは一覧表示も並べ替えもできません：error_stack、handling_stack、threads、graphql、display、tags。
• 配列フィールド（service、state、city、network_connectivity、ip、action_id）は並べ替えできません。
• TSV 出力の各セルは 2048 バイトで切り詰められます。リスト API 自体は文字列を切り詰めません。

ウィンドウ。 ウィンドウは RUM データウィンドウに合わせて制限され、境界にスナップされます。from_time が生データの保持期間（セッションとビューは 30 日、それ以外は 7 日）より古い場合、保持期間の境界まで繰り上げられ、ウィンドウは RUM データのバケット境界まで広げられます。ウィンドウが変更された場合、ヘッダーに window_clamped=true と表示されます。保持期間より完全に古いウィンドウは、指定されたままになります。

読み取り予算エラーはありません。 リストの読み取りに読み取り予算の上限はありません。読み取りに時間がかかるとタイムアウトする場合があります。その場合は、ウィンドウを短くするか、application_id、env、session_id でフィルタリングしてください。

WHERE 構文

RUM カタログのフィールド名を使い、kubesense-mcp の共通構文が適用されます。

env = production AND browser_name = Chrome
severity = crash AND country IN (US, DE)
view_name ILIKE "%checkout%"                    (rum_view only)
lcp_ms > 2500 AND browser_name = Chrome         (rum_view)
status_code >= 500 AND resource_host = api.example.com   (rum_resource)
error_count > 0                                 (rum_session)
feature_flag.new_checkout = true                (any event type)
@checkout.step = payment                        (attribute)

/、:、%、または空白を含む値は引用符で囲みます。x NOT IN (...) ではなく、NOT (x IN (...)) と記述してください。

ルール

1. カタログの LIKE 列が yes のフィールドにのみ LIKE と ILIKE を使用できます。 該当するのはカーディナリティの低い列（env、country、error_type、action_name、 rum_view の view_name）です。それ以外（user_id、view_url、resource_url、 error_message、その他のイベントタイプの view_name）には = と IN を使用します。これらに対する LIKE は LIKE is not supported on <field>; use = or IN で拒否されます。
2. @attribute フィールドに LIKE は使用できません。属性には =、!=、IN、<、>、<= および >= を使用できます。比較には数値が必要です。@plan LIKE ... は operator "LIKE" not allowed for rum_view attribute field "plan" で拒否されます。
3. 配列フィールドはフィルター専用です。rum_session の service、state、city、network_connectivity および ip、rum_view の ip、さらに rum_error、rum_resource、rum_long_task の action_id はリストを保持します。= と IN でメンバーシップを判定します。グループ化や集計には使用できません。
4. 時間はナノ秒単位です。生の列（lcp、duration、loading_time、time_spent など）はナノ秒単位で 保存および返され、グループ化には使用できません。それぞれに _ms と _s の派生フィールド（lcp_ms、duration_s）があり、 フィルター専用です。where で使用します（lcp_ms > 2500 は 2.5 秒でフィルタリングします）。集計フィールド、 グループ化、またはリスト列としては使用しないでください。時間を集計するには、ベースフィールド（lcp の p75）を使用します。 結果はナノ秒単位です。
5. 自由検索 ID とテキスト（session_id、view_id、trace_id など）のグループ化は no です。代わりにカーディナリティの低いフィールドでグループ化します。 グループ化できるものは 5 つあり、上位 N グループ（ページサイズ）が返されます。error_message（先頭 200 文字でグループ化）、fingerprint、issue_id、および view_url／resource_url（クエリ文字列やフラグメントを除いたパスで グループ化）です。フィルターでは引き続き値全体が参照されるため、URL のグループラベルはパスになります。また、view_url = "<path>" はクエリ文字列のない URL のみと一致します。
6. feature_flag.<key> はすべてのイベントタイプでフィルタリングできます。フラグ値が行に保存される rum_view と rum_error でのみグループ化または集計できます。他の 4 つのイベントタイプではセッションごとに保存されるため、そこでのグループ化は拒否されます。キーは大文字と小文字を区別し、値はテキストです（true、dark、5）。フラグキー（feature_flag.new-checkout）によるグループ化は rum_view で確認済みです。where 形式はエンジンのソースに基づいており、稼働中のサーバーでは実行されていません。
7. where では属性に @ が必要です（@checkout.step）。group_by_fields／fields では @ を付けずに is_attribute: true を指定します。キーの検出機能はありません。
8. rum_error の severity は小文字の crash または error です。これは is_crash のラベルです。文字列としての is_crash ではなく、severity 型を指定してください。
9. ブール値フィールド（session_is_active、slow_rendered）には true または false を指定します。
10. プラットフォーム固有のフィールドは強制されません。 lcp はブラウザー専用で、battery_level はモバイル専用です。異なるアプリケーションタイプに対してこれらのいずれかでフィルタリングすると、何も一致せず、エラーも発生しません。
11. value_operation には row_count、unique_count、avg、sum、min、max、p50、p75、p90、p95 または p99 を指定します。row_count にはフィールドは不要です。それ以外は fields エントリーをちょうど 1 つ指定します。数値演算には数値フィールドまたは属性が必要です。unique_count にはリスト以外の任意のフィールドを指定できます。
12. RUM では alert_mode、group_by_present_only、lookback_seconds は拒否されます。

analyze-telemetry

selectedMode にシグナルを設定します。省略すると、サブクエリはメトリクスクエリになります。

ページごとの p90 LCP、Chrome のみ、ミリ秒単位

{
  "from_time": "2026-10-20T10:00:00Z",
  "to_time": "2026-10-20T11:00:00Z",
  "query_type": "instant",
  "queries": {
    "A": {
      "selectedMode": "rum_view",
      "where": "browser_name = Chrome",
      "group_by_fields": [ { "field": "view_name", "is_attribute": false } ],
      "value_operation": "p90",
      "fields": [ { "field": "lcp", "is_attribute": false } ],
      "sort_direction": "DESC",
      "limit": 10
    }
  }
}

エラー種別ごとの1時間あたりのクラッシュ数

{
  "from_time": "2026-10-20T00:00:00Z",
  "to_time": "2026-10-21T00:00:00Z",
  "query_type": "range",
  "queries": {
    "A": {
      "selectedMode": "rum_error",
      "where": "severity = crash AND env = production",
      "group_by_fields": [ { "field": "error_type", "is_attribute": false } ],
      "value_operation": "row_count"
    }
  }
}

エラーが発生したセッションの割合 — グループ化しないクエリを2つと数式を使用します：

{
  "from_time": "2026-10-20T10:00:00Z",
  "to_time": "2026-10-20T11:00:00Z",
  "query_type": "instant",
  "queries": {
    "A": { "selectedMode": "rum_session", "value_operation": "row_count" },
    "B": { "selectedMode": "rum_session", "where": "error_count > 0", "value_operation": "row_count" },
    "C": { "query_type": "formula", "expression": "(B/A)*100" }
  }
}

p95 リクエスト時間が最も遅いホスト、失敗したリクエストのみ selectedMode: rum_resource、where: "status_code >= 500"、 group_by_fields: [{"field":"resource_host"}]、value_operation: p95、 fields: [{"field":"duration"}]（ナノ秒）

フィーチャーフラグの値ごとのエラー数 selectedMode: rum_error、group_by_fields: [{"field":"feature_flag.new_checkout"}]、 value_operation: row_count

カスタム属性ごとのセッション数 selectedMode: rum_session、group_by_fields: [{"field":"checkout.step","is_attribute":true}]、 where: "@checkout.step IN (cart, payment)"

ダッシュボードパネル

保存済みのパネルクエリと analyze の呼び出しでは、イベントタイプの指定方法が異なります：

	フィールド	値
analyze-telemetry のサブクエリ	selectedMode	rum_view
ダッシュボードのパネルクエリ	selectedMode + rumEventType	"rum" + "view"

selectedMode: "rum_view" を指定したパネルは検証に失敗し、rumEventType のない "rum" は保存時に拒否されます。_ms の測定値とその単位を含むパネルの形式は、kubesense-dashboards に記載されています。まず analyze-telemetry でクエリをテストしてから、パネルクエリに変換してください。

一般的な RUM に関する質問（ユニークユーザー数、クラッシュフリーのユーザー数、Web Vitals の良好／不良の割合、Apdex、エラーと URL の上位項目、ANR 率）向けのパネルレシピは、references/dashboard-recipes.md に記載されています。

制限事項

• データの保持期間。 デフォルトでは、生の RUM 行データは rum_action、rum_error、 rum_resource、rum_long_task については7日間、rum_session と rum_view については30日間保持されます。より長い期間を指定した場合、返されるのは保存済みのデータのみです（search-rum は window_clamped=true として報告します）。デプロイ環境で保持期間を変更できます。
• 1回の呼び出しで読み取れる行数には上限があります。 search-rum は1回の呼び出しで最大200行を返し、合計数は返しません。ページングの深さに上限はありません。数値を求める質問では、代わりに集計してください。
• アラート、SQL、SPL には対応していません。 RUM はアラートルール、execute-sql、execute-spl のデータソースではありません。ログで近似せず、その旨を伝えてください。
• 属性キーの検出には対応していません。 「先に検出する」を参照してください。

エラーメッセージ

稼働中のサーバーで確認されたもの：

メッセージ	原因
unknown field "services" for signal=rum_session ...	ストレージ名です。カタログ名（service）を入力してください
analysis failed: cannot group by lcp_ms	ルール4：_ms / _s の組み合わせはフィルターにのみ使用できます。ベースフィールドを集計してください
analysis failed: LIKE is not supported on user_email; use = or IN	ルール1
operator "LIKE" not allowed for rum_view attribute field "plan" — use one of: EQ, NEQ, ...	ルール2
rbac(rum): this API key does not have access to this resource	このキーには RUM モジュールへのアクセス権がありません

kubeapi のソースに基づく文言であり、稼働中には未確認のもの：

メッセージ	原因
<field> is not a filterable field for <type>	このフィールドは別のイベントタイプに属しているか、非表示になっています
<field> holds a list and cannot be grouped or measured; filter on it instead	ルール3
cannot group by <field>; it is a duration in nanoseconds	ルール4。lcp などの生の列に該当します
cannot group by <field>	ルール5
feature flags are stored per session for <type>; filter on them instead	ルール6
<op> needs a numeric field; <field> is not numeric	文字列またはブール値に対して測定しています
rum is not configured	このデプロイ環境には RUM データベースがありません