翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

CloudWatch Logs Insights クエリの保存と再実行

作成したクエリは、後で再度実行できるように保存できます。保存したクエリは、フォルダ構造が保持されるため、整理された状態を保つことができます。アカウントごとに、リージョンあたり最大 1000 件保存できます。

クエリは、ユーザー固有のレベルではなく、リージョン固有のレベルに保存されます。クエリを作成して保存すると、同じリージョンで CloudWatch Logs にアクセスできる他のユーザーは、リージョンで保存されたすべてのクエリとそのフォルダ構造を表示できます。

クエリを保存するには、アクセス許可 logs:PutQueryDefinition を持つロールにログインする必要があります。保存されたクエリのリストを表示するには、アクセス許可 logs:DescribeQueryDefinitions を持つロールにログインする必要があります。

Console

クエリを保存するには

1. CloudWatch コンソールの https://console.aws.amazon.com/cloudwatch/ を開いてください。

2. ナビゲーションペインで、[Logs] (ログ)、[Logs Insights] (ログのインサイト) の順に選択します。

3. クエリエディタで、クエリを作成します。

4. [保存] を選択します。

5. クエリの名前を入力します。

6. (オプション) クエリを保存するフォルダを選択します。[新規作成] を選択して、フォルダを作成します。新しいフォルダを作成した場合、フォルダ名にスラッシュ (/) 文字を使用してフォルダ構造を定義できます。たとえば、新しいフォルダに folder-level-1/folder-level-2 という名前を付けると、folder-level-1 という最上位フォルダが作成され、そのフォルダ内に folder-level-2 という別のフォルダが作成されます。クエリは folder-level-2 に保存されます。

7. (オプション) クエリのロググループまたはクエリテキストを変更します。

8. (オプション) クエリでパラメータを使用するには、以下の追加ステップに従います。

   1. クエリにパラメータを追加します。{{parameter}} 構文 (パラメータ名の前後に二重括弧) を使用して、静的値をプレースホルダーに置き換えます。

      例: 静的な値を持つ元のクエリ:

      fields @timestamp, @message
      | filter level = "Error"
      | filter applicationName = "OrderService"

      パラメータでクエリを更新しました。

      fields @timestamp, @message
      | filter level = {{logLevel}}
      | filter applicationName = {{applicationName}}

   2. クエリで使用されるパラメータを定義します。プレースホルダーパラメータごとに、以下を指定します。

      • 名前: プレースホルダー名と完全に一致する必要があります (例: logLevel、applicationName)。

      • デフォルト値 (オプション): パラメータ値が指定されていない場合に使用する値。

      • 説明 (オプション): パラメータの目的について説明します。

   3. パラメータを含むクエリを実行するには、$プレフィックスが付いたクエリ名を使用し、キーと値のペアとしてパラメータ名を渡します。詳細については、「保存済みクエリを実行するには」を参照してください。

9. [保存] を選択します。

AWS CLI

クエリを保存するには、 を使用しますput-query-definition。

aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

(オプション) パラメータを含むクエリを保存するには、 --parametersオプションを追加し、クエリ文字列に{{parameterName}}プレースホルダーを使用します。

aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

クエリをフォルダに保存するには、クエリ名の前にフォルダパスを付けます。

aws logs put-query-definition \
  --name "my-folder/ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

API

クエリを保存するには、PutQueryDefinition を呼び出します。

{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = \"ERROR\"",
  "logGroupNames": ["/aws/lambda/my-function"]
}

(オプション) パラメータを含むクエリを保存するには、 parametersフィールドを含め、クエリ文字列に{{parameterName}}プレースホルダーを使用します。

{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}",
  "logGroupNames": ["/aws/lambda/my-function"],
  "parameters": [
    {
      "name": "logLevel",
      "defaultValue": "ERROR",
      "description": "Log level to filter"
    },
    {
      "name": "applicationName",
      "defaultValue": "OrderService",
      "description": "Application name to filter"
    }
  ]
}

Console

保存されたクエリを実行するには

1. CloudWatch コンソールの https://console.aws.amazon.com/cloudwatch/ を開いてください。

2. ナビゲーションペインで、[Logs] (ログ)、[Logs Insights] (ログのインサイト) の順に選択します。

3. 右側の [クエリ] を選択します。

4. 保存済みクエリリストからクエリを選択します。クエリテキストがクエリエディタに表示されます。

5. (オプション) パラメータでクエリを使用するには:

   1. 保存済みクエリのサイドパネルで、クエリ名の横にある + アイコンを選択します。

   2. パラメータを含むクエリがクエリエディタに表示されます。たとえば、 の横にある + アイコンを選択するとErrorsByLevel、クエリエディタに次のように入力されます。 $ErrorsByLevel(level=, applicationName=)

   3. パラメータの値 (レベル、applicationName) を指定し、クエリを実行します。例: $ErrorsByLevel(level= "ERROR", applicationName= "OrderService")

6. [Run] (実行) を選択します。

AWS CLI

パラメータを使用して保存されたクエリを実行するには

$QueryName() 構文start-queryで を使用します。

aws logs start-query \
  --log-group-names "/aws/lambda/my-function" \
  --start-time 1707566400 --end-time 1707570000 \
  --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \
  --region us-east-1

API

パラメータを使用して保存されたクエリを実行するには

queryString フィールドの$QueryName()構文を使用して StartQuery を呼び出します。

{
  "logGroupNames": ["/aws/lambda/my-function"],
  "startTime": 1707566400,
  "endTime": 1707570000,
  "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}

クエリを削除するには、logs:DeleteQueryDefinition アクセス許可を持つロールにログインする必要があります。

パラメータを使用した保存済みクエリの使用

パラメータを含む保存されたクエリは、名前付きプレースホルダーを持つ再利用可能なクエリテンプレートです。ほぼ同一のクエリの複数のコピーを維持する代わりに、テンプレートを保存し、クエリの実行時に異なるパラメータ値を指定できます。パラメータは CloudWatch Logs Insights クエリ言語でのみサポートされます。

仕組み

クエリを保存する場合、プレースホルダーはクエリ実行時に指定できる値を識別します。プレースホルダーは {{parameterName}}構文を使用します。以下は、 logLevelと の 2 つのパラメータErrorsByLevelを持つ という名前の保存済みクエリの例ですapplicationName。

fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}

保存済みクエリを実行するには、 というプレフィックスが付いたクエリ名を使用してクエリを呼び出し$、パラメータ値を渡します。CloudWatch Logs Insights クエリエンジンは、各プレースホルダーを置き換えます。パラメータにデフォルト値が含まれている場合、他の値が指定されていない場合はそれらの値が使用されます。

# Run query by using query name and passing parameter values explicitly
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")

# Run query without specifying parameter values - default values are used in this case.
$ErrorsByLevel()

スペースまたは特殊文字を含む保存されたクエリ名は、バックティックで囲む必要があります。

$`Errors By Level`(logLevel = "WARN")

パラメータを含む保存済みクエリのサンプル

パラメータとして結果制限を追加する

クエリ名: パラメータErrorsByLevel付き logLevel (デフォルト: "ERROR")、 applicationName (デフォルト: "OrderService")、および maxResults (デフォルト: 50)

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

# Run the query using the query name and passing parameter values
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100)

パラメータで複数の保存されたクエリを使用する

以下の例では、 ErrorsByLevelおよび として定義された 2 番目の保存RecentN済みクエリ sort @timestamp desc | limit {{count}} (パラメータ 、countデフォルト ) を使用します20。CloudWatch Logs Insights クエリエンジンは、各クエリを実行する前に展開します。

# Using multiple queries with parameters in sequence
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")
| $RecentN(count = 10)

# Each of the queries is expanded, resulting in the following query when it is run.
fields @timestamp, @message
| filter level = "WARN"
| filter applicationName = "OrderService"
| sort @timestamp desc
| limit 10

クォータとエラー処理

展開されたクエリ文字列は 10,000 文字を超えることはできません。パラメータ名は文字またはアンダースコアで始まる必要があります。保存されたクエリは、別の保存されたクエリを参照できません (ネストされた呼び出しはサポートされていません）。