로그 작성 및 보기

Go Java Node.js PHP Python Ruby

이 페이지에서는 App Engine 앱에 사용할 수 있는 로그와 로그 항목을 작성하고, 관계를 파악하고, 조회하는 방법을 설명합니다.

App Engine은 다음 세 가지 유형의 로그를 수집합니다.

• 요청 로그: 앱으로 전송된 요청의 로그입니다. 기본적으로 App Engine은 앱이 수신하는 각 HTTP 요청에 대한 로그 항목을 자동으로 내보냅니다.

• 앱 로그: 지원되는 프레임워크 또는 파일에 기록하는 로그 항목을 기준으로 App Engine 앱에서 내보내는 로그 항목입니다.

• 시스템 로그: 앱에 관한 정보가 포함된 플랫폼에서 생성된 로그입니다. 이 로그는 varlog/system에 작성됩니다.

App Engine은 요청 로그와 앱 로그를 모두 Cloud Logging 에이전트에 자동으로 보냅니다.

참고: 1세대 런타임에서 2세대 런타임으로 업그레이드하는 경우 자세한 내용과 예시는 Cloud Logging으로 마이그레이션을 참조하세요.

앱 로그 작성

App Engine은 앱에 전송된 요청에 대한 로그를 자동으로 내보내므로 요청 로그를 작성할 필요가 없습니다. 이 섹션에서는 앱 로그를 작성하는 방법을 설명합니다.

App Engine 앱에서 다음 방법을 사용하여 앱 로그를 작성하면 Cloud Logging에서 자동으로 로그를 수집합니다.

• Cloud Logging 통합
• stdout 및 stderr로 구조화된 로그 작성

Cloud Logging 통합

App Engine 앱을 Cloud Logging과 통합할 수 있습니다. 이 접근 방식을 사용하면 Google 관련 코드 몇 줄만으로 Cloud Logging에서 제공하는 모든 기능을 사용할 수 있습니다.

표준 Python 로깅 핸들러를 사용하거나 Python용 Cloud Logging API 클라이언트 라이브러리를 직접 사용하여 Python 애플리케이션에서 Cloud Logging에 로그를 작성할 수 있습니다. 표준 Python 로깅 핸들러를 사용할 때는 Cloud Logging 핸들러를 Python 루트 핸들러에 연결해야 합니다. 자세한 내용은 Python용 Cloud Logging 설정을 참조하세요.

중요: 로그 탐색기에는 16KB를 초과하는 앱 로그 항목이 표시되지 않습니다.

stdout 및 stderr에 구조화된 로그 작성

기본적으로 App Engine은 Cloud Logging 클라이언트 라이브러리를 사용하여 로그를 전송합니다. 그러나 이 메서드는 구조화된 로깅을 지원하지 않습니다. stdout/stderr을 사용하여 구조화된 로그만 작성할 수 있습니다. 또한 stdout 및 stderr에 텍스트 문자열을 보낼 수도 있습니다. 기본적으로 로그 페이로드는 로그 항목의 textPayload 필드에 저장되는 텍스트 문자열입니다. 문자열은 로그 탐색기, 명령줄, Cloud Logging API에 메시지로 표시되며 이를 출력한 App Engine 서비스와 버전과 연결됩니다.

로그 탐색기에서 이러한 문자열을 심각도 수준으로 필터링하면 로그를 더 유용하게 활용할 수 있습니다. 이러한 문자열을 필터링하려면 문자열의 형식을 구조화된 데이터로 지정해야 합니다. 이를 위해 한 줄로 직렬화된 JSON 형식으로 로그를 작성합니다. App Engine은 이 직렬화된 JSON 줄을 수집하고 파싱하여 textPayload 대신 로그 항목의 jsonPayload 필드에 배치합니다.

다음 스니펫은 이러한 구조화된 로그를 작성하는 방법을 보여줍니다.

참고: 이 스니펫은 원래 Cloud Run용으로 작성되었습니다. App Engine에도 동일하게 적용됩니다.

# Uncomment and populate this variable in your code:
# PROJECT = 'The project ID of your Cloud Run service';

# Build structured log messages as an object.
global_log_fields = {}

# Add log correlation to nest all log messages.
# This is only relevant in HTTP-based contexts, and is ignored elsewhere.
# (In particular, non-HTTP-based Cloud Functions.)
request_is_defined = "request" in globals() or "request" in locals()
if request_is_defined and request:
    trace_header = request.headers.get("X-Cloud-Trace-Context")

    if trace_header and PROJECT:
        trace = trace_header.split("/")
        global_log_fields[
            "logging.googleapis.com/trace"
        ] = f"projects/{PROJECT}/traces/{trace[0]}"

# Complete a structured log entry.
entry = dict(
    severity="NOTICE",
    message="This is the default display field.",
    # Log viewer accesses 'component' as jsonPayload.component'.
    component="arbitrary-property",
    **global_log_fields,
)

print(json.dumps(entry))

App Engine 표준 환경에서 stdout 및 stderr에 구조화된 로그를 작성하는 작업은 Cloud Logging API의 분당 로그 수집 요청 할당량에 포함되지 않습니다.

메시지의 특수 JSON 필드

구조화된 로그를 JSON 사전으로 제공하면 일부 특수 필드가 jsonPayload에서 삭제되고 특수 필드 문서에 설명된 대로 생성된 LogEntry의 해당 필드에 작성됩니다.

예를 들어 JSON에 severity 속성이 포함되어 있으면 이 속성은 jsonPayload에서 삭제되고 대신 로그 항목의 severity로 표시됩니다. message 속성이 있으면 이 속성은 로그 항목의 기본 표시 텍스트로 사용됩니다.

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

기본적으로 2세대 런타임에서는 로그 간에 상관관계가 없습니다. 이러한 런타임에는 Cloud 클라이언트 라이브러리를 사용해야 합니다. 이러한 라이브러리는 중첩을 지원하지 않으며 로그의 상관관계를 직접 지정해야 합니다.

Python 로깅 모듈 사용

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

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

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

stdout 및 stderr 사용

항목의 형식을 JSON 객체로 지정하고 특정 메타데이터를 제공한 후 요청 로그 필터링 및 상관관계를 사용 설정할 수 있습니다. 요청 로그 항목과 앱 로그 항목의 상관관계를 지정하려면 요청의 trace 식별자가 필요합니다. 안내에 따라 로그 메시지의 상관관계를 지정합니다.

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

상관관계가 지정된 로그를 보려면 로그 탐색기에서 상관관계가 지정된 로그 항목 보기를 참조하세요.

로그 보기

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

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

로그 탐색기 사용

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

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

   로그 탐색기로 이동

2. 페이지 상단에서 기존 Google Cloud 프로젝트를 선택합니다.

3. 리소스 유형에서 GAE 애플리케이션을 선택합니다.

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

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

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

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

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

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

   로그 탐색기로 이동

2. 리소스 유형에서 GAE 애플리케이션을 선택합니다.

3. 요청 로그를 보고 상관관계를 지정하려면 로그 이름에서 request_log를 선택합니다. 또는 요청 로그별로 상관관계를 지정하려면 상관관계 지정 기준을 클릭하고 request_log를 선택합니다.

   

4. 쿼리 결과 창에서 로그 항목을 펼치려면 펼치기를 클릭합니다. 펼치면 각 요청 로그에 연결된 앱 로그가 표시됩니다.

로그 필터를 만들면 각 요청 로그에 해당 앱 로그가 하위 로그로 표시됩니다. 로그 탐색기는 애플리케이션이 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의 varlog/system 로그 이름 아래에 각 인스턴스가 생성된 이유를 나타내는 로그 항목이 포함됩니다. 로그 항목의 형식은 다음과 같습니다.

Starting new instance. Reason: REASON - DESCRIPTION

다음 표에서는 인스턴스 설명을 자세히 보여줍니다.

이유	설명
CUSTOMER_MIN_INSTANCE	앱에 대해 고객이 구성한 최소 인스턴스입니다.
SCHEDULED	구성된 배율(예: CPU 사용률, 요청 처리량 등) 및 대상에 따라 인스턴스가 시작되었습니다.
OVERFLOW	현재 트래픽의 기존 용량을 찾을 수 없기 때문에 인스턴스가 시작되었습니다.

가격 책정, 할당량, 로그 보관 정책

요청 및 앱 로그 모두에 적용되는 가격에 대한 자세한 내용은 Cloud Logging 가격 책정을 참조하세요.

로그 보관 정책과 최대 로그 항목 크기는 할당량 및 한도를 참조하세요. 로그를 더 오래 저장하려는 경우 Cloud Storage로 로그를 내보낼 수 있습니다. 또한 추가 처리를 위해 로그를 BigQuery 및 Pub/Sub로 내보낼 수 있습니다.

로그 리소스 사용량 관리

앱의 코드에서 항목을 더 많이 또는 더 적게 작성하여 앱 로그에서 로깅 활동량을 관리할 수 있습니다. 요청 로그는 자동으로 생성되므로 앱과 연결된 요청 로그 항목의 수를 관리하려면 Cloud Logging의 로그 제외 기능을 사용합니다.

알려진 문제

다음은 2세대 런타임의 몇 가지 로깅 문제입니다.

• 앱 로그 항목이 요청 로그와 상관 관계가 없는 경우가 있습니다. 이 문제는 앱이 처음 요청을 수신하는 경우와 App Engine이 앱의 로그에 상태 메시지를 작성하는 경우에 발생합니다. 자세한 내용은 https://issuetracker.google.com/issues/138365527을 참조하세요.

• 로그 싱크에서 Cloud Storage로 로그를 라우팅하면 Cloud Storage 대상에 요청 로그만 포함됩니다. App Engine은 앱 로그를 다른 폴더에 작성합니다.

• 요청 로그의 @type 필드로 인해 BigQuery에서 로그를 수집할 수 없습니다. BigQuery에서 필드 이름에 @type을 허용하지 않기 때문에 자동 스키마 감지가 중단됩니다. 이 문제를 해결하려면 스키마를 수동으로 정의하고 요청 로그에서 @type 필드를 삭제해야 합니다.

• 로깅 REST API를 사용하는 경우 백그라운드 스레드가 Cloud Logging에 로그를 작성합니다. 기본 스레드가 활성 상태가 아니면 인스턴스는 CPU 시간을 얻지 못하므로 백그라운드 스레드가 중지됩니다. 로그 처리 시간이 지연됩니다. 특정 시점에 인스턴스가 삭제되고 보내지 않은 모든 로그가 손실됩니다. 로그 손실을 방지하려면 다음 옵션 중 하나를 사용합니다.

  • gRPC를 사용하도록 Cloud Logging SDK를 구성합니다. gRPC를 사용하면 로그가 즉시 Cloud Logging으로 전송됩니다. 하지만 이렇게 하면 필요한 CPU 한도가 증가할 수 있습니다.
  • stdout/stderr을 사용하여 로그 메시지를 Cloud Logging에 전송합니다. 이 파이프라인은 App Engine 인스턴스 외부에 있으며 제한되지 않습니다.

다음 단계

• 지연 시간 모니터링 및 알림을 참조하여 Cloud Logging을 사용하여 로그에서 디버깅 오류 로그를 확인하는 방법과 Cloud Trace를 사용하여 앱 지연 시간을 파악하는 방법을 알아보세요.