CloudWatch Logs Insights の保存クエリにパラメータを設定して使い回してみた

こんにちは。
SELECT hope FROM life;
オペレーション部のかわいです。

2026年4月13日、Amazon CloudWatch Logs Insights の保存クエリにパラメータ（変数）を設定できるようになりました。
https://aws.amazon.com/about-aws/whats-new/2026/03/cloudwatch-logs-insights-query-params/

これまでは、ログレベルやサービス名を変えつつ同じ構造のクエリを使い回したい場合、値が異なるクエリをいくつも用意するか、毎回エディタ上で手書き編集するしかありませんでした。

今回のアップデートで、クエリ定義に {{parameterName}} 形式のプレースホルダを埋め込み、実行時に値を渡せるようになりました。これにより、1つのテンプレートで複数の用途をカバーできます。

本記事では、パラメータ付き保存クエリを作成、実行する手順を検証します。

パラメータ付き保存クエリとは？

CloudWatch Logs Insights は、ログデータをインタラクティブに検索・集計できるサービスです。
よく使うクエリは「保存クエリ」として名前をつけて保管できます。

これまでは、ログレベルやサービス名などの、値が異なるだけでほぼ同じ構造のクエリを、それぞれ別の保存クエリとして管理する必要がありました。今回のアップデートでは、クエリ定義に {{パラメータ名}} 形式のプレースホルダを埋め込み、実行時に値を渡せるようになりました。1つのテンプレートで複数の用途をカバーできるため、メンテナンスするクエリ数を大幅に削減できます。

※パラメータ機能は Logs Insights Query Language（CWLI）を使用するクエリのみ対応しています。PPL（Piped Processing Language）や SQL では現時点では使用できません。

■変更前の例（値が固定）

fields @timestamp, @message
| filter level = "ERROR"
| filter applicationName = "OrderService"
| sort @timestamp desc
| limit 20

■変更後の例

fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
| sort @timestamp desc
| limit {{maxResults}}

また、実行時は以下のように呼び出します。

$ErrorsByApp(logLevel="ERROR", applicationName="OrderService", maxResults=20)

【制限事項】

何が嬉しいのか

直接クエリを書けばいいんじゃないの？と思うかもですが、パラメータ付き保存クエリは、特に以下のような場面で使えそうです。

• Default値を用いて、クエリを省略して実行できる
  例えば$OrderError() のような書き方で実行できます。普段は固定値で、必要なときだけパラメータ側を編集すればok。

• チームで共通テンプレートを持てる
  クエリ構造はチームで統一しつつ、実行時の値だけを変える運用ができます。

• 複数クエリを部品として組み合わせられる
  パラメータ付き保存クエリ同士をパイプでつなぎ組み合わせることで、複雑な分析が可能になります（詳しくは後述）。

逆に個人利用や単発フィルタの変更程度であれば、エディタで直接書いて実行するほうが楽です。

コスト見積もり

事前準備

習うより慣れろ。早速やっていきましょう。
操作は AWS マネジメントコンソール 上で実施します。

サンプルログの用意

パラメータ付きクエリを試すためにサンプルログを用意します。
今回は Lambda 関数で JSON 形式のログを出力させます。

1. Lambda 関数の作成

マネジメントコンソールから Lambda を開き、【Create Function】をクリックします。

lambda_function.pyを以下に置き換えて Deploy

services と levels からランダムに値を選び、1回の実行で20件の JSON ログを出力します。
出力例は以下のようなイメージ。

{"level": "ERROR", "applicationName": "PaymentService", "message": "Sample log entry 3", "requestId": "abc-123"}
{"level": "INFO",  "applicationName": "OrderService",   "message": "Sample log entry 7", "requestId": "abc-123"}

▼コード

import json
import logging
import random

logger = logging.getLogger()
logger.setLevel(logging.INFO)

def lambda_handler(event, context):
    services = ["OrderService", "PaymentService", "NotificationService"]
    levels = ["INFO", "WARN", "ERROR"]

    for i in range(20):
        log = {
            "level": random.choice(levels),
            "applicationName": random.choice(services),
            "message": f"Sample log entry {i}",
            "requestId": context.aws_request_id
        }
        logger.info(json.dumps(log))

    return {"statusCode": 200}

5. Test → テストイベントを任意の名前で作成し、間隔を空けて数回実行する

これで /aws/lambda/test-log-generator にサンプルログが出力されます。

検証

1. パラメータなしの保存クエリを作成

後でパラメータ付きと比較するため、まずは値が固定された保存クエリを作成します。

1. CloudWatch コンソール → Logs → Logs Insights
2. ロググループ に /aws/lambda/test-log-generator を選択
3. クエリエディタに以下を入力し Run queryで実行

fields @timestamp, @message
| filter @message like /ERROR/
| sort @timestamp desc
| limit 20

ログレベル「ERROR」のみが抽出されました

4. 保存 をクリック
5. 名前を ErrorLog として保存

この時点では値（"ERROR"）がクエリ定義にハードコードされています。
例えばログレベルを"WARN" に変えて使いたい場合は別途保存するか、毎回編集が必要です。

2. パラメータ付き保存クエリを作成

次に、ログレベルとサービス名をパラメータ化したクエリを作成します。

1. クエリエディタの内容を以下に書き換える

fields @timestamp, @message
| filter @message like /{{logLevel}}/
| filter @message like /{{applicationName}}/
| sort @timestamp desc
| limit 20

※ {{}} はプレースホルダ構文で、ここに書いた名前がそのままパラメータ名になります。大文字/小文字は区別されます（logLevel と loglevel は別物）。

2. 保存 をクリック
3. クエリ名に OrderError を入力

ここで、「Query parameters - optional」セクションが表示されます。

4. Add parameter をクリックし、以下を入力

5. 保存 をクリック

3. パラメータ付きクエリを実行する

a) デフォルト値で実行

1. 画面右上のフォルダアイコンをクリックして Saved queries パネルを開く

2. OrderError - CWLI の横の + アイコンをクリック
   

3. エディタに以下が自動展開されます

$OrderError(logLevel=ERROR, applicationName=OrderService)

4. そのまま Run query

Default値 の ERROR と OrderService が適用されてクエリが実行されます。出力は以下。

b) 値を変えて実行

a) で展開された呼び出し文を、エディタ上で直接書き換えます。

$OrderError(logLevel="WARN", applicationName="PaymentService")

logLevel を "WARN"、applicationName を "PaymentService" に変えて Run query をクリックします。アップデートさえしなければ、保存済みクエリの定義（テンプレート）は変わらず、実行時の値だけが変わります。

c) 複数クエリを組み合わせる

パラメータ付き保存クエリ同士をパイプでつないで実行できます。ここでは新たに MostRecentLogs という保存クエリを作成し、直近の10件を取得するようにしてみます。OrderError と組み合わせることで、条件に合うログの中から直近10件だけ取得するクエリになります。

【MostRecentLogs クエリの作成】

1. 新規エディタに以下を入力して Save

sort @timestamp desc
| limit {{count}}

2. クエリ名に MostRecentLogs を入力
3. クエリパラメータを追加（パラメータ名:count、Default値:10）
4. Save をクリック

【組み合わせ実行】

先ほどの Saved queries パネルから OrderError の +（プラス） をクリックしてエディタに展開、末尾に | $MostRecentLogs() を追記します（パイプで繋ぎます）。

$OrderError(logLevel="ERROR", applicationName="OrderService") | $MostRecentLogs()

Run query を実行するとcount のデフォルト値 10 が適用され、展開後は以下と同様のクエリとして処理されます。

fields @timestamp, @message
| filter @message like /ERROR/
| filter @message like /OrderService/
| sort @timestamp desc
| limit 10

直近の10件が出力されました

まとめ的なやつ

本記事では、CloudWatch Logs Insights のパラメータ付き保存クエリを検証してみました。

{{parameterName}} でプレースホルダを埋め込んだクエリを保存しておけば、実行時に$QueryName(param=value) で値を渡して使い回せるようになります。
クエリ文を直接編集せずにクエリパラメータを変更したり、パラメータを定義したクエリ同士をパイプで組み合わせたりできるので、地味に便利だと思いました。

完

【参考リンク】

https://aws.amazon.com/about-aws/whats-new/2026/03/cloudwatch-logs-insights-query-params/
https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.html