Cloud Logging으로 마이그레이션

2세대 런타임의 로깅은 1세대 런타임과 다릅니다. 최신 런타임으로 업그레이드할 때 가장 큰 변경사항 중 하나는 App Engine과 사전 통합된 로깅이 2세대 런타임에서 지원되지 않고 로그의 상관관계가 자동으로 지정되지 않는다는 것입니다. 2세대 런타임으로 마이그레이션하는 경우 Cloud Logging 클라이언트 라이브러리를 사용해야 합니다.

이 가이드에서는 Cloud Logging을 사용하여 앱을 업데이트하고 App Engine의 로깅 통합에서 사용할 수 있는 것과 거의 동일한 필터링 및 로그 상관관계 기능을 달성하는 방법을 설명합니다.

Cloud Logging은 스토리지, 검색, 분석, 모니터링을 지원을 갖춘 실시간 로그 관리 시스템입니다. Cloud Logging은 Google Cloud 리소스 로그를 자동으로 수집합니다. 애플리케이션, 온프레미스 리소스, 다른 클라우드 제공업체의 리소스에서 로그를 수집할 수도 있습니다.

주요 차이점

다음 표에서는 1세대 런타임과 2세대 런타임 로깅 간의 차이점을 설명합니다.

	1세대 런타임	2세대 런타임
요청 및 앱 로그(애플리케이션 로그라고도 함)	App Engine은 모든 앱 로그를 요청 로그 내에 삽입합니다. 1세대 런타임의 로깅은 요청 로그의 `protoPayload.line.logMessage` 필드를 사용하여 앱 로그를 삽입합니다.	App Engine은 연결된 요청 로그 내에 앱 로그를 삽입하지 않습니다. App Engine은 요청 로그에서 `protoPayload.line` 속성을 생략합니다. 앱 로그는 로깅 메서드에 따라 라우팅됩니다. `stdout` 및 `stderr`: `print()`와 같은 로그를 `logs/stdout` 또는 `logs/stderr`로 라우팅합니다. Cloud Logging 클라이언트를 설정한 후 Python 로깅 모듈 : `logging.info()` 및 `logging.error()`와 같이 Python 루트 로깅 모듈로 작성된 모든 로그를 `logs/python`에 라우팅합니다. Python용 Cloud Logging 클라이언트 라이브러리에 상관관계가 설정되지 않았으면 Python 루트 로깅 모듈이 기본적으로 `logs/stderr`로 라우팅됩니다.
로그 탐색기에서 로그 보기	1세대 런타임에는 하나의 로그 유형(`appengine.googleapis.com/request_log`)만 포함됩니다. 요청 로그를 펼치면 그 아래에 중첩된 앱 로그를 볼 수 있습니다.	2세대 런타임에는 `appengine.googleapis.com/request_log`, `stdout`, `stderr`, `logs/python` 및 그 외 다수의 요청 로그와 같은 여러 로그 유형의 로그가 포함됩니다. 이는 앱이 로그를 내보내는 방법에 따라 달라집니다. Google 내부 로그는 `/var/log/google_init.log`에서도 사용할 수 있습니다. 앱 로그는 자동으로 요청 로그와 상관관계가 지정되지 않으므로 로그 탐색기에서 요청 및 앱 로그의 중첩된 뷰를 표시하려면 추가 단계가 필요합니다. 자세한 내용은 요청 로그와 앱 로그의 상관관계 및 로그 탐색기에서 상관관계가 지정된 로그 보기를 참조하세요.
Cloud Trace 통합	지연 시간 데이터 수집을 위해 Cloud Trace와 자동으로 통합됩니다.	App Engine에서 지연 시간에 대한 데이터를 수집하려면 앱을 Cloud Trace와 수동으로 통합해야 합니다. 자세한 내용은 Cloud Trace 계측을 참조하세요.
오류 수준 상관관계	ERROR 심각도 수준으로 App Engine 요청 로그에 발생한 오류를 기록합니다. Error Reporting은 Error Reporting 대시보드에서 이러한 세부정보의 상관관계를 자동으로 지정합니다.	기본적으로 App Engine은 2세대 런타임에 Error Reporting을 통합하지 않습니다. Error Reporting과 로깅 통합을 설정하려면 클라이언트 라이브러리를 사용하여 앱 계측을 참조하세요.
심각도 수준	로그 탐색기는 심각도 수준을 요청 로그에 할당합니다. 심각도 수준은 요청 로그 항목과 관련된 모든 앱 로그 항목의 가장 높은 심각도를 반영합니다. 예를 들어 요청으로 인해 앱에 경고 로그 항목이 표시되면 로그 탐색기에서 요청 로그 항목 옆에 경고 아이콘이 표시됩니다. 요청 항목을 펼치면 요청 항목 내에 중첩된 경고 로그 항목이 표시됩니다.	기본적으로 모든 요청 로그의 심각도는 `DEFAULT` 또는 `INFO`입니다. 요청 로그가 앱 로그와 상관관계가 있고 로그 탐색기가 상관관계가 지정된 로그 보기로 구성된 경우에도 요청 로그에는 연결된 앱 로그의 심각도가 반영되지 않습니다.
Logservice API	Logservice API는 번들 서비스 SDK의 일부입니다.	번들 서비스 SDK에서 Logservice API가 삭제되었습니다. 자세한 내용은 사용 가능한 API 목록을 참조하세요.

마이그레이션을 시작하기 전에

앱이 포함된 프로젝트에서 Cloud Logging API를 사용 설정합니다.

API 사용 설정
앱에 로그를 작성할 권한이 있는지 확인합니다.

기본적으로 앱의 기본 서비스 계정에는 로그를 작성할 권한이 있습니다.

앱에서 다른 서비스 계정 또는 기본 서비스 계정의 권한을 변경한 경우 사용 중인 계정에 로그를 작성할 수 있는 logging.logEntries.create 권한이 있는지 확인하세요.
App Engine의 여러 유형의 로그를 숙지합니다.

마이그레이션 프로세스 개요

Cloud Logging을 사용하도록 앱을 마이그레이션하려면 다음 안내를 따르세요.

Cloud Logging용 Cloud 클라이언트 라이브러리 설치
Cloud Logging으로 로그 작성
요청 로그와 앱 로그의 상관관계
로그 보기
앱 테스트

Cloud Logging용 Cloud 클라이언트 라이브러리 설치

구성 파일을 설치 및 업데이트하려면 다음과 같이 requirements.txt 파일의 종속 항목 목록에 Cloud Logging용 Cloud 클라이언트 라이브러리를 추가합니다.

google-cloud-logging

표준 Python 로깅 모듈로 로그 작성

로그 항목을 작성하는 각 파일에서 다음을 수행합니다.

Cloud Logging 클라이언트 라이브러리를 가져옵니다.
Cloud Logging 클라이언트를 인스턴스화합니다.
Cloud Logging 클라이언트의 setup_logging() 메서드를 실행하여 기본 리스너를 Python 루트 로거의 로깅 핸들러로 연결합니다.

예를 들면 다음과 같습니다.

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

핸들러가 연결되면 INFO 수준 이상의 모든 로그가 애플리케이션에 표시되고 기본적으로 Logging으로 전송됩니다.

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

요청 로그와 앱 로그의 상관관계

요청 로그와 앱 로그의 자동 상관관계 지정 등 1세대 런타임에서 사용할 수 있는 일부 기능은 2세대 런타임에서 사용할 수 없습니다.

2세대 런타임을 사용하는 앱은 다음 방법 중 하나를 통해 1세대 런타임과 비슷한 중첩 로깅 동작을 달성할 수 있습니다.

애플리케이션에서 Cloud Logging 클라이언트를 설정하고 로그에 상관관계를 지정합니다.
stdout 및 stderr와 함께 trace 식별자를 사용합니다.

1세대 런타임과 2세대 런타임의 로깅 동작은 다음과 같은 점에서 차이가 있습니다.

1세대 런타임에서 App Engine은 요청을 처리할 때 내보낸 모든 앱 로그를 요청 로그의 protoPayload.line.logMessage 필드에 삽입합니다. 이러한 로그는 appengine.googleapis.com/request_log를 통해 로그 탐색기에 표시됩니다.

다음 이미지는 1세대 런타임에서 상관관계가 지정된 요청과 앱 로그를 보여줍니다.
2세대 런타임에서 App Engine은 요청 로그에서 protoPayload.line 속성을 생략합니다. 앱 로그의 콘텐츠는 로그 탐색기의 JSON 요청 로그 내에 없습니다. 각 앱 로그는 로그 탐색기에서 로그 이름과 별도로 표시됩니다.

다음 이미지는 2세대 런타임의 별도의 요청 로그와 앱 로그를 보여줍니다.

다음 섹션에서는 Cloud Logging 클라이언트 또는 stdout 및 stderr로 구조화된 로깅을 사용하여 로그에 상관관계를 지정하는 방법을 설명합니다.

Python 로깅 모듈 사용

Python 로깅 모듈에서 로깅된 앱 로그에 요청 상관관계를 추가하려면 Cloud Logging 클라이언트 라이브러리를 설정합니다.

애플리케이션 시작 시 client.setup_logging() 메서드를 실행하면 이 메서드는 trace 필드 및 HTTP 요청 세부정보를 logging.info(), logging.error() 등 Python logging 모듈에서 작성된 앱 로그에 추가합니다. 이러한 로그는 logs/python으로 라우팅됩니다.

또한 App Engine은 이 trace 필드를 연결된 요청 로그에 추가하므로 로그 탐색기에서 상관관계가 지정된 로그 항목을 볼 수 있습니다.

`stdout` 및 `stderr` 사용

stdout 및 stderr을 사용하여 로그 항목을 작성하면 해당 항목이 로그 탐색기에 표시됩니다. 하지만 필터링 및 요청 로그와의 상관관계를 사용 설정하려면 항목의 형식을 JSON 객체로 지정하고 특정 메타데이터를 제공해야 합니다. 이 접근방식에 대한 자세한 내용은 구조화된 로깅을 참조하세요. 구조화된 앱 로그의 경우 앱 로그의 항목과 요청 로그의 상관관계를 지정하려면 요청의 trace 식별자가 필요합니다. 안내에 따라 로그 메시지의 상관관계를 지정합니다.

X-Cloud-Trace-Context 요청 헤더에서 trace 식별자를 추출합니다.
구조화된 로그 항목에서 logging.googleapis.com/trace라는 필드에 ID를 작성합니다. X-Cloud-Trace-Context 헤더에 대한 자세한 내용은 요청을 강제로 추적을 참조하세요.

로그 보기

여러 가지 방법으로 앱 로그를 보고 로그를 요청할 수 있습니다.

Google Cloud 콘솔의 Cloud Logging에서 로그 탐색기를 사용합니다.
Google Cloud CLI를 사용하여 gcloud로 로그를 봅니다.
다양한 방법을 사용하여 프로그래매틱 방식으로 로그를 읽습니다.

로그 탐색기 사용

로그 탐색기를 사용하여 앱을 보고 로그를 요청할 수 있습니다.

Google Cloud 콘솔의 로그 탐색기로 이동합니다.

로그 탐색기로 이동
페이지 상단에서 기존 Google Cloud 프로젝트를 선택합니다.
리소스 유형에서 GAE 애플리케이션을 선택합니다.

App Engine 서비스, 버전, 기타 기준별로 로그 탐색기를 필터링할 수 있습니다. 로그에서 특정 항목을 검색할 수도 있습니다. 자세한 내용은 로그 탐색기 사용을 참조하세요.

간단한 텍스트 항목을 표준 출력으로 보내면 로그 뷰어를 사용하여 앱 항목을 심각도 기준으로 필터링하거나 특정 요청에 해당하는 앱 로그를 확인할 수 없습니다. 로그 탐색기에서 텍스트 및 타임스탬프와 같은 다른 유형의 필터링을 계속 사용할 수 있습니다.

로그 탐색기에서 상관관계가 지정된 로그 항목 보기

로그 탐색기에서 상위 로그 항목과 상관관계가 지정된 하위 로그 항목을 보려면 로그 항목을 펼칩니다.

예를 들어 App Engine 요청 로그 항목과 애플리케이션 로그 항목을 표시하려면 다음을 수행합니다.

Google Cloud 콘솔의 탐색 패널에서 Logging을 선택한 후 로그 탐색기를 선택합니다.

로그 탐색기로 이동
리소스 유형에서 GAE 애플리케이션을 선택합니다.
요청 로그를 보고 상관관계를 지정하려면 로그 이름에서 request_log를 선택합니다. 또는 요청 로그별로 상관관계를 지정하려면 상관관계 지정 기준을 클릭하고 request_log를 선택합니다.
쿼리 결과 창에서 로그 항목을 펼치려면 펼치기를 클릭합니다. 펼치면 각 요청 로그에 연결된 앱 로그가 표시됩니다.

로그 필터를 만들면 각 요청 로그에 해당 앱 로그가 하위 로그로 표시됩니다. 로그 탐색기는 애플리케이션이 google-cloud-logging 라이브러리를 사용한다는 가정 하에 앱 로그의 trace 필드와 지정된 요청 로그에 상관관계를 지정하여 이를 수행합니다.

다음 이미지는 trace 필드로 그룹화된 앱 로그를 보여줍니다.

요청 로그 항목에 중첩된 앱 로그 항목

Google Cloud CLI 사용

명령줄에서 App Engine 로그를 보려면 다음 명령어를 사용합니다.

gcloud app logs tail

자세한 내용은 gcloud 앱 로그 테일을 참조하세요.

프로그래매틱 방식으로 로그 읽기

프로그래매틱 방식으로 로그를 읽으려면 다음 방법 중 하나를 사용하면 됩니다.

Pub/Sub에 연결된 로그 싱크 및 Pub/Sub에서 가져오기 위한 스크립트를 사용합니다.
프로그래밍 언어의 클라이언트 라이브러리를 통해 Cloud Logging API를 호출합니다.
Cloud Logging API REST 엔드포인트를 직접 호출합니다.

앱 테스트

오류 없이 앱을 배포할 수 있으면 마이그레이션이 성공한 것입니다. Cloud Logging이 작동하는지 확인하려면 다음 단계를 따르세요.

로그 탐색기로 이동하여 요청 로그 항목을 펼칩니다.

로그 탐색기로 이동
요청을 처리할 때 앱에서 생성한 앱 로그가 요청 로그 내에 중첩되어 있는지 확인합니다.
모든 앱 엔드포인트가 예상대로 작동하면 트래픽 분할을 사용하여 업데이트된 앱의 트래픽을 천천히 늘립니다. 앱을 면밀히 모니터링하여 문제가 없는 것을 확인한 후 더 많은 트래픽을 업데이트된 앱으로 라우팅합니다.