기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# CloudWatch Logs Insights 쿼리 저장 및 재실행
쿼리를 생성한 후 나중에 다시 실행할 수 있도록 저장할 수 있습니다. 쿼리는 폴더 구조로 저장되므로 체계적으로 관리할 수 있습니다. 계정별로 리전당 최대 1,000개의 쿼리를 저장할 수 있습니다.
쿼리는 사용자별 수준이 아닌 리전별 수준에 저장됩니다. 쿼리를 생성하고 저장하는 경우 동일한 리전의 CloudWatch Logs에 액세스할 수 있는 다른 사용자는 해당 리전의 저장된 모든 쿼리와 폴더 구조를 볼 수 있습니다.
쿼리를 저장하려면 `logs:PutQueryDefinition` 권한이 있는 역할에 로그인해야 합니다. 저장된 쿼리의 목록을 보려면 `logs:DescribeQueryDefinitions` 권한이 있는 역할에 로그인해야 합니다.
**참고**
파라미터, 즉 명명된 자리 표시자가 있는 재사용 가능한 템플릿을 사용하여 쿼리를 생성하고 저장할 수 있습니다. 동일한 쿼리의 여러 변형을 다른 값으로 저장하는 대신 하나의 템플릿을 생성하고 실행할 때 다른 파라미터 값을 제공합니다. 이 기능은 현재 Logs Insights 쿼리 언어를 사용하는 쿼리에만 지원됩니다. 자세한 내용은 [파라미터와 함께 저장된 쿼리 사용을](#CWL_Insights-Parameterized-Queries) 참조하세요.
------
#### [ Console ]
**쿼리를 저장하려면**
1. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. 탐색 창에서 **로그**를 선택한 다음, **로그 인사이트**를 선택합니다.
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`을 사용하여 저장된 쿼리에 대한 폴더를 만들 수 있습니다. 저장된 쿼리에 대한 폴더를 만들려면 슬래시(/)를 사용하여 원하는 쿼리 이름에 원하는 폴더 이름을 접두사로 붙입니다. `<{{folder-name}}>/<{{query-name}}>`. 이 작업에 대한 자세한 내용은 [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html)을 참조하세요.
------
#### [ Console ]
**저장된 쿼리를 실행하려면**
1. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. 탐색 창에서 **로그**를 선택한 다음, **로그 인사이트**를 선택합니다.
1. 오른쪽에서 **쿼리**를 선택합니다.
1. **저장된 쿼리 목록에서 쿼리**를 선택합니다. 쿼리 텍스트가 쿼리 편집기에 나타납니다.
1. (선택 사항) 파라미터와 함께 쿼리를 사용하려면:
1. **저장된 쿼리** 사이드 패널에서 쿼리 이름 옆에 있는 **\+** 아이콘을 선택합니다.
1. 파라미터가 있는 쿼리는 쿼리 편집기에 나타납니다. 예를 들어 옆에 있는 **\+** 아이콘을 선택하면 `ErrorsByLevel`쿼리 편집기가 다음과 같이 채워집니다. `$ErrorsByLevel(level=, applicationName=)`
1. 파라미터(level, applicationName) 값을 입력하고 쿼리를 실행합니다. 예: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")`
1. **실행**을 선택합니다.
------
#### [ AWS CLI ]
**파라미터로 저장된 쿼리를 실행하려면**
구문과 `start-query` 함께 `$QueryName()`를 사용합니다.
```
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. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. 탐색 창에서 **로그**를 선택한 다음, **로그 인사이트**를 선택합니다.
1. 오른쪽에서 **쿼리**를 선택합니다.
1. **저장된 쿼리** 목록에서 쿼리를 선택합니다. 이 쿼리가 쿼리 편집기에 나타납니다.
1. 쿼리를 수정합니다. 작업을 확인하기 위해 쿼리를 실행해야 하는 경우 **쿼리 실행**을 선택합니다.
1. 새 버전을 저장할 준비가 되면 **작업**, **다른 이름으로 저장**을 선택합니다.
1. 쿼리의 이름을 입력합니다.
1. (선택 사항) 쿼리를 저장할 폴더를 선택합니다. **새로 생성**을 선택하여 폴더를 만듭니다. 새 폴더를 만드는 경우 폴더 이름에 슬래시(/) 문자를 사용하여 폴더 구조를 정의할 수 있습니다. 예를 들어, 새 폴더의 이름을 **folder-level-1/folder-level-2**로 지정하면 **folder-level-1**이라는 최상위 폴더가 만들어지고 그 폴더 안에 **folder-level-2**라는 다른 폴더가 만들어집니다. 쿼리가 **folder-level-2**에 저장됩니다.
1. (선택 사항) 쿼리의 로그 그룹 또는 쿼리 텍스트를 변경합니다.
1. **저장**을 선택합니다.
쿼리를 삭제하려면 `logs:DeleteQueryDefinition` 권한이 있는 역할에 로그인해야 합니다.
**저장된 쿼리를 편집 또는 삭제하려면**
1. [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)에서 CloudWatch 콘솔을 엽니다.
1. 탐색 창에서 **로그**를 선택한 다음, **로그 인사이트**를 선택합니다.
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` 및 `sort @timestamp desc | limit {{count}}` (파라미터 `count`, 기본값 )로 `RecentN` 정의된 두 번째 저장된 쿼리를 사용합니다`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`.