자바용 Cloud Logging 설정

Logback 어펜더 또는 java.util.logging 핸들러를 사용하거나 자바용 Cloud Logging 라이브러리를 직접 사용하여 자바 애플리케이션에서 Cloud Logging에 로그를 작성할 수 있습니다.

자바용 Cloud Logging 라이브러리를 사용하기 위해 Cloud Logging 에이전트를 설치할 필요는 없습니다.

시작하기 전에

  1. Google 계정으로 로그인합니다.

    아직 계정이 없으면 새 계정을 등록하세요.

  2. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기 페이지로 이동

  3. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

  4. Cloud Logging API를 사용 설정합니다.

    API 사용 설정

Cloud Logging용 Logback 어펜더

Logback 어펜더를 사용하면 Cloud Logging을 SLF4J 로깅 퍼사드와 함께 사용할 수 있습니다.

종속 항목 설치

Maven을 사용하는 경우 pom.xml 파일에 다음을 추가합니다. BOM에 대한 자세한 내용은 Google Cloud Platform 라이브러리 BOM을 참조하세요.

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-logback</artifactId>
  <version>0.118.5-alpha</version>
</dependency>

Gradle을 사용하는 경우 종속 항목에 다음을 추가합니다.

compile 'com.google.cloud:google-cloud-logging-logback:0.118.5-alpha'

SBT를 사용하는 경우 종속 항목에 다음을 추가합니다.

libraryDependencies += "com.google.cloud" % "google-cloud-logging-logback" % "0.118.5-alpha"

Logback 구성

프로그래매틱 방식으로, 또는 XML이나 Groovy로 표현된 스크립트를 사용하여 Logback을 구성할 수 있습니다.

최소 심각도 임계값, 로그 이름을 맞춤설정하거나 추가 인핸서를 제공할 수 있습니다. 다음은 XML 형식의 샘플 Logback 구성입니다.

<configuration>
  <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
    <!-- Optional : filter logs at or above a level -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
      <level>INFO</level>
    </filter>
    <log>application.log</log> <!-- Optional : default java.log -->
    <resourceType>gae_app</resourceType> <!-- Optional : default: auto-detected, fallback: global -->
    <enhancer>com.example.logging.logback.enhancers.ExampleEnhancer</enhancer> <!-- Optional -->
    <flushLevel>WARN</flushLevel> <!-- Optional : default ERROR -->
  </appender>

  <root level="info">
    <appender-ref ref="CLOUD" />
  </root>
</configuration>

Cloud Logging Logback 어펜더를 사용하도록 Logback을 구성했다면 이제 SLF4J 로깅 API를 사용하여 로그를 리디렉션할 수 있습니다. 이 스니펫은 애플리케이션 내에서 SLF4J 퍼사드를 사용한 로깅 방식을 보여줍니다.


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Quickstart {
  private static final Logger logger = LoggerFactory.getLogger(Quickstart.class);

  public static void main(String[] args) {
    logger.info("Logging INFO with Logback");
    logger.error("Logging ERROR with Logback");
  }
}

java.util.logging 핸들러

기본 자바 Logging API 핸들러를 사용하여 Cloud Logging API를 사용할 수도 있습니다.

종속 항목 설치

Maven과 함께 BOM을 사용하는 경우 pom.xml 파일에 다음을 추가합니다.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>16.1.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-logging</artifactId>
  </dependency>
  <!-- ...
</dependencies>

BOM을 사용하지 않고 Maven을 사용하는 경우 종속 항목에 다음을 추가합니다.

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>2.0.2-SNAPSHOT</version>
</dependency>

Gradle을 사용하는 경우 종속 항목에 다음을 추가합니다.

compile 'com.google.cloud:google-cloud-logging:2.0.1'

SBT를 사용하는 경우 종속 항목에 다음을 추가합니다.

libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "2.0.1"

IntelliJ 또는 Eclipse를 사용하는 경우 다음 IDE 플러그인을 사용하여 클라이언트 라이브러리를 프로젝트에 추가할 수 있습니다.

이 플러그인은 서비스 계정의 키 관리와 같은 추가 기능을 제공합니다. 자세한 내용은 각 플러그인의 문서를 참조하세요.

java.util.logging 구성

프로그래매틱 방식으로, 또는 구성 파일을 사용하여 로깅 핸들러를 추가할 수 있습니다. 구성 파일 경로를 시스템 속성으로 애플리케이션에 제공해야 합니다(예: -Djava.util.logging.config.file=/path/to/logging.properties).

다음은 구성 파일의 예시입니다.

# To use this configuration, add to system properties : -Djava.util.logging.config.file="/path/to/file"
#
.level = INFO

# it is recommended that io.grpc and sun.net logging level is kept at INFO level,
# as both these packages are used by Stackdriver internals and can result in verbose / initialization problems.
io.grpc.netty.level=INFO
sun.net.level=INFO

com.example.logging.jul.Quickstart.handlers=com.google.cloud.logging.LoggingHandler
# default : java.log
com.google.cloud.logging.LoggingHandler.log=custom_log

# default : INFO
com.google.cloud.logging.LoggingHandler.level=FINE

# default : ERROR
com.google.cloud.logging.LoggingHandler.flushLevel=ERROR

# default : auto-detected, fallback "global"
com.google.cloud.logging.LoggingHandler.resourceType=container

# custom formatter
com.google.cloud.logging.LoggingHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=%3$s: %5$s%6$s

#optional enhancers (to add additional fields, labels)
com.google.cloud.logging.LoggingHandler.enhancers=com.example.logging.jul.enhancers.ExampleEnhancer

이 스니펫은 java.util.logging을 사용하여 로깅하는 방법을 보여줍니다.


import java.util.logging.Logger;

public class Quickstart {
  private static final Logger logger = Logger.getLogger(Quickstart.class.getName());

  public static void main(String[] args) {
    logger.info("Logging INFO with java.util.logging");
    logger.severe("Logging ERROR with java.util.logging");
  }
}

공통 구성

다음 섹션에서는 Cloud Logging용 java.util.logging 핸들러와 Logback 어펜더에 공통적인 구성을 설명합니다.

기본값

Logback 어펜더와 java.util.logging 핸들러는 다음 기본값을 사용하여 Cloud Logging 클라이언트를 인스턴스화합니다.

  • 로그 이름: java.log

  • 로깅할 최소 임곗값: INFO

  • Flush 심각도: ERROR

자바용 Cloud Logging 라이브러리는 최종 작성 이후의 메시지를 크기 및 시간을 기준으로 일괄 처리합니다. Flush 심각도 이상의 로깅 요청이 있는 배치는 즉시 작성됩니다.

모니터링 리소스 감지

Cloud Logging 라이브러리를 통해 전송되는 모든 로그에는 애플리케이션을 식별하기 위한 모니터링 리소스 유형이 필요합니다.

Logback 어펜더와 java.util.logging 핸들러는 App Engine, Compute Engine, Google Kubernetes Engine 애플리케이션의 자동 리소스 유형 감지 기능을 제공합니다.

global 모니터링 리소스는 다른 환경에서 기본값으로 사용됩니다.

Logback 어펜더 구성 또는 java.util.logging 핸들러 구성에서 모니터링 리소스 유형을 유효한 유형으로 재정의할 수 있습니다.

추가 필드 및 라벨

Logback 어펜더와 java.util.logging 핸들러를 사용하면 LoggingEnhancer 인스턴스를 사용하여 LogEntry 객체에서 필드를 추가하거나 업데이트할 수 있습니다.

Logback 어펜더 구성 또는 java.util.logging 핸들러 구성에 나와 있는 것처럼 인핸서를 구성해야 합니다.


import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.LoggingEnhancer;

// Add / update additional fields to the log entry
public class ExampleEnhancer implements LoggingEnhancer {

  @Override
  public void enhanceLogEntry(LogEntry.Builder logEntry) {
    // add additional labels
    logEntry.addLabel("test-label-1", "test-value-1");
  }
}

설치에 대한 자세한 내용은 자바용 Cloud Logging 라이브러리에 대한 문서를 참조하세요. 또한 Issue Tracker를 통해 문제를 신고할 수도 있습니다.

Cloud 클라이언트 라이브러리 직접 사용

자바용 Cloud Logging Cloud 클라이언트 라이브러리를 사용하는 방법은 Cloud Logging 클라이언트 라이브러리를 참조하세요.

Google Cloud에서 실행

자바용 Cloud Logging 라이브러리를 사용하려면 Google Cloud의 IAM 로그 작성자 역할이 있어야 합니다. 대부분의 Google Cloud 환경은 기본적으로 이 역할을 제공합니다.

App Engine

App Engine은 기본적으로 로그 작성자 역할을 부여합니다.

자바용 Cloud Logging 라이브러리는 명시적으로 사용자 인증 정보를 제공하지 않아도 사용 가능합니다.

Cloud Logging은 App Engine 애플리케이션에서 자동으로 사용 설정되며 추가 설정이 필요 없습니다.

App Engine 표준 환경에서는 기본적으로 java.util.logging.Logger API를 사용하므로 로그가 Cloud Logging에 직접 작성되고 구성이 간편합니다.

자세한 내용은 애플리케이션 로그 읽기 및 쓰기에 관한 App Engine 문서를 참조하세요.

App Engine 가변형 환경

App Engine 가변형 환경에서 java.util.logging은 기본적으로 ConsoleHandler를 사용하며 로그를 stdoutstderr로 전송합니다.

Jetty 런타임은 자바용 Cloud Logging 라이브러리와 함께 번들로 제공됩니다.

java.util.logging 핸들러를 사용하면 아래와 같이 app.yaml에서 logging.properties를 제공하는 방식으로 Cloud Logging에 직접 로깅할 수 있습니다.

    env_variables:
      JETTY_ARGS: -Djava.util.logging.config.file=WEB-INF/logging.properties

java.util.logging 핸들러 또는 Logback 어펜더를 사용하는 경우에는 Jetty 런타임에서 trace ID를 사용할 수 있습니다.

App Engine 가변형 환경에서 실행할 때 TraceLoggingEnhancer 인스턴스는 trace_id 라벨을 사용하여 모든 로그 항목에 스레드 안전성을 갖는 trace ID를 추가합니다.

Google Kubernetes Engine

Google Kubernetes Engine에서는 클러스터를 만들 때 logging.write 액세스 범위를 추가해야 합니다.

gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

Compute Engine VM 인스턴스를 사용할 때 각 인스턴스에 cloud-platform 액세스 범위를 추가합니다. Google Cloud Console을 통해 새 인스턴스를 만들 때 인스턴스 만들기 패널의 ID 및 API 액세스 섹션에서 이 작업을 수행할 수 있습니다. 선택한 Compute Engine 기본 서비스 계정 또는 다른 서비스 계정을 사용하고 ID 및 API 액세스 섹션에서 모든 Cloud API에 대한 전체 액세스 허용을 선택하세요. 선택한 서비스 계정에 관계없이 Cloud Console의 IAM 및 관리자 섹션에서 로그 작성자 역할이 부여되었는지 확인합니다.

로컬 및 기타 위치에서 실행

자체 워크스테이션, 데이터 센터의 컴퓨터 또는 다른 클라우드 제공업체의 VM 인스턴스에서 라이브러리를 실행하는 경우와 같이 Google Cloud 외부에서 자바용 Cloud Logging 라이브러리를 사용하려면 자바용 Cloud Logging 라이브러리에 직접 Google Cloud 프로젝트 ID와 적절한 서비스 계정 사용자 인증 정보를 제공해야 합니다.

서비스 계정 사용자 인증 정보를 수동으로 만들고 가져올 수 있습니다. 역할 필드를 지정할 때 로그 작성자 역할을 사용하세요. Identity and Access Management 역할에 대한 자세한 내용은 액세스 제어 가이드를 참조하세요.

로그 보기

배포 후 로그 탐색기에서 로그를 볼 수 있습니다.

로그 탐색기로 이동

로그 탐색기에서 리소스를 하나 이상 지정해야 하지만 어떤 리소스를 선택해야 할지 애매할 수 있습니다. 다음은 시작하는 데 도움이 되는 몇 가지 유용한 팁입니다.

  • 애플리케이션을 App Engine에 배포하거나 App Engine 관련 라이브러리를 사용하는 경우 리소스를 GAE 애플리케이션으로 설정합니다.

  • 애플리케이션을 Compute Engine에 배포하는 경우 리소스를 GCE VM 인스턴스로 설정합니다.

  • 애플리케이션을 Google Kubernetes Engine에 배포하는 경우 클러스터의 로깅 구성에 따라 로그 항목의 리소스 유형이 결정됩니다. 기존 Google Cloud의 작업 제품군 및 Google Cloud의 작업 제품군 Kubernetes Monitoring 솔루션에 대한 자세한 내용과 이러한 옵션이 리소스 유형에 미치는 영향을 알아보려면 Google Cloud의 작업 제품군 Kubernetes Monitoring으로 마이그레이션을 참조하세요.

  • 애플리케이션에서 Cloud Logging API를 직접 사용하는 경우 API와 구성에 따라 리소스가 달라집니다. 예를 들어 애플리케이션에서 리소스를 지정하거나 기본 리소스를 사용할 수 있습니다.

  • 로그 탐색기에 어떤 로그도 표시되지 않는 경우 모든 로그 항목을 보려면 고급 쿼리 모드로 전환하여 비어 있는 쿼리를 사용합니다.

    1. 고급 쿼리 모드로 전환하려면 로그 탐색기 상단의 메뉴(&blacktriangledown;)를 클릭한 다음 고급 필터로 전환을 선택합니다.
    2. 필터 상자에 포함된 내용을 지웁니다.
    3. 필터 제출을 클릭합니다.

    개별 항목을 검사하여 리소스를 파악할 수 있습니다.

자세한 내용은 로그 보기고급 로그 쿼리를 참조하세요.