superlog-debug

Superlog の本番環境デバッグ

ユーザーが本番環境で起きていることを調査している場合、コードについて推論する前に、実際のテレメトリを確認してください。Superlog は、ユーザーのサービスの OpenTelemetry トレース、ログ、メトリクスを取り込みます。「なぜ 500 が発生したのか？」「デプロイは正常か？」「何が変わったのか？」という問いへの答えは、ほとんどの場合そこにあります。

有効化するタイミング

ユーザーが実際の本番環境の挙動を調べていると示したら、すぐに有効化してください。例：

• 「ユーザーがサインインできない」／「チェックアウトが壊れている」／「本番環境で 500 が発生している」
• 「デプロイは正常か？」／「自分の PR で何かが悪化したか？」
• 「今の /api/foo の p95 は？」／「過去 1 時間のエラー数は？」
• 「夜間、ワーカーに何が起きていた？」
• インシデントチャンネルのメッセージ、Sentry／PagerDuty のリンク、オンコールからの通知。

次の場合はスキップしてください。

• 作業がローカルのみの場合（worktree での開発、テスト、型エラー、lint）。
• ユーザーがすでに関連するログ／トレース／スパンを貼り付けている場合。
• 本番環境に関係なく、「このコードはどのような構成か」だけを尋ねている場合。

前提条件：Superlog MCP がインストールされていること

以下のツールは Superlog MCP サーバーによって公開されています。現在のエージェントで利用できない場合は、まずインストールしてください。

Claude Code の場合：

claude mcp add --transport http superlog https://api.superlog.sh/mcp

Codex の場合：

codex mcp add superlog --url https://api.superlog.sh/mcp
codex mcp login superlog

Cursor などの場合：https://superlog.sh/ → Connect から mcpServers のスニペットをコピーしてください。

インストール後、エージェントを再起動し、MCP が初回使用時に開始する OAuth フローで認証してください。

各セッションで最初に呼び出すツール

superlog.get_active_project

デバッグ対象がユーザーのプロジェクトではない場合は、切り替えてください。

superlog.list_projects
superlog.set_active_project { project_id: "<id>" }

セッション状態を変更せずに、個々の呼び出しに project_id を渡すこともできます。ユーザーが複数の環境を別々のプロジェクト（例：prod と staging）として設定している場合は、クエリを実行する前にどちらを対象とするか確認してください。

ツール早見表

すべてのクエリツールは、デフォルトでアクティブなプロジェクトの直近 1 時間を対象とします。range: { since, until } で変更できます。どちらも ISO-8601（"2026-05-28T14:00:00Z"）または ClickHouse 式（"now() - INTERVAL 30 MINUTE"）を受け付けます。

ツール	用途
superlog.list_services	対象時間内にテレメトリを出力したサービスを確認する
superlog.query_logs	ログ本文を検索する。service、severity、resource_attrs、log_attrs で絞り込む
superlog.query_traces	遅いスパンやエラーのあるスパンを見つける。service、span_name、min_duration_ms、status_code、span_attrs で絞り込む
superlog.query_metrics	metric_name と service を指定して、最近のメトリクス値を取得する
superlog.list_alerts / get_alert	ユーザーが確認している事象にすでに対応している既存のアラートがないか確認する
superlog.list_dashboards / get_dashboard	クエリを一から作る前に、影響を受けている領域に対応する既存のダッシュボードを探す

query_logs のヒント

• severity は、保存されている OTel の重大度テキストと大文字・小文字を区別せずに照合します。SDK が実際に出力する短縮形（"ERROR"、"WARN"、"INFO"、"DEBUG"）を使ってください。"WARNING" は使わないでください。保存されているテキストは WARN なので、何も一致しません。絞り込みは積極的に行ってください。インシデント発生時は、通常、エラーのみから調べ始めるのが適切です。
• search はログ本文に対する、大文字・小文字を区別しない部分文字列検索です。スタックトレースや特定のメッセージを見つけるのに、手軽で効果的です。
• log_attrs は、レコードごとの属性（event.name や、アプリが各ログに設定するカスタム構造化フィールドなど）で絞り込みます。
• resource_attrs は、OTel リソースのサービスレベル属性（deployment.environment.name=production、service.version=1.42.0 など）で絞り込みます。現在の OTel semconv キーを使ってください。deployment.environment.name は古い deployment.environment に取って代わっており、最近の SDK を使うアプリは新しいキーのみを出力します。各エントリでは、任意の op として eq（デフォルト）、neq、not_contains も指定できます。
• レスポンスにはログごとの resource_attrs マップが含まれるため、2 回目の呼び出しをせずに、結果からサービス、環境、バージョンを確認できます。
• スパンの外部で出力されたログでは、trace_id / span_id の文字列が空になります。これは想定どおりであり、バグではありません。一部のログにトレースコンテキストがないからといって、トレースのパイプラインが壊れていると判断しないでください。

query_traces のヒント

• HTTP ステータスコードは status_code ではなく、span_attrs にあります。 OTel の status_code は意味上の OK／ERROR／UNSET を表します。また、OTel HTTP semconv では、サーバーからの 5xx レスポンスのみが自動的にスパンを ERROR にします。4xx レスポンスを見つけるには、次のようにします。

  span_attrs: [{ key: "http.response.status_code", value: "404" }]
  

• status_code フィルターでは列挙型の形式（STATUS_CODE_OK、STATUS_CODE_ERROR、STATUS_CODE_UNSET）を指定しますが、各スパンについてレスポンスが返す値はタイトルケース形式（"Ok"、"Error"、"Unset"）です。レスポンスの値を列挙型と等値比較しようとしないでください。

• 「遅い X リクエスト」を調べるには、service、span_name、min_duration_ms: 1000 を指定してください。

• ルートレベルで絞り込むには、実際の URL ではなく、テンプレート（例：/api/users/:id）である http.route を span_attrs に指定してください。実際の URL はカーディナリティが高くなります。

• データベース呼び出しを調べるには、DB ホストを指す HTTP 形式のクライアントスパンで絞り込むか、アプリの計装が出力している場合は db.system で絞り込んでください（SDK によっては出力されないため、最初にサンプルスパンの span_attrs を確認してください）。

• 返される各スパンには span_attrs と resource_attrs の両方が含まれるため、結果から直接、サービスのバージョン、環境、インスタンスを確認できます。

query_metrics のヒント

• 常に metric_name を（通常は service も）指定してください。これらを指定しなくても呼び出しは動作しますが、直近に書き込まれたものが何でも返されるため、求める結果とは異なることがほとんどです。
• 返される各ポイントには、kind（gauge／sum／histogram／summary）、metric_name、unit、service、ポイントごとの attributes（ルート、ステータス、テナントなどの系列のディメンション）、および resource_attrs が含まれます。ポイントがどの系列に属するかを判別するには、attributes を使ってください。
• gauge／sum のポイントにはスカラー値 value が含まれます。 histogram／summary のポイントにはスカラー値がなく、代わりに count と sum が含まれます（さらに、ヒストグラムには min／max も含まれます）。したがって、ヒストグラムの平均は sum / count で、value は null です。これは想定どおりなので、count／sum／min／max を確認してください。
• レートを求めるには、MCP に計算させるのではなく、2 つの時間ウィンドウで元のカウンターを取得し、自分で差分を計算してください。レイテンシのパーセンタイルを求めるには、ダッシュボードのウィジェットを作成してください（ダッシュボードのクエリレイヤーがヒストグラムの分位数を再構成します）。query_metrics の生のポイントからは p95 を直接取得できません。

調査手順

「本番環境で今、Xに問題が発生していますか？」

1. 過去30分間の list_services — サービスはそもそもレポートを送信していますか？無応答もシグナルです。
2. query_logs で service: "<svc>"、severity: "ERROR" を指定し、過去30分間を確認します。スタックトレースのサンプルをそのままユーザーに引用します。
3. query_traces で service: "<svc>"、status_code: "STATUS_CODE_ERROR" を指定し、必要に応じて span_attrs で http.response.status_code をフィルタリングして4xxを検出します。
4. エラーが特定のルートに集中している場合、そのルートの最近のトレースから最も遅いものを取得し、失敗した操作（DBステートメント、下流のURL、例外メッセージ）の SpanAttributes を確認します。

「このエンドポイントは遅いです」

1. query_traces で service に加え、span_name または span_attrs: [{ key: "http.route", value: "/api/foo" }] のいずれかと、min_duration_ms: 1000 を指定し、過去1時間を確認します。
2. 遅い順にスパンを並べて確認し、span_attrs（サービスのバージョン／環境については resource_attrs も）を展開します。時間のかかるDB呼び出し（http.host がDBを指している、または db.system が設定されているもの）、下流HTTPへのファンアウト、キュー待ちを探します。
3. 遅い子操作が見つかった場合、そのスパン名を直接指定して再クエリし、全体的に遅いのか、このルートでのみ遅いのかを確認します。

「デプロイで何か悪化しましたか？」

1. デプロイのタイムスタンプを確認します（明らかでなければユーザーに尋ねます）。
2. 対象サービスについて、デプロイ前とデプロイ後の同じ長さの2つの時間枠で query_logs の severity: "ERROR" を実行します。件数と固有のエラーシグネチャを比較します。
3. 両方の時間枠で、リクエストレート、エラーレート、レイテンシのメトリクスを query_metrics で確認します。
4. デプロイ後に query_traces の status_code: "STATUS_CODE_ERROR" を実行します。アプリがリリース情報をタグ付けしている場合は、resource_attrs: [{ key: "service.version", value: "<new-version>" }] で絞り込みます。返されたスパンには resource_attrs が含まれるため、各エラーをどのバージョンが出したか確認できます。

「このサービスは夜間に何をしていましたか？」

1. 夜間の range を指定して list_services を実行し、継続的にレポートが送信されていたことを確認します。
2. 対象の時間枠で、まず severity: "ERROR"、次に severity: "WARN" を指定して query_logs を実行し、集中しているエラーや時刻ごとの傾向を確認します。
3. サービスの主要なビジネスカウンターを query_metrics で確認し、低下や急増がないか調べます。

「ユーザーはこのコードパスを利用していますか？」

1. service と span_name を指定して query_traces を実行します。または、feature.flag や tenant.id のようなカスタムビジネス属性で span_attrs をフィルタリングします。
2. 件数がゼロの場合は、ソースコードと照らし合わせてスパン名と属性キーを確認します。ここでのタイプミスが、誤検出の最大の原因です。

出力時の注意

• 手法ではなく、見つかった内容から伝えます。「過去15分間に api で47件のERRORログがあり、すべて db.query からの TimeoutError です」は、どのツールを呼び出したかを説明する段落よりも有用です。
• 実際の根拠を引用します：タイムスタンプ、トレースID、スパンID、正確なエラーメッセージ。ユーザーが回答からSuperlog UIに移動して、それぞれを確認できるようにします。
• 対象の時間枠を明示します：「過去30分間」「14:00 UTC以降」など。時間枠のない調査結果は、対応に役立ちません。
• ゼロと不明を区別します。「一致するスパンはゼロ件です」は、クエリを実行して何も返されなかったことを意味します。明確にそう伝えます。「アクティブなプロジェクトがこのサービスのプロジェクトではないため、クエリを実行できませんでした」は別の状況なので、そう伝えます。
• 必要以上に提案しません。テレメトリからサービスが正常だと分かる場合は、明確にそう伝えて終わります。忙しそうに見せるためだけに「次のステップ」を作り出さないでください。

他のコンテキストとの連携

Superlog MCP で確認できるのは、ユーザーのアプリが OpenTelemetry としてエクスポートした情報だけです。以下は確認できません。

• 行レベルのデータベースの状態 — データベースに直接クエリするか、インストール済みであれば Postgres／MySQL MCP を使用してください。
• OTel パイプラインに取り込まれなかった、クラウドプロバイダーのホスト／コンテナのログ（CloudWatch、GCP Logging、Fly logs、Railway logs など）。
• アプリが明示的にメトリクスを出力していない場合の、キューの深さ（SQS、RabbitMQ など）。
• アプリが計測していない情報。

MCP からサービスに関する情報が何も返ってこなくても、そのサービスが稼働していないと結論づけないでください。まず、テレメトリが ingest に届いているか確認してください。エクスポーターが存在しない、または設定を誤っている、service.name が間違っている、ingest キーが別のプロジェクトのもの、といった場合は、ホストレベルでサービスが稼働し大量のログを出していても「MCP から何も見えない」状態になります。ユーザーがこの問題を修正する必要がある場合は、インストール手順を superlog-onboard スキルで確認できます。

まず確認すべき具体的な障害の例として、トークンが有効なのに、すべての ingest リクエストが 401 になるケースがあります。トークンの送信先ヘッダー名が間違っています。ingest がトークンを読み取るのは x-api-key: <token> または Authorization: Bearer <token>（リテラルな Bearer プレフィックスが必須）だけです。それ以外（api-key、x-superlog-token、Bearer を付けない Authorization: <token>）では、すべてのリクエストが 401 になるため、キー自体は正しくてもインストールが壊れているように見えます。アプリのエクスポーター設定とは別に、キーが機能することを手早く確認する方法は次のとおりです。

curl -i -X POST https://intake.superlog.sh/v1/traces \
  -H "x-api-key: sl_public_..." \
  -H "content-type: application/json" --data '{"resourceSpans":[]}'
# 2xx → key is valid; the app is sending the wrong header. Fix the exporter to use x-api-key.
# 401 → the token itself is wrong/revoked.

厳守事項

• デフォルトでは読み取り専用です。 query_* と list_* の呼び出しは安全です。create_alert、update_dashboard、delete_* などはユーザーのアカウントを変更します。明示的に依頼されない限り、これらを実行しないでください。依頼された場合も、まず具体的な変更内容を確認してください。
• スパン／ログ属性に含まれる ingest トークンやシークレットを、完全な形でチャットに表示しないでください。言及する必要がある場合は、一部を省略してください。
• アクティブなプロジェクトを、ユーザーに知らせずに切り替えないでください。set_active_project を呼び出す場合は、その旨と理由をユーザーに伝えてください。
• 質問の範囲に合わせてください。「本番環境は大丈夫？」と聞かれたユーザーには、12 個のクエリで一通り調査するのではなく、2 行で答えてください。調査の必要に応じてのみ、掘り下げてください。