자바용 Cloud Logging 설정

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

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

시작하기 전에

  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.

    Go to project selector

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

  4. Enable the Cloud Logging API.

    Enable the API

    5.

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

    Go to project selector

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

  7. Enable the Cloud Logging API.

    Enable the API

    8.

Cloud Logging용 Logback 어펜더

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

종속 항목 설치

If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

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

If you are using Gradle, add the following to your dependencies:

implementation 'com.google.cloud:google-cloud-logging-logback:0.131.6-alpha'

If you are using sbt, add the following to your dependencies:

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

Logback 구성

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

최소 심각도 임계값, 로그 이름을 맞춤설정하거나 추가 인핸서를 제공할 수 있습니다. 다음은 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 logging API를 사용하여 로그를 리디렉션할 수 있습니다. 예시를 로컬 또는 Google Cloud 외부에서 실행하려는 경우 Google Cloud 구성을 제공합니다. 이 스니펫은 애플리케이션 내에서 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를 사용할 수도 있습니다.

종속 항목 설치

If you are using Maven with a BOM, add the following to your pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.39.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>

If you are using Maven without a BOM, add this to your dependencies:

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

If you are using Gradle, add the following to your dependencies:

implementation platform('com.google.cloud:libraries-bom:26.39.0')

implementation 'com.google.cloud:google-cloud-logging'

If you are using sbt, add the following to your dependencies:

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

If you're using Visual Studio Code, IntelliJ, or Eclipse, you can add client libraries to your project using the following IDE plugins:

The plugins provide additional functionality, such as key management for service accounts. Refer to each plugin's documentation for details.

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 Cloud 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

예

예시를 로컬 또는 Google Cloud 외부에서 실행하려는 경우 Google Cloud 구성을 제공합니다. 이 스니펫은 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");
  }
}

구성에 커스텀 라벨을 사용하지 못할 수 있습니다. 예를 들어 Dataflow 로그에는 이러한 라벨이 포함되어 있지 않습니다.

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

Cloud Logging 클라이언트 라이브러리로 로그 작성

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

Google Cloud에서 실행

애플리케이션에서 자바용 Cloud Logging 라이브러리를 사용하여 로그를 작성하려면 기본 리소스의 서비스 계정에 로그 작성자(roles/logging.logWriter) IAM 역할이 있어야 합니다. 대부분의 Google Cloud 환경에서는 이 역할을 갖도록 기본 서비스 계정을 자동으로 구성합니다.

App Engine

Cloud Logging은 App Engine에 자동으로 사용 설정되며 앱의 기본 서비스 계정에는 기본적으로 로그 항목을 쓸 수 있는 IAM 권한이 있습니다.

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

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

App Engine 가변형 환경

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

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(GKE)

GKE에서는 기본 서비스 계정에 로그 작성자(roles/logging.logWriter) IAM 역할을 자동으로 부여합니다. 이 기본 서비스 계정과 함께 GKE용 워크로드 아이덴티티 제휴를 사용하여 워크로드가 특정 Google Cloud API에 액세스할 수 있도록 하면 추가 구성이 필요하지 않습니다. 그러나 커스텀 IAM 서비스 계정과 함께 GKE용 워크로드 아이덴티티 제휴를 사용하는 경우 커스텀 서비스 계정에 로그 작성자 역할(roles/logging.logWriter)이 있어야 합니다.

필요한 경우 클러스터를 만들 때 다음 명령어를 사용하여 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 콘솔을 통해 새 인스턴스를 만들 때 인스턴스 만들기 패널의 ID 및 API 액세스 섹션에서 이 작업을 수행할 수 있습니다. 선택한 Compute Engine 기본 서비스 계정 또는 다른 서비스 계정을 사용하고 ID 및 API 액세스 섹션에서 모든 Cloud API에 대한 전체 액세스 허용을 선택하세요. 선택한 서비스 계정에 관계없이 Google Cloud 콘솔의 IAM 및 관리자 섹션에서 로그 작성자 역할이 부여되었는지 확인합니다.

로컬 및 기타 위치에서 실행

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

기존 서비스 계정의 경우 다음을 수행합니다.

  1. 서비스 계정에 로그 작성자(roles/logging.logWriter) IAM 역할을 부여합니다. IAM 역할에 대한 자세한 내용은 액세스 제어를 참조하세요.

  2. 애플리케이션 기본 사용자 인증 정보를 설정합니다.

서비스 계정이 없으면 서비스 계정을 만듭니다. 이 프로세스에 대한 자세한 내용은 서비스 계정 만들기를 참조하세요.

인증에 사용할 수 있는 방법에 대한 일반적인 내용은 용어: 서비스 계정을 참조하세요.

로그 보기

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

로그 탐색기로 이동

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

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

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

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

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

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

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

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

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

자세한 내용은 로그 탐색기 사용을 참조하세요.