gcloud CLI를 사용하여 로그 항목 쓰기 및 쿼리

gcloud CLI를 사용하여 로그 항목 쓰기 및 쿼리

이 문서에서는 Cloud Logging의 몇 가지 기능을 소개하고 다음을 수행하는 방법을 보여줍니다.

• Google Cloud CLI를 사용하여 로그 항목 쓰기
• gcloud CLI를 사용하여 로그 항목 나열
• Logging API를 사용하여 로그 항목 나열
• 로그 탐색기를 사용하여 로그 항목 보기 및 쿼리

시작하기 전에

이 빠른 시작을 완료하려면 결제가 사용 설정된 Google Cloud 프로젝트가 있어야 합니다. Google Cloud 프로젝트가 없거나 Google Cloud 프로젝트에 결제가 사용 설정되어 있지 않으면 다음을 수행하세요.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

시작하기

gcloud CLI에는 Cloud Logging API에 명령줄 인터페이스를 제공하는 명령어 그룹인 gcloud logging이 있습니다.

이 빠른 시작에서는 gcloud CLI 명령어에 Cloud Shell 환경 또는 Compute Engine 가상 머신(VM) 인스턴스를 사용할 수 있습니다. gcloud CLI는 Cloud Shell 환경에 사전 설치되어 있습니다.

Cloud Shell

gcloud CLI가 올바른 Google Cloud 프로젝트를 사용하도록 구성되었는지 확인합니다.

1. Google Cloud 콘솔에서 Cloud Shell 활성화를 클릭합니다.

   

   Cloud Shell이 창에서 열리고 환영 메시지가 표시됩니다. 시작 메시지에 구성된 프로젝트 ID가 표시됩니다.

   

2. 환영 메시지에 표시된 프로젝트 대신 다른 Google Cloud 프로젝트를 사용하려면 PROJECT_ID를 프로젝트 ID로 바꾼 후 다음 명령어를 실행합니다.

      gcloud config set project PROJECT_ID
      

   프로젝트 ID를 가져오려면 프로젝트 식별을 참조하세요.

VM 인스턴스

Google Cloud 콘솔에서 Compute Engine VM 인스턴스를 만들려면 다음 단계를 수행합니다.

1. Google Cloud 콘솔에서 Compute Engine을 선택한 후 VM 인스턴스를 선택합니다.

2. 인스턴스 만들기를 선택합니다.

3. 액세스 범위의 ID 및 API 액세스에서 각 API에 액세스 설정을 선택합니다.

4. API를 스크롤해서 Stackdriver Logging API를 찾습니다. 액세스를 전체로 전환합니다.

5. 다른 모든 설정은 기본값으로 두고 만들기를 클릭합니다. VM 인스턴스를 사용할 준비가 되었습니다.

6. SSH를 클릭하여 VM 인스턴스 셸에 연결합니다. 잠시 후 Debian GNU/Linux 셸이 창에서 열리고 환영 메시지가 표시됩니다.

7. 다음 명령어를 실행하여 gcloud CLI가 Compute Engine 프로젝트에 구성되어 있는지 확인합니다.

   gcloud config list
   

8. 다른 Google Cloud 프로젝트를 사용하려면 PROJECT_ID를 프로젝트 ID로 바꾼 후에 다음 명령어를 실행합니다.

     gcloud config set project PROJECT_ID
     

   프로젝트 ID를 가져오려면 프로젝트 식별을 참조하세요.

gcloud CLI를 사용하여 로그 항목 쓰기

Logging은 구조화된 데이터와 구조화되지 않은 데이터가 있는 로그 항목을 지원합니다. 구조화된 데이터는 JSON 데이터 구조로 구성됩니다(예: {"weather": "partly cloudy"}). 구조화되지 않은 데이터는 문자열입니다(예: "A simple entry"). 다음 단계에서는 gcloud CLI를 사용하여 구조화되지 않은 데이터가 있는 로그 항목과 구조화된 데이터가 있는 로그 항목을 작성합니다.

1. 구조화되지 않은 데이터가 있는 로그 항목을 로그 my-test-log에 작성하려면 다음을 실행합니다.

   gcloud logging write my-test-log "A simple entry."
   

   이 명령어가 완료되면 Created log entry라는 메시지가 표시됩니다.

2. 구조화된 데이터가 있는 로그 항목을 로그 my-test-log에 작성하려면 다음을 실행합니다.

   gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
   

   구조화된 데이터가 있는 로그 항목을 작성할 때는 --payload-type=json을 포함해야 합니다. 이 필드를 생략하면 Logging은 페이로드를 구조화되지 않은 데이터로 해석합니다.

로그 my-test-log가 없으면 로그 항목이 수신될 때 Logging이 해당 로그를 만듭니다.

gcloud CLI를 사용하여 로그 항목 나열

Logging에서 로그 항목을 검색하고 gcloud CLI를 사용하여 표시할 수 있습니다. 예를 들어 리소스 유형이 globalglobal인 로그 항목을 검색하여 표시하려면 다음 명령어를 실행합니다.

gcloud logging read "resource.type=global"

이 명령어는 다음과 유사한 결과를 반환합니다.

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

API 탐색기를 사용하여 로그 항목 나열

코드를 작성하지 않고 Logging API 메서드를 실행하려면 API 탐색기 사용을 참조하세요. Logging의 로그 항목 목록을 읽으려면 다음 안내를 따르세요.

1. entries.list API 메서드에 대한 API 참조 페이지로 이동합니다.

   entries.list API 페이지로 이동

2. API 명령어를 구성하고 실행합니다.

   1. 다음 텍스트에서 PROJECT_ID를 바꿉니다.

      "resourceNames": [
      "projects/PROJECT_ID"
      ],
      "filter": "resource.type=global",
      "orderBy": "timestamp desc"
      

   2. 이전 단계에서 업데이트한 텍스트를 복사하여 API 탐색기의 요청 본문 필드에 붙여넣습니다.

   3. 실행을 클릭합니다.

   이 메서드는 다음과 비슷한 응답을 반환합니다.

   {
     "entries": [
       {
         "textPayload": "A simple entry",
         "insertId": "vd4m1if7h7u1a",
         "resource": {
           "type": "global",
           "labels": {
             "project_id": "myloggingproject"
           }
         },
         "timestamp": "2018-11-01T18:39:19.718100792Z",
         "logName": "projects/myloggingproject/logs/my-test-log",
         "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
       },
       {
         "insertId": "jpj9zjf73t1mn",
         "jsonPayload": {
           "message": "My second entry",
           "weather": "partly cloudy"
         },
         "resource": {
           "type": "global",
           "labels": {
             "project_id": "myloggingproject"
           }
         },
         "timestamp": "2018-11-01T18:39:31.114507977Z",
         "logName": "projects/myloggingproject/logs/my-test-log",
         "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
       }
     ]
   }
   

로그 탐색기에서 로그 항목 보기

Google Cloud 콘솔에서 로그 항목을 보려면 로그 탐색기를 사용합니다. 대부분의 Google Cloud 프로젝트에는 많은 로그가 저장되며, 쿼리를 작성하여 특정 로그 항목을 선택할 수 있습니다.

로그 탐색기를 사용하여 작성한 로그 항목을 보려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

   로그 탐색기로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

   Google Cloud 탐색 메뉴에서 Google Cloud 프로젝트가 선택되어 있는지 확인합니다. 필요한 경우 Google Cloud 프로젝트 드롭다운 목록을 사용하여 Google Cloud 프로젝트를 선택합니다.

2. 리소스 메뉴에서 전역을 선택합니다.

   전체 메뉴 옵션이 표시되지 않거나 로그 항목이 표시되지 않으면 몇 분 후에 페이지를 새로고침합니다. Logging에서 로그 항목을 수신하는 데 몇 분이 걸릴 수 있습니다.

3. 로그 항목의 세부정보를 보려면 메뉴를 클릭합니다.

   첫 번째 로그 항목의 데이터는 textPayload에 저장되어 있습니다. 두 번째 로그 항목에는 jsonPayload에 저장된 구조화된 데이터가 포함되어 있습니다. 구조화된 페이로드에는 message 및 weather 키가 포함되어 있습니다.

   참고: message가 구조화된 로그 항목의 키인 경우 Logging은 해당 로그 항목이 펼쳐져 있지 않을 때 이를 로그 항목 요약으로 사용합니다.

로그 항목의 데이터 형식에 대한 자세한 내용은 LogEntry 유형을 참조하세요.

로그 탐색기에서 로그 항목 쿼리

쿼리 편집기를 사용하고 키 및 값(구조화된 로그의 경우)을 기준으로 하여 로그 항목을 필터링할 수 있습니다. 예를 들어 simple이라는 텍스트가 포함된 모든 로그 항목을 표시하려면 다음을 수행합니다.

1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

   로그 탐색기로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

2. 리소스 메뉴에서 전역을 선택합니다.

3. 쿼리 편집기에서 simple 문자열을 따옴표로 묶어 입력합니다. 그러면 로그 화면에 로그 항목 A simple entry.만 표시됩니다.

4. 로그를 확인한 후 추가한 쿼리 문자열을 삭제하고 쿼리 실행을 클릭합니다. 그러면 두 로그 항목이 모두 화면에 다시 나타납니다.

value 필드에 partly가 포함되어 있고 weather 키를 가진 구조화된 데이터가 있는 모든 로그 항목을 표시하려면 다음을 수행합니다.

1. 쿼리 편집기에는 resource.type="global" 줄이 포함되어 있습니다. 다음 명령어를 입력합니다.

   jsonPayload.weather:partly
   

2. 쿼리 실행을 클릭합니다. 그러면 단일 로그 항목 My second entry가 표시됩니다.

로그 탐색기는 저장, 추천, 최근 쿼리도 제공합니다. 쿼리에 대한 자세한 내용은 로그 탐색기에서 쿼리 빌드를 참조하세요.

샘플 쿼리는 로그 탐색기를 사용하는 샘플 쿼리를 참조하세요.

문제 해결하기

• 입력 오류가 있거나 필드 이름을 알 수 없으면 gcloud CLI 명령어가 유효하지 않은 인수 메시지와 함께 완료됩니다. 예를 들어 resource.type에서 점을 빼면 다음과 같은 오류가 발생합니다.

   ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
  

• Cloud Logging에 필요한 액세스 권한이 부여되지 않았으면 gcloud CLI 명령어가 권한 거부됨 메시지와 함께 완료됩니다. 예를 들어 Compute Engine VM 인스턴스가 기본 API 설정으로 구성되면 list 명령어가 권한 거부됨 오류와 함께 완료됩니다.

   ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
  

  이 문제를 수정하려면 다음을 수행하여 Compute Engine VM 인스턴스 권한을 수정해 Cloud Logging에 읽기 권한을 부여합니다.

  1. VM 인스턴스의 VM 인스턴스 세부정보 페이지로 이동합니다. 중지를 클릭합니다. 이 작업을 완료하는 데 1~2분 정도 걸릴 수 있습니다.
  2. 구성을 수정하려면 수정을 클릭합니다.
  3. 헤더 Cloud API 액세스 범위를 검색하고 세부정보를 클릭하여 각 API의 설정을 표시합니다. 항목을 Cloud Logging API에서 전체로 변경하고 저장을 클릭합니다.
  4. VM 인스턴스를 다시 시작하려면 시작을 클릭합니다. 잠시 후에 VM을 사용할 준비가 됩니다.

• API 탐색기에서 명령어를 완료할 수 없거나 추가 승인이 필요하면 메시지 또는 오류 코드가 표시됩니다.

  • 200 응답 코드 및 항목 없음: nextPageToken 메시지는 API 탐색기가 검색을 완료할 수 있는 시간이 부족했음을 나타냅니다. 요청에 pageToken을 추가하고 값을 nextPageToken을 사용하여 지정된 값과 동일한 값으로 설정한 후에 명령어를 다시 시도합니다.
  • 400 응답 코드: 쿼리 값이 잘못되었습니다. 예를 들어 global을 gloobal로 잘못 입력하면 Unsupported resource type: gloobal이라는 메시지가 표시됩니다.
  • 404 응답 코드: 프로젝트 ID가 잘못되었습니다. 프로젝트 식별자의 철자를 검사합니다.
  • 본인의 Google 계정으로 로그인하여 API 탐색기가 내 계정에 액세스하도록 허용하라는 메시지가 표시될 수 있습니다.

삭제

이 페이지에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 단계를 수행합니다.

1. (선택사항) 만든 로그 항목을 삭제하려면 다음 gcloud 명령어를 실행합니다.

   gcloud logging logs delete my-test-log
   

   로그 항목을 삭제하지 않으면 로그 항목이 만료되어 삭제됩니다. 보관에 대한 자세한 내용은 할당량 및 한도를 참조하세요.

다음 단계

• Logging 명령줄 인터페이스에 대한 자세한 내용은 gcloud logging 명령어 그룹의 참조 페이지를 확인하세요.
• Logging API 문서는 Cloud Logging API를 참조하세요.
• 로그 탐색기에 대한 자세한 내용은 로그 탐색기 사용을 참조하세요.
• Logging에서 VM 인스턴스의 로그 항목을 수집하는 방법은 Google Cloud Observability 에이전트를 참조하세요.