cloud-logging-query-generation

ロギングクエリ言語クエリの生成

このスキルを使用して、Cloud Logging 用の正しい Logging Query Language（LQL）クエリを生成します。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の帰属をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコード内のコマンドは対象外）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-logging-query-generation)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:cloud-logging-query-generation) を追加してください。

基本ルール

1. 厳密な構文要件：

   • 文字列リテラルには**必ず二重引用符（"）**を使用してください。単一引用符（'）は使用しないでください。
   • 論理演算子はすべて大文字で記述してください：AND、OR、NOT。
   • 項をグループ化し、優先順位を明示的に指定するため、必ず括弧を使用してください。

2. よくある落とし穴：

   • インスタンス ID とインスタンス名： gce_instance リソースタイプでは、インスタンス名をインスタンス ID と比較しないでください。インスタンス名は文字列（例：my-instance）で、インスタンス ID は数値です。名前しかわからない場合は、インスタンス名で検索する SEARCH("my-instance") を使用するか、そのリソースで利用可能であれば resource.labels.instance_name を使用してください。
   • リソースタイプの正確性： リソースタイプを推測しないでください。サービス固有のリファレンスファイルで正しい resource.type 値を調べる必要があります。たとえば、転送ルール名やリージョンでフィルタリングする内部 HTTP(S) ロードバランサーのルールには、http_load_balancer ではなく internal_http_lb_rule を使用してください。

3. 出力形式とプレースホルダー：

   • 生の LQL クエリテキストのみを出力してください。会話的な前置きは含めないでください。ユーザーから明示的に求められない限り、クエリを Markdown のコードブロックで囲まないでください。LQL の有効なコメント（-- を使用）は許可されており、説明や警告を含める方法として唯一認められています。
   • 変数が不足していても処理を止めないでください。 ユーザーの依頼に特定の識別子（プロジェクト ID、インスタンス名、IP アドレスなど）がない場合でも、確認を求めないでください。リージョナルログのログバケット名など、機能するクエリに変数が必須の場合は、大文字のプレースホルダー文字列を山括弧で囲んで挿入してください（例："<PROJECT_ID>"）。重要：ユーザーが省略した変数のプレースホルダーを含めると、明示的なフィルタとして機能し、ログが検索対象から漏れます。そのため、そのフィールドが厳密に必須でない場合は、プレースホルダーを含むフィルタや行全体を省略する必要があります。たとえば、ユーザーがインスタンスを指定していない場合は resource.labels.instance_id="..." を完全に省略してください。一方、プロジェクト ID が厳密に必須となるリージョナルログバケットクエリを作成する場合は、プレースホルダーを含む logName=".../projects/<PROJECT_ID>/..." を必ず含めてください。

4. 推奨フィールド：

   • クエリが特定の Google Cloud サービスまたはリソースを対象とする場合は、resource.type と log_id の制限を含めてください。グローバルクエリ（例：「最新のエラーログ」）では、これらの制限は不要です。

詳細リファレンス

演算子、NULL の処理、SEARCH、正規表現など、LQL の構文規則については references/api_reference.md を参照してください。

サービス別の参照ファイル

クエリを生成する前に、対象サービスの例を必ず読んでください。 LQL スキーマと resource.type の値はサービスごとに異なります。ファイル内で基本スキーマを見つけても、そこで読むのをやめないでください。スキーマブロックの下にある段落や具体的なクエリ例に、状態追跡（previousState など）やリソース固有のログ ID に関する要件がないか、必ず確認してください。

次のサービスについては、記載されているファイルを正確に読んでください。

• App Engine
• BigQuery
• Cloud Deployment Manager
• Cloud Functions
• Cloud Observability（Monitoring、Logging、Trace）
• Cloud Run
• Cloud Source Repositories
• Cloud Spanner
• Cloud SQL
• Cloud Storage
• Cloud Tasks
• Compute Engine（GCE）
• Dataflow
• Dataproc
• Kubernetes Engine（GKE）
• IAM とサービスアカウント
• ネットワーキング（VPC、ロードバランシングなど）
• セキュリティ（監査ログ）
• Service Usage（API の有効化／無効化、割り当て）
• サードパーティ（Nginx、Apache など）

一覧にない Google Cloud サービスの場合： 上記に記載されていないサービスについては、一般知識に基づいて LQL クエリを作成してください。

クエリ生成ルール

1. リソースタイプ： 特定のサービスに焦点を当てるクエリでは、resource.type を明示的に指定してください。クエリによっては、複数のタイプを対象に検索する必要があります（例：resource.type=("bigquery_project" OR "bigquery_dataset")）。
2. 監査ログと管理ログ： ユーザーが監査ログ、管理ログ、API ログ、またはリソースを作成、更新、削除、読み取り、アクセスしたユーザーに関するログを求めている場合：
   • 正しい protoPayload スキーマパスと一般的な例を確認するため、必ず references/query_audit_logs.md を読んでください。
   • 具体的な例が記載されていない場合は、サービス名と動詞を組み合わせて protoPayload.methodName を推測してください。推測する場合は、バージョン接頭辞の不一致を避けるため、完全一致演算子（=）ではなく、スコープ指定された SEARCH() 関数を使用してください（例：SEARCH(protoPayload.methodName, "compute.instances.insert")）。部分文字列の誤検出を招く可能性があるため、コロン演算子（:）は使用しないでください。
   • 一般的な API の有効化／無効化イベント（例：サービスが無効化された場合）では、必ず resource.type="audited_resource" を使用してください。
3. 不明なスキーマへの対応（重要）： ユーザーが特定のフィールドや条件によるフィルタリングを求めていて、参照ファイルに該当する例やスキーマが見つからない場合は、グローバル検索を使ってクエリを生成してください。
   • 正確な名前が確実に分かる場合に限り、jsonPayload.* または protoPayload.* のフィールド構造を指定してください。
   • 正しい resource.type の範囲内でキーワードをグローバルに検索するには、SEARCH() 関数を使用してください。
   • 必須の LQL コメント： SEARCH を使ったクエリを提示する場合、参照資料に正確なスキーマがなかったためグローバルなキーワード検索を使用したことを示す LQL コメント（-- を使用）をクエリの先頭に必ず追加してください。会話形式の文章は出力せず、出力形式のルールを厳守してください。

関連リンク

• Cloud Logging のクエリ言語に関するドキュメント
• 監視対象リソースタイプのカタログ
• Cloud Logging のクエリライブラリ