翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# CloudWatch Logs Insights クエリの保存と再実行
作成したクエリは、後で再度実行できるように保存できます。保存したクエリは、フォルダ構造が保持されるため、整理された状態を保つことができます。アカウントごとに、リージョンあたり最大 1000 件保存できます。
クエリは、ユーザー固有のレベルではなく、リージョン固有のレベルに保存されます。クエリを作成して保存すると、同じリージョンで CloudWatch Logs にアクセスできる他のユーザーは、リージョンで保存されたすべてのクエリとそのフォルダ構造を表示できます。
クエリを保存するには、アクセス許可 `logs:PutQueryDefinition` を持つロールにログインする必要があります。保存されたクエリのリストを表示するには、アクセス許可 `logs:DescribeQueryDefinitions` を持つロールにログインする必要があります。
**注記**
パラメータを使用してクエリを作成および保存できます。名前付きプレースホルダーを持つ再利用可能なテンプレートです。同じクエリの複数のバリエーションを異なる値で保存する代わりに、1 つのテンプレートを作成し、実行時に異なるパラメータ値を指定します。この機能は現在、Logs Insights クエリ言語を使用するクエリでのみサポートされています。詳細については、[「パラメータを使用した保存済みクエリの使用](#CWL_Insights-Parameterized-Queries)」を参照してください。
------
#### [ Console ]
**クエリを保存するには**
1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。
1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。
1. クエリエディタで、クエリを作成します。
1. **[保存]** を選択します。
1. クエリの名前を入力します。
1. (オプション) クエリを保存するフォルダを選択します。[**新規作成**] を選択して、フォルダを作成します。新しいフォルダを作成した場合、フォルダ名にスラッシュ (/) 文字を使用してフォルダ構造を定義できます。たとえば、新しいフォルダに **folder-level-1/folder-level-2** という名前を付けると、**folder-level-1** という最上位フォルダが作成され、そのフォルダ内に **folder-level-2** という別のフォルダが作成されます。クエリは **folder-level-2** に保存されます。
1. (オプション) クエリのロググループまたはクエリテキストを変更します。
1. (オプション) クエリでパラメータを使用するには、以下の追加ステップに従います。
1. **クエリにパラメータを追加します。**`{{parameter}}` 構文 (パラメータ名の前後に二重括弧) を使用して、静的値をプレースホルダーに置き換えます。
例: 静的な値を持つ元のクエリ:
```
fields @timestamp, @message
| filter level = "Error"
| filter applicationName = "OrderService"
```
パラメータでクエリを更新しました。
```
fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
```
1. **クエリで使用されるパラメータを定義します。**プレースホルダーパラメータごとに、以下を指定します。
+ **名前**: プレースホルダー名と完全に一致する必要があります (例: `logLevel`、`applicationName`)。
+ **デフォルト値** (オプション): パラメータ値が指定されていない場合に使用する値。
+ **説明** (オプション): パラメータの目的について説明します。
1. パラメータを含むクエリを実行するには、`$`プレフィックスが付いたクエリ名を使用し、キーと値のペアとしてパラメータ名を渡します。詳細については**、「保存済みクエリを実行するには**」を参照してください。
1. **[保存]** を選択します。
------
#### [ 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](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html) を呼び出します。
```
{
"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"
}
]
}
```
------
**ヒント**
`PutQueryDefinition` で保存したクエリー用のフォルダを作成することができます。保存したクエリ用のフォルダを作成するには、スラッシュ (/) を使用して、目的のクエリ名の前に目的のフォルダ名を付加します: `/`。このリソースの更新の詳細については、「[PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)」を参照してください。
------
#### [ Console ]
**保存されたクエリを実行するには**
1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。
1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。
1. 右側の [**クエリ**] を選択します。
1. **保存済みクエリリストからクエリ**を選択します。クエリテキストがクエリエディタに表示されます。
1. (オプション) パラメータでクエリを使用するには:
1. **保存済みクエリのサイドパネルで、クエリ**名の横にある **\$1** アイコンを選択します。
1. パラメータを含むクエリがクエリエディタに表示されます。たとえば、 の横にある **\$1** アイコンを選択すると`ErrorsByLevel`、クエリエディタに次のように入力されます。 `$ErrorsByLevel(level=, applicationName=)`
1. パラメータの値 (レベル、applicationName) を指定し、クエリを実行します。例: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")`
1. **[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](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html) を呼び出します。
```
{
"logGroupNames": ["/aws/lambda/my-function"],
"startTime": 1707566400,
"endTime": 1707570000,
"queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}
```
------
**保存したクエリの新しいバージョンを保存するには**
1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。
1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。
1. 右側の [**クエリ**] を選択します。
1. [**保存されたクエリ**] リストからクエリを選択します。クエリエディタに表示されます。
1. クエリを修正します。作業を確認するために実行する必要がある場合は、[**クエリの実行**] を選択します。
1. 新しいバージョンを保存する準備ができたら、[**アクション**]、[**名前を付けて保存**] の順に選択します。
1. クエリの名前を入力します。
1. (オプション) クエリを保存するフォルダを選択します。[**新規作成**] を選択して、フォルダを作成します。新しいフォルダを作成した場合、フォルダ名にスラッシュ (/) 文字を使用してフォルダ構造を定義できます。たとえば、新しいフォルダに **folder-level-1/folder-level-2** という名前を付けると、**folder-level-1** という最上位フォルダが作成され、そのフォルダ内に **folder-level-2** という別のフォルダが作成されます。クエリは **folder-level-2** に保存されます。
1. (オプション) クエリのロググループまたはクエリテキストを変更します。
1. [**Save**] を選択します。
クエリを削除するには、`logs:DeleteQueryDefinition` アクセス許可を持つロールにログインする必要があります。
**保存したクエリを編集または削除するには**
1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。
1. ナビゲーションペインで、**[Logs]** (ログ)、**[Logs Insights]** (ログのインサイト) の順に選択します。
1. 右側の [**クエリ**] を選択します。
1. [**保存されたクエリ**] リストからクエリを選択します。クエリエディタに表示されます。
1. [**アクション**]、[**編集**]、または [**アクション**]、[**削除**] を選択します。
## パラメータを使用した保存済みクエリの使用
パラメータを含む保存されたクエリは、名前付きプレースホルダーを持つ再利用可能なクエリテンプレートです。ほぼ同一のクエリの複数のコピーを維持する代わりに、テンプレートを保存し、クエリの実行時に異なるパラメータ値を指定できます。パラメータは 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
```
### クォータとエラー処理
**注記**
保存された各クエリには、最大 20 個のパラメータを含めることができます。
展開されたクエリ文字列は 10,000 文字を超えることはできません。パラメータ名は文字またはアンダースコアで始まる必要があります。保存されたクエリは、別の保存されたクエリを参照できません (ネストされた呼び出しはサポートされていません）。
**一般的なエラー**
| エラー | 原因 |
| --- | --- |
| パラメータは CWLI クエリ言語でのみサポートされています | パラメータは CloudWatch Logs Insights クエリ言語でのみサポートされます。 |
| queryString にない必須パラメータ | のパラメータ名には、クエリ文字列`{{placeholder}}`に一致するもの`--parameters`がありません。 |
| パラメータ数が最大 20 を超えています | 保存されたクエリは現在、20 個のパラメータのみをサポートしています。 |
| 重複するパラメータ名 | クエリ定義には、 に重複するパラメータがあります`parameters`。 |
**注記**
パラメータを使用して保存されたクエリを作成または更新するには、 アクセス`logs:PutQueryDefinition`許可が必要です。これを実行するには、 `logs:StartQuery`と が必要です`logs:DescribeQueryDefinitions`。