Java 계측 샘플

이 문서에서는 OpenTelemetry SDK와 OpenTelemetry 수집기를 사용하여 trace 및 측정항목 데이터를 수집하도록 Java 앱을 계측하는 방법을 설명합니다. 또한 구조화된 JSON 로그를 표준 출력에 작성하는 방법도 설명합니다. 계측을 실험하려면 샘플 앱을 다운로드하여 실행하세요. 이 앱은 Spring Boot 프레임워크를 사용하고 로그, 측정항목, 추적 데이터를 생성합니다.

OpenTelemetry 수집기를 사용하는 경우 SDK와 SDK의 OTLP 프로세스 내 내보내기 도구로 애플리케이션을 계측합니다. 이 계측은 공급업체 중립적입니다. 프로세스 내 내보내기 도구에서 원격 분석을 수신한 후 해당 원격 분석을 Google Cloud 프로젝트로 내보내는 OpenTelemetry 수집기도 배포합니다. 수집기에 대해 자세히 알아보려면 Google 기반의 OpenTelemetry Collector를 참고하세요.

환경에서 수집기 사용을 지원하는 경우 OpenTelemetry 수집기를 사용하여 원격 분석 데이터를 내보내는 것이 좋습니다. 일부 환경에서는Google Cloud 프로젝트로 데이터를 직접 전송하는 인프로세스 내보내기 도구를 사용해야 합니다. 인프로세스 계측에 대해 알아보려면 Trace 내보내기 도구에서 OTLP 엔드포인트로 마이그레이션을 참고하세요.

계측에 대한 자세한 내용은 다음 문서를 참조하세요.

• 계측 및 모니터링 가능성
• 계측 방법 선택

참고: 이 문서에는 작동하는 애플리케이션의 일부만 표시됩니다. 예를 들어 샘플에 가져온 패키지 목록이 표시되지 않습니다. 하지만 전체 애플리케이션은 GitHub에서 확인할 수 있습니다. 전체 샘플을 보려면 더보기를 클릭한 다음 GitHub에서 보기를 선택합니다.

수동 및 제로 코드 계측 정보

이 문서에서는 Google Cloud 프로젝트로 원격 분석을 전송하기 위해 OpenTelemetry 제로 코드 계측을 사용하는 계측 기능에 대해 설명합니다. Java의 경우, 제로 코드 계측은 바이트 코드를 라이브러리 및 프레임워크에 동적으로 삽입하여 원격 분석을 캡처하는 방식입니다. 코드 없는 계측을 사용하여 인바운드 및 아웃바운드 HTTP 호출 같은 항목에 대한 원격 분석을 수집할 수 있습니다. 자세한 내용은 Java 에이전트를 참고하세요.

또한 OpenTelemetry는 자체 코드에 커스텀 계측을 추가할 수 있는 API를 제공합니다. OpenTelemetry에서는 이를 수동 계측이라고 합니다. 이 문서에서는 수동 계측에 대해 설명하지 않습니다. 해당 주제에 대한 예시와 정보를 확인하려면 수동 계측을 참조하세요.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

• 프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
• 프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

참고: 이 절차에서 생성한 리소스를 유지하지 않으려면 기존 프로젝트를 선택하지 말고 프로젝트를 새로 만드세요. 작업이 끝나면 프로젝트를 삭제하여 프로젝트와 관련된 모든 리소스를 삭제할 수 있습니다.

• Google Cloud 프로젝트를 만듭니다.

  gcloud projects create PROJECT_ID

  PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.

• 생성한 Google Cloud 프로젝트를 선택합니다.

  gcloud config set project PROJECT_ID

  PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Cloud Logging, Cloud Monitoring, Cloud Trace, 원격 분석 API를 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할 (roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Google Cloud 프로젝트를 만들거나 선택합니다.

프로젝트를 선택하거나 만드는 데 필요한 역할

• 프로젝트 선택: 프로젝트를 선택하는 데는 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 프로젝트를 선택하면 됩니다.
• 프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기

참고: 이 절차에서 생성한 리소스를 유지하지 않으려면 기존 프로젝트를 선택하지 말고 프로젝트를 새로 만드세요. 작업이 끝나면 프로젝트를 삭제하여 프로젝트와 관련된 모든 리소스를 삭제할 수 있습니다.

• Google Cloud 프로젝트를 만듭니다.

  gcloud projects create PROJECT_ID

  PROJECT_ID를 만들려는 Google Cloud 프로젝트의 이름으로 바꿉니다.

• 생성한 Google Cloud 프로젝트를 선택합니다.

  gcloud config set project PROJECT_ID

  PROJECT_ID을 Google Cloud 프로젝트 이름으로 바꿉니다.

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Cloud Logging, Cloud Monitoring, Cloud Trace, 원격 분석 API를 사용 설정합니다.

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할 (roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

1. Cloud Shell, Google Cloud리소스 또는 로컬 개발 환경에서 샘플을 실행하는 경우 이 섹션에 나열된 권한으로 충분합니다. 프로덕션 애플리케이션의 경우 일반적으로 서비스 계정이 로그, 측정항목, trace 데이터를 작성하는 사용자 인증 정보를 제공합니다.

   샘플 애플리케이션에서 로그, 측정항목, trace 데이터를 작성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

   • 로그 작성자(roles/logging.logWriter)
   • 모니터링 측정항목 작성자(roles/monitoring.metricWriter)
   • Cloud 원격 분석 trace 작성자(roles/telemetry.tracesWriter)

   로그, 측정항목, trace 데이터를 보는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

   • 로그 뷰어(roles/logging.viewer)
   • 모니터링 뷰어(roles/monitoring.viewer)
   • Cloud Trace 사용자(roles/cloudtrace.user)

   역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참고하세요.

   커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

앱을 계측하여 trace, 측정항목, 로그 수집

trace 및 측정항목 데이터를 수집하고 구조화된 JSON을 표준 출력에 작성하도록 앱을 계측하려면 이 문서의 이어지는 섹션에 설명된 대로 다음 단계를 수행합니다.

1. OpenTelemetry Java 에이전트를 사용하도록 앱 구성
2. OpenTelemetry 구성
3. 구조화된 로깅 구성
4. 구조화된 로그 작성

OpenTelemetry Java 에이전트를 사용하도록 앱 구성

OpenTelemetry를 사용하여 구조화된 로그를 작성하고 측정항목 및 trace 데이터를 수집하도록 앱을 구성하려면 OpenTelemetry Java 에이전트를 사용하도록 앱 호출을 업데이트합니다. 이러한 앱 계측 방법은 앱 코드를 수정할 필요가 없으므로 자동 계측이라고 합니다.

다음 코드 샘플은 OpenTelemetry Java 에이전트 JAR 파일을 다운로드하고 -javaagent 플래그를 전달하도록 명령줄 호출을 업데이트하는 Dockerfile을 보여줍니다.

전체 샘플을 보려면 더보기를 클릭한 다음 GitHub에서 보기를 선택합니다.

RUN wget -O /opentelemetry-javaagent.jar https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.31.0/opentelemetry-javaagent.jar
CMD sh -c "java -javaagent:/opentelemetry-javaagent.jar -cp app:app/lib/* com.example.demo.DemoApplication \
	2>&1 | tee /var/log/app.log"

또는 JAVA_TOOL_OPTIONS 환경 변수의 -javaagent 플래그를 설정할 수도 있습니다.

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"

OpenTelemetry 구성

OpenTelemetry Java 에이전트의 기본 구성은 OTLP 프로토콜을 사용하여 trace 및 측정항목을 내보냅니다. 또한 trace 컨텍스트 전파에 W3C Trace 컨텍스트 형식을 사용하도록 OpenTelemetry를 구성합니다. 이 구성을 통해 스팬이 trace 내에서 올바른 상위-하위 관계를 갖도록 할 수 있습니다.

자세한 내용 및 구성 옵션은 OpenTelemetry Java 자동 계측을 참조하세요.

구조화된 로깅 구성

표준 출력에 작성된 JSON 형식 로그의 일부로 trace 정보를 포함하려면 JSON 형식으로 구조화된 로그를 출력하도록 앱을 구성합니다. 로깅 구현으로 Log4j2를 사용하는 것이 좋습니다. 다음 코드 샘플은 JSON 템플릿 레이아웃을 사용하여 구조화된 JSON 로그를 출력하도록 구성된 log4j2.xml 파일을 보여줍니다.

<!-- Format JSON logs for the Cloud Logging agent
https://cloud.google.com/logging/docs/structured-logging#special-payload-fields -->

<!-- Log4j2's JsonTemplateLayout includes a template for Cloud Logging's special JSON fields
https://logging.apache.org/log4j/2.x/manual/json-template-layout.html#event-templates -->
<JsonTemplateLayout eventTemplateUri="classpath:GcpLayout.json">
  <!-- Extend the included GcpLayout to include the trace and span IDs from Mapped
  Diagnostic Context (MDC) so that Cloud Logging can correlate Logs and Spans

  Since log4j2 2.24.0, GcpLayout.json already includes trace context logging from MDC and
  the below additional fields are no longer needed -->
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace"
    format="JSON"
    value='{"$resolver": "mdc", "key": "trace_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/spanId"
    format="JSON"
    value='{"$resolver": "mdc", "key": "span_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace_sampled"
    format="JSON"
    value="true"
  />
</JsonTemplateLayout>

이전 구성은 SLF4J의 매핑된 진단 컨텍스트에서 활성 스팬에 대한 정보를 추출하고 해당 정보를 로그에 속성으로 추가합니다. 그런 다음, 다음 속성을 사용하여 로그와 trace의 상관관계를 보여줄 수 있습니다.

• logging.googleapis.com/trace: 로그 항목과 연결된 trace의 리소스 이름입니다.
• logging.googleapis.com/spanId: 로그 항목과 연결된 trace가 있는 스팬 ID입니다.
• logging.googleapis.com/trace_sampled: 이 필드의 값은 true 또는 false여야 합니다.

이러한 필드에 대한 자세한 내용은 LogEntry 구조를 참조하세요.

구조화된 로그 작성

trace에 연결되는 구조화된 로그를 작성하려면 SLF4J logging API를 사용합니다. 예를 들어 다음 문은 Logger.info() 메서드를 호출하는 방법을 보여줍니다.

logger.info("handle /multi request with subRequests={}", subRequests);

OpenTelemetry Java 에이전트는 SLF4J의 매핑된 진단 컨텍스트를 OpenTelemetry 컨텍스트에 있는 현재 활성 스팬의 스팬 컨텍스트로 자동으로 채웁니다. 그러면 매핑된 진단 컨텍스트가 구조화된 구성 로깅에 설명된 대로 JSON 로그에 포함됩니다.

원격 분석을 수집하도록 구성된 샘플 앱 실행

샘플 앱의 계측은 로그 데이터용 JSON, 측정항목 및 추적 데이터용 OTLP와 같은 공급업체 중립적인 형식을 사용합니다. 앱은 Spring Boot Framework도 사용합니다. OpenTelemetry Collector는 Google 내보내기 도구를 사용하여 로그 및 측정항목 데이터를 프로젝트로 전송합니다. OTLP를 사용하는 Telemetry API를 사용하여 trace 데이터를 프로젝트로 전송합니다.

이 앱에는 2개의 엔드포인트가 있습니다.

• /multi 엔드포인트는 handleMulti 함수로 처리됩니다. 앱의 부하 생성기는 /multi 엔드포인트로 요청을 보냅니다. 이 엔드포인트가 요청을 수신하면 로컬 서버의 /single 엔드포인트로 3~7개의 요청을 보냅니다.

  /**
   * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
   *
   * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
   * span for the controller body.
   */
  @GetMapping("/multi")
  public Mono<String> handleMulti() throws Exception {
    int subRequests = ThreadLocalRandom.current().nextInt(3, 8);
  
    // Write a structured log with the request context, which allows the log to
    // be linked with the trace for this request.
    logger.info("handle /multi request with subRequests={}", subRequests);
  
    // Make 3-7 http requests to the /single endpoint.
    return Flux.range(0, subRequests)
        .concatMap(
            i -> client.get().uri("http://localhost:8080/single").retrieve().bodyToMono(Void.class))
        .then(Mono.just("ok"));
  }

• /single 엔드포인트는 handleSingle 함수로 처리됩니다. 이 엔드포인트가 요청을 수신하면 짧은 지연 동안 절전 모드로 전환된 후 문자열로 응답합니다.

  /**
   * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
   * milliseconds slept as its response.
   *
   * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
   * span for the controller body.
   */
  @GetMapping("/single")
  public String handleSingle() throws InterruptedException {
    int sleepMillis = ThreadLocalRandom.current().nextInt(100, 200);
    logger.info("Going to sleep for {}", sleepMillis);
    Thread.sleep(sleepMillis);
    logger.info("Finishing the request");
    return String.format("slept %s\n", sleepMillis);
  }

앱 다운로드 및 배포

참고: Cloud Shell을 사용하여 샘플 앱을 실행하는 것이 좋습니다. 그러나 Linux 또는 Mac에서 로컬로 샘플 앱을 실행하려면 다음 안내의 첫 번째 단계를 건너뛰세요.

샘플을 실행하려면 다음을 수행합니다.

1. Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

   Cloud Shell 활성화

   Google Cloud 콘솔 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

2. 저장소를 클론합니다.

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java
   

3. 샘플 디렉터리로 이동합니다.

   cd opentelemetry-operations-java/examples/instrumentation-quickstart
   

4. 샘플을 빌드하고 실행합니다.

   docker compose up --abort-on-container-exit
   

   Cloud Shell에서 실행하지 않는 경우 사용자 인증 정보 파일을 가리키는 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용하여 애플리케이션을 실행합니다. 애플리케이션 기본 사용자 인증 정보는 $HOME/.config/gcloud/application_default_credentials.json에서 사용자 인증 정보 파일을 제공합니다.

   # Set environment variables
   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
   export USERID="$(id -u)"
   
   # Run
   docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
   

측정항목 보기

샘플 앱의 OpenTelemetry 계측은 측정항목 탐색기를 사용하여 볼 수 있는 Prometheus 측정항목을 생성합니다.

• Prometheus/http_server_duration_milliseconds/histogram은 서버 요청 기간을 기록하고 결과를 히스토그램에 저장합니다.

• Prometheus/http_client_duration_milliseconds/histogram은 클라이언트 요청 기간을 기록하고 결과를 히스토그램에 저장합니다.

샘플 앱에서 생성된 측정항목을 보려면 다음을 실행합니다.

1. Google Cloud 콘솔에서  측정항목 탐색기 페이지로 이동합니다.

   측정항목 탐색기로 이동

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

2. Google Cloud 콘솔의 툴바에서 Google Cloud 프로젝트를 선택합니다. App Hub 구성의 경우 App Hub 호스트 프로젝트나 앱 지원 폴더의 관리 프로젝트를 선택합니다.
3. 측정항목 요소에서 측정항목 선택 메뉴를 펼치고 필터 표시줄에 http_server을 입력한 후 하위 메뉴를 사용하여 특정 리소스 유형과 측정항목을 선택합니다.
   1. 활성 리소스 메뉴에서 Prometheus 대상을 선택합니다.
   2. 활성 측정항목 카테고리 메뉴에서 Http를 선택합니다.
   3. 활성 측정항목 메뉴에서 측정항목을 선택합니다.
   4. 적용을 클릭합니다.

4. 쿼리 결과에서 시계열을 삭제하는 필터를 추가하려면 필터 요소를 사용합니다.

5. 데이터를 보는 방법을 구성합니다.
   

   측정항목의 측정값이 누적되면 측정항목 탐색기는 측정된 데이터를 정렬 기간에 따라 자동으로 정규화하므로 차트에 비율이 표시됩니다. 자세한 내용은 종류, 유형, 변환을 참조하세요.

   두 개의 counter 측정항목과 같이 정수 값 또는 Double 값이 측정되면 측정항목 탐색기가 모든 시계열을 자동으로 합산합니다. /multi 및 /single HTTP 경로의 데이터를 보려면 집계 항목의 첫 번째 메뉴를 없음으로 설정합니다.

   차트 구성에 대한 자세한 내용은 측정항목 탐색기 사용 시 측정항목 선택을 참조하세요.

trace 보기

trace 데이터를 사용할 수 있게 되기까지 몇 분 정도 걸릴 수 있습니다. 예를 들어 프로젝트에서 trace 데이터를 수신하면 Google Cloud Observability에서 해당 데이터를 저장할 데이터베이스를 만들어야 할 수 있습니다. 데이터베이스를 만드는 데 몇 분 정도 걸릴 수 있으며 이 기간에는 trace 데이터를 볼 수 없습니다.

trace 데이터를 보려면 다음을 수행합니다.

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

   Trace 탐색기로 이동

   검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

2. 페이지의 테이블 섹션에서 스팬 이름이 /multi인 행을 선택합니다.

3. trace 세부정보 패널의 Gantt 차트에서 /multi 라벨이 지정된 스팬을 선택합니다.

   HTTP 요청에 대한 정보가 표시된 패널이 열립니다. 이러한 세부정보에는 메서드, 상태 코드, 바이트 수, 호출자의 사용자 에이전트가 포함됩니다.

4. 이 trace와 연결된 로그를 보려면 로그 및 이벤트 탭을 선택합니다.

   탭에는 개별 로그가 표시됩니다. 로그 항목의 세부정보를 보려면 로그 항목을 펼칩니다. 로그 보기를 클릭하고 로그 탐색기를 사용하여 로그를 볼 수도 있습니다.

Cloud Trace 탐색기 사용에 대한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.

로그 보기

로그 탐색기에서 로그를 검사할 수 있으며 연결된 trace가 있는 경우 이를 볼 수도 있습니다.

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

   로그 탐색기로 이동

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

2. handle /multi request라는 설명이 포함된 로그를 찾습니다.

   로그 세부정보를 보려면 로그 항목을 확장합니다.

3. 'handle /multi request' 메시지가 있는 로그 항목에서 trace를 클릭한 후 trace 세부정보 보기를 선택합니다.

   trace 세부정보 패널이 열리고 선택한 trace가 표시됩니다.

   로그 데이터는 trace 데이터를 사용할 수 있기 몇 분 전에 사용할 수 있습니다. ID로 trace를 검색하거나 이 태스크의 단계를 따라 trace 데이터를 볼 때 오류가 발생하면 1~2분 정도 기다린 후 작업을 다시 시도하세요.

로그 탐색기 사용에 대한 자세한 내용은 로그 탐색기를 사용하여 로그 보기를 참조하세요.

다음 단계

• OpenTelemetry
• OTLP 사양
• 구조화된 로깅
• Managed Service for Prometheus 문제 해결
• Cloud Trace 문제 해결