기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

CloudWatch Logs Insights 쿼리 저장 및 재실행

쿼리를 생성한 후 나중에 다시 실행할 수 있도록 저장할 수 있습니다. 쿼리는 폴더 구조로 저장되므로 체계적으로 관리할 수 있습니다. 계정별로 리전당 최대 1,000개의 쿼리를 저장할 수 있습니다.

쿼리는 사용자별 수준이 아닌 리전별 수준에 저장됩니다. 쿼리를 생성하고 저장하는 경우 동일한 리전의 CloudWatch Logs에 액세스할 수 있는 다른 사용자는 해당 리전의 저장된 모든 쿼리와 폴더 구조를 볼 수 있습니다.

쿼리를 저장하려면 logs:PutQueryDefinition 권한이 있는 역할에 로그인해야 합니다. 저장된 쿼리의 목록을 보려면 logs:DescribeQueryDefinitions 권한이 있는 역할에 로그인해야 합니다.

Console

쿼리를 저장하려면

1. https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.

2. 탐색 창에서 로그를 선택한 다음, 로그 인사이트를 선택합니다.

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. 쿼리에 사용되는 파라미터를 정의합니다. 각 자리 표시자 파라미터에 대해 다음을 지정합니다.

      • 이름: 자리 표시자 이름과 정확히 일치해야 합니다(예: , logLevelapplicationName).

      • 기본값(선택 사항): 파라미터 값이 제공되지 않은 경우 사용할 값입니다.

      • 설명(선택 사항): 파라미터의 용도를 설명합니다.

   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. https://console.aws.amazon.com/cloudwatch/에서 CloudWatch 콘솔을 엽니다.

2. 탐색 창에서 로그를 선택한 다음, 로그 인사이트를 선택합니다.

3. 오른쪽에서 쿼리를 선택합니다.

4. 저장된 쿼리 목록에서 쿼리를 선택합니다. 쿼리 텍스트가 쿼리 편집기에 나타납니다.

5. (선택 사항) 파라미터와 함께 쿼리를 사용하려면:

   1. 저장된 쿼리 사이드 패널에서 쿼리 이름 옆에 있는 + 아이콘을 선택합니다.

   2. 파라미터가 있는 쿼리는 쿼리 편집기에 나타납니다. 예를 들어 옆에 있는 + 아이콘을 선택하면 ErrorsByLevel쿼리 편집기가 다음과 같이 채워집니다. $ErrorsByLevel(level=, applicationName=)

   3. 파라미터 값(레벨, applicationName)을 입력하고 쿼리를 실행합니다. 예: $ErrorsByLevel(level= "ERROR", applicationName= "OrderService")

6. 실행을 선택합니다.

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를 호출합니다.

{
  "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 및 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

할당량 및 오류 처리

확장된 쿼리 문자열은 10,000자를 초과할 수 없습니다. 파라미터 이름은 문자 또는 밑줄로 시작해야 합니다. 저장된 쿼리는 다른 저장된 쿼리를 참조할 수 없습니다(중첩된 호출은 지원되지 않음).