로그 쿼리 작성

이 페이지에서는 Google Cloud Console 로그 탐색기에서 쿼리를 작성하여 검색, 조정, 분석하는 방법을 설명합니다.

시작하기 전에

Amazon Web Services(AWS)에서 Logging으로 로그를 전송하는 경우가 아니면 작업공간이 없어도 Logging을 사용할 수 있습니다.

로그 탐색기는 단일 Google Cloud 프로젝트의 로그를 표시합니다. 작업공간을 사용하는 경우 Logging에서 모니터링되는 프로젝트의 로그를 합치지 않으므로 로그를 볼 특정 프로젝트를 선택해야 합니다.

작업공간과 AWS를 사용하는 경우 AWS 커넥터 프로젝트를 선택하여 AWS 로그를 확인합니다.

시작하기

로그 탐색기로 이동하려면 다음 안내를 따르세요.

  1. Google Cloud 탐색 메뉴로 이동하여 Logging > 로그 탐색기를 차례로 선택합니다.
    로그 탐색기로 이동
  2. Google Cloud 프로젝트를 선택합니다.
  3. 업그레이드 메뉴에서 기존 로그 뷰어로그 탐색기로 전환합니다.

이제 로그 탐색기가 표시됩니다.

쿼리 빌드

쿼리 빌더 창에서는 여러 가지 방법으로 로그를 검색 할 수 있습니다.

  1. 쿼리 빌더 드롭다운 메뉴
  2. 쿼리 빌더 언어를 사용하는 쿼리
  3. 최근, 저장됨, 추천 쿼리 탭

query-builder-pane

다음 섹션에서는 쿼리를 빌드하고 실행하여 로그를 검색하는 방법을 설명합니다.

쿼리 빌더 드롭다운 메뉴

드롭다운 메뉴를 사용하면 쿼리 빌더에 쿼리 매개변수를 추가할 수 있습니다. 드롭다운 메뉴를 사용하여 리소스, 로그 이름, 로그 심각도, 시간 범위를 선택할 수 있습니다. 이 옵션은 모든 Google Cloud의 작업 제품군 로그의 LogEntry 필드에 해당합니다.

쿼리 빌더 드롭다운 메뉴

  • 리소스: resource.type을 지정할 수 있습니다. 한 번에 하나의 리소스를 선택하여 쿼리 빌더에 추가할 수 있습니다. 항목은 논리 연산자 AND를 사용합니다.
  • 로그 이름: 로그 이름을 지정할 수 있습니다. 여러 로그 이름을 한 번에 선택하여 쿼리 빌더에 추가할 수 있습니다. 여러 항목을 선택할 때 논리 연산자 OR를 사용합니다.
  • 심각도: [severity][severity]를 지정할 수 있습니다. 여러 심각도 수준을 한 번에 선택하여 쿼리 빌더에 추가할 수 있습니다. 여러 항목을 선택할 때 논리 연산자 OR를 사용합니다.

검색 매개변수 메뉴를 사용하려면 매개변수를 확장하고 한 개 또는 여러 개의 매개변수를 선택한 다음 추가를 클릭합니다.

쿼리를 빌드한 후 쿼리 실행을 클릭하여 원하는 로그 항목을 검색합니다.

시간 제한이 있는 쿼리

시간을 기준으로 로그를 쿼리하는 방법에는 두 가지가 있습니다.

  1. 타임 스탬프 표현식을 사용하여 쿼리
  2. 시간 범위 선택기를 사용하여 쿼리

    로그 탐색기는 시간을 기준으로 필터링하는 두 가지 방법을 보여줍니다.

타임스탬프가 있는 쿼리의 경우 시간 범위 선택기가 비활성화되고 쿼리는 시간 범위 제한으로 타임스탬프 표현식을 사용합니다. 쿼리가 타임스탬프 표현식을 사용하지 않는 경우 쿼리는 시간 범위 선택기를 시간 범위 제한으로 사용합니다.

쿼리 빌더 언어를 사용하는 쿼리

쿼리 빌더 언어를 사용하여 Cloud Logging 쿼리 빌더 창과 Logging API 또는 명령줄 인터페이스에서 쿼리를 빌드할 수 있습니다.

자세한 내용은 쿼리 빌더 언어를 참조하세요.

다음은 쿼리를 최적화하기 위한 몇 가지 제안사항입니다.

쿼리 최적화

보다 효율적으로 로그 항목을 찾으려면 다음 안내를 따르세요.

  • 색인이 지정된 필드를 사용하여 검색합니다.
  • 검색되어야 하는 로그 항목의 개수를 최소화합니다.

색인이 지정된 필드 사용

색인을 활용하려면 등호 연산자를 사용하여 색인이 지정된 필드에 정확한 값을 지정합니다. 하위 문자열 일치를 사용하지 마세요.

다음과 같은 LogEntry 필드에 색인이 지정되어 있습니다.

다음 섹션에서는 이러한 색인이 지정된 필드를 사용해 쿼리할 로그 항목 수를 최소화하는 방법을 설명합니다.

로그 항목 빨리 찾기

로그 수, 로그 항목 수, 검색 시간 범위를 제한하면 더 빠르게 검색할 수 있습니다. 이 세 가지 조건을 모두 줄이면 더 좋습니다.

예: 올바른 로그 이름 사용

관심 있는 로그 항목이 포함된 로그를 지정하세요. 로그 항목 중 하나를 검사하여 실제 로그 이름을 파악하세요. 예를 들어 로그 탐색기에 Compute Engine 섹션에 'activity_log'라는 로그가 있다고 표시됩니다. 활동 로그 항목을 자세히 살펴보면 실제 로그 이름은 'compute.googleapis.com/activity_log'입니다.

다음 비교는 잘못되었습니다. 잘못된 로그 이름을 사용하고 있기 때문에 어떤 것과도 일치하지 않습니다.

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

다음 비교는 올바릅니다. 이 비교는 활동 로그에서 로그 항목을 선택합니다. 다음과 같이 로그 이름에 URL 인코딩을 수행해야 합니다.

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

예: 올바른 로그 항목의 선택

원하는 로그 항목이 특정 VM 인스턴스에서 온다는 것을 알고 있으면 해당 인스턴스를 지정하세요. 검색하려는 로그 항목 중 하나를 검사하여 라벨 이름이 올바른지 확인하세요. 다음 예시에서 instance_id는 색인이 지정된 라벨 중 하나입니다.

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

리소스 유형에 값을 지정해야 합니다. 그렇지 않으면 instance_id 비교 시 색인이 사용되지 않습니다.

예: 올바른 기간 선택

검색할 기간을 지정해야 합니다. RFC 3339 형식의 유용한 타임스탬프를 결정하는 빠른 방법은 Gnu/Linux date 명령어를 사용하는 것입니다.

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

다음 쿼리에 이 타임스탬프 값을 사용하세요. Logging에서 사용할 수 있는 타임스탬프를 만들려면 날짜와 시간 사이의 공백을 문자 T로 바꿉니다.

예를 들어 최근 3시간 범위 내에서 검색하려면 다음을 사용하세요.

    timestamp >= "2016-06-27T14:40:00-04:00"

또 다른 예로 3시간에서 5시간 전 사이의 범위에서 검색하려면 다음을 사용하세요.

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

타임스탬프를 사용하는 그 밖의 예시는 이 페이지의 임시 필드 색인을 참조하세요.

전체 검색과 하위 문자열 검색의 최소화

로깅 쿼리를 입력할 때 간편한 방법을 찾으려고 시도하지 마세요.

예: 색인이 지정된 필드에 하위 문자열을 사용하지 마세요.

Apache2 웹 서버에서 로그 항목을 검색한다고 가정해 보겠습니다. 그리고 Apache 로그의 이름이 apache-accessapache-error라는 것을 알고 있다고 가정하겠습니다. 어떻게 해야 할까요?

  • 입력 시간을 절약하기 위해 하위 문자열 일치를 사용하지 마세요.

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • 색인이 지정된 필드를 검색할 때는 100% 일치를 사용하세요.

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

하위 문자열 검색을 수행하면 색인이 지정된 필드로 인해 검색 속도가 크게 저하됩니다.

예: 전체 검색을 사용하지 마세요.

페이로드에 'Hello, Kitty'가 포함된 로그 항목을 검색하려고 합니다.

  • 전체 검색을 사용하지 마세요. 한 가지 이유는 전체 검색이 모두 하위 문자열 검색이기 때문입니다.

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • 하위 문자열 검색을 유지해야 하더라도 검색 대상을 단일 필드로 제한하세요.

        textPayload:"Hello, Kitty"
    
  • 가능하다면 동일성 테스트를 사용하세요.

        textPayload = "Hello, Kitty"
    
  • 로그 항목에 구조화된 페이로드가 있는 경우 페이로드의 각 필드를 참조하세요.

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • 색인이 지정된 필드를 사용하여 검색 범위를 제한하세요.

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

검색 예

아래의 로그 항목은 검색어 상자의 쿼리와 일치하는 로그 항목입니다. 이동할 날짜 메뉴에 값이 포함되어 있으면 화면이 그 시점까지 스크롤됩니다. 다음은 몇 가지 쿼리 예시입니다.

resource.type=gae_app

리소스 로그 메뉴에서 GAE 애플리케이션(모든 모듈 IDs)을, 로그 이름 메뉴에서 모든 로그를 선택한 경우 기본 쿼리 인터페이스에 표시되는 로그 항목과 동일한 로그 항목을 찾습니다. 리소스 유형 목록은 모니터링 리소스 목록을 참조하세요.

입력과 동시에 로그 탐색기는 resource.type과 같은 전체 필드 이름을 제안합니다.

resource.type=gae_app AND logName:request_log

request_log를 포함하는 로그 이름에서 App Engine 앱의 로그 항목을 찾습니다. 다음과 같은 사항에 유의하세요.

  • = 연산자는 100% 동일입니다. 리소스 유형은 대소문자에 관계없이 정확히 "gae_app"이어야 합니다.
  • : 연산자는 'has'를 의미합니다. logName 필드에는 대소문자에 관계없이 request_log가 포함되어야 합니다. 실제 로그 이름은 훨씬 더 깁니다. :을 사용하면 검색 속도가 더 느려질 것입니다.
  • 비교가 2개인 경우 AND로 결합합니다. OR을 사용해도 되지만 연산자를 빼버리면 AND로 간주됩니다.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Compute Engine VM 인스턴스와 AWS EC2 VM 인스턴스의 두 가지 리소스 유형 중 하나가 있는 로그 항목을 찾습니다. 로그 항목의 severity는 최소한 ERROR여야 합니다. 이는 기본 쿼리 인터페이스의 심각도 메뉴에서 오류를 선택하는 것과 같습니다. 기본 쿼리 인터페이스에는 여러 리소스 유형의 로그가 표시되지 않습니다.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

[PROJECT_ID] 프로젝트에서 모든 관리자 활동 감사 로그 항목을 찾습니다. 한 프로젝트 내의 감사 로그는 모두 동일한 로그 이름을 사용하지만 리소스 유형은 서로 다릅니다. 로그 ID cloudaudit.googleapis.com/activity는 로그 이름에서 URL로 인코딩되어야 합니다. 비교 시 등호를 사용하면 검색 속도가 빨라집니다. 자세한 내용은 감사 로그 이해를 참조하세요.

unicorn

특정 필드에서 대소문자에 관계없이 unicorn이 포함된 로그 항목을 찾습니다. 필드 비교의 일부가 아닌 검색어는 '모든 필드' 쿼리입니다.

unicorn phoenix

일부 필드에는 unicorn, 일부 필드에는 phoenix가 포함된 로그 항목을 찾습니다.

textPayload:(unicorn phoenix)

textPayload 필드에 순서에 관계없이 unicornphoenix이 포함된 로그 항목을 찾습니다. 이때 AND는 두 단어 사이에 내포되어 있습니다.

textPayload:"unicorn phoenix"

textPayload 필드에 "unicorn phoenix"라는 문자열이 포함된 로그 항목을 찾습니다. 이는 기본 쿼리 인터페이스와 동일합니다.

NOT textPayload: "unicorn phoenix"

textPayload 필드에 "unicorn phoenix" 문자열이 포함되지 않은 로그 항목을 찾습니다. 이 유형의 쿼리는 원치 않는 로그 항목을 줄입니다.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

30분 시간 범위 내의 로그 항목을 찾습니다.

저장된 쿼리

쿼리 빌더 창에는 저장된 쿼리에 액세스 할 수 있는 저장됨 탭이 있습니다.

저장된 쿼리 목록

저장된 쿼리를 사용하면 쿼리 표현식을 저장하여 로그를 일관되고 효율적으로 탐색할 수 있습니다.

쿼리 빌더 창에서 빌드한 쿼리를 저장하려면 다음 안내를 따르세요.

  1. 쿼리 빌더 창에서 저장을 클릭합니다. 쿼리 저장 대화상자가 열리고 쿼리 필드에 쿼리 표현식이 표시됩니다.

  2. 쿼리의 이름을 추가합니다.

    이름은 64자로 제한됩니다.

  3. 선택사항: 쿼리에 요약 필드를 추가하려면 요약 필드 포함으로 전환합니다.

  4. 선택사항: 쿼리 설명을 추가합니다.

    설명은 1,000자로 제한됩니다. 민감한 정보를 포함하면 안 됩니다.

  5. 대화상자에서 쿼리 저장을 클릭합니다.

저장된 쿼리는 쿼리 빌더 창의 저장됨 탭 아래 목록에 표시됩니다.

저장된 쿼리를 실행하려면 쿼리 실행을 클릭합니다.

최근 쿼리

쿼리 빌더 창에는 최근 탭이 있습니다. 쿼리를 실행하면 쿼리가 최근 쿼리 목록에 추가되며, 여기에는 30일 동안 발생한 10,000개의 고유한 쿼리가 포함됩니다.

최근 탭에는 최근 쿼리가 표시됩니다.

최근 쿼리를 보려면 쿼리 빌더 창에서 최근 탭을 선택합니다. 최근 탭에서는 다음 옵션을 사용할 수 있습니다.

  • 실행. 쿼리를 실행합니다.
  • 옵션 더보기 . 쿼리 실행 옵션과 함께 쿼리 매개변수를 보거나 저장된 쿼리 목록에 저장할 수 있습니다. 쿼리를 직접 선택하여 이러한 옵션을 가져올 수도 있습니다.

    쿼리를 실행하려면 실행을 선택합니다.

    쿼리를 저장하려면 다른 이름으로 저장을 선택하고 다음 필드를 작성합니다.

    • 이름(필수사항): 이름을 입력합니다.
    • 설명(선택사항): 쿼리의 목적을 식별하는 데 도움이 되는 설명을 제공합니다.
    • 요약 필드 포함(선택사항): 요약 필드 포함을 사용 설정하고 표시할 필드를 입력합니다.
    • 요약 필드 자르기(선택사항): 요약 필드 자르기를 사용 설정하고 잘라낼 문자 수와 자르기가 필드의 시작 부분에서 발생할지 끝부분에서 발생할지 여부를 선택합니다.

    쿼리 저장을 선택합니다. 이제 저장된 쿼리 목록에서 쿼리를 사용할 수 있습니다.

최근 쿼리를 필터링할 수도 있습니다. 필터와 쿼리의 표현식에 있는 텍스트가 일치합니다.

추천 쿼리

Logging은 사용 중인 Google Cloud 제품에 대한 이해를 기반으로 추천 쿼리를 생성합니다. 문제를 정확하게 식별하고 시스템의 전체 상태에 대해 유용한 정보를 제공하는 데 도움이 되는 쿼리를 제안합니다. 예를 들어 Google Kubernetes Engine을 사용하는 경우 Logging이 컨테이너의 모든 오류 로그를 찾아내는 쿼리를 추천할 수 있습니다.

쿼리 빌더 창에서 추천 쿼리를 보고 실행하려면 다음을 수행합니다.

  1. 추천 탭을 클릭합니다.

    쿼리 모음을 보여주는 추천 검색어 탭

  2. 추천 쿼리에 대한 설명을 검토합니다.

  3. 추천 쿼리에 대한 세부정보를 검토하려면 다음 작업 중 하나를 수행하세요.

    a. 행을 클릭합니다.

    b. 더보기 를 클릭하고 새로 만들기를 선택합니다.

  4. 쿼리 빌더 창에 쿼리와 이를 실행 또는 저장할 수 있는 옵션이 표시됩니다.

    a. 쿼리를 저장하려면 저장을 클릭합니다. 저장됨 목록에 쿼리가 표시됩니다. 여기에서 나중에 쿼리를 실행하도록 선택할 수 있습니다.

    b. 쿼리를 실행하려면 실행을 클릭합니다. 쿼리 빌더의 쿼리 미리보기에 쿼리가 표시됩니다.

  5. 쿼리를 검토한 후 쿼리 실행을 클릭합니다. 추천 쿼리의 결과가 쿼리 결과에 표시됩니다.

추천 쿼리는 Google Cloud 프로젝트 컨텍스트에 따라 동적으로 생성됩니다. 연속으로 페이지를 로드하면 동일한 쿼리가 동일한 순서로 표시되지 않을 수 있습니다. 이는 정상적인 동작입니다.

문제 해결

따옴표로 묶지 않은 텍스트

공백이나 일부 특수문자가 포함되어 있지 않은 텍스트 문자열은 따옴표로 묶지 않아도 됩니다. 이를 따옴표로 묶지 않은 텍스트라고 하며, 앞의 예시에서의 ERROR와 같은 단어를 예로 들 수 있습니다. 문자열 "v1.compute.instances.insert"는 마침표를 포함하고 있으므로 따옴표로 묶였습니다. 문자열 내에 따옴표를 포함하려면 따옴표 앞에 백슬래시를 사용합니다.

구문 문제

쿼리 빌더 언어를 사용하는 데 문제가 발생하는 경우 다음을 확인하세요.

  • 쿼리가 구문 규칙을 준수하며 괄호와 따옴표가 제대로 되어 있습니다. 쿼리에 주석을 추가할 수 없습니다.

  • 로그 항목 필드 이름의 철자가 올바릅니다.

  • 부울 연산이 대문자로 되어 있습니다(AND, OR, NOT).

  • 전역 제한 형태의 부울 표현식 또는 비교의 오른쪽에 있는 부울 표현식은 괄호로 묶어서 명확하게 구분하는 것이 좋습니다. 예를 들어 아래의 쿼리 2개는 같아 보이지만 다릅니다.

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • 따옴표로 묶여 있지 않은 텍스트에 특수문자가 있어서는 안 됩니다. 확실하지 않다면 큰따옴표를 추가하세요. 예를 들어 아래의 첫 번째 비교는 하위 문자열 연산자(:)가 삽입되어 있으므로 잘못되었습니다. 비교는 따옴표로 묶어서 작성해야 합니다.

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • gcloud logging에서는 쿼리를 큰따옴표로 묶어야 합니다. gcloud logging 명령어를 사용하여 특수문자를 이스케이프하는 큰 따옴표를 사용하려면 전체 쿼리를 작은따옴표로 묶으세요.

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
    
  • 타임스탬프가 포함된 쿼리를 빌드하는 경우에는 검색어 상자 아래에 있는 시간 범위 선택기에서 제한 없음을 선택해야 합니다.