Java의 생성형 AI 애플리케이션을 위한 실용적인 관측 가능성 기법

1. 개요

생성형 AI 애플리케이션에는 다른 애플리케이션과 마찬가지로 관측 가능성도 필요합니다. 생성형 AI에 특별한 관측 기술이 필요한가요?

이 실습에서는 간단한 생성형 AI 애플리케이션을 만듭니다. Cloud Run에 배포합니다. Google Cloud 관측 가능성 서비스 및 제품을 사용하여 필수 모니터링 및 로깅 기능으로 계측합니다.

학습할 내용

  • Cloud Shell 편집기를 사용하여 Vertex AI를 사용하는 애플리케이션 작성
  • GitHub에 애플리케이션 코드 저장
  • gcloud CLI를 사용하여 애플리케이션의 소스 코드를 Cloud Run에 배포
  • 생성형 AI 애플리케이션에 모니터링 및 로깅 기능 추가
  • 로그 기반 측정항목 사용
  • OpenTelemetry SDK로 로깅 및 모니터링 구현
  • 책임감 있는 AI 데이터 처리에 대한 유용한 정보 얻기

2. 기본 요건

아직 Google 계정이 없다면 새 계정을 만들어야 합니다.

3. 프로젝트 설정

  1. Google 계정으로 Google Cloud 콘솔에 로그인합니다.
  2. 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 방금 만들었거나 선택한 프로젝트의 프로젝트 ID를 기록합니다.
  3. 프로젝트에 결제를 사용 설정합니다.
    • 이 실습을 완료하는 데는 청구 비용이 $5 미만이 소요됩니다.
    • 이 실습의 끝에 있는 단계에 따라 리소스를 삭제하면 추가 비용이 발생하지 않습니다.
    • 신규 사용자는 미화 300달러 상당의 무료 체험판을 이용할 수 있습니다.
  4. Cloud Billing의 내 프로젝트에서 결제가 사용 설정되어 있는지 확인합니다.
    • 새 프로젝트의 Billing account 열에 Billing is disabled가 표시되면 다음 단계를 따르세요.
      1. Actions 열에서 점 3개를 클릭합니다.
      2. 결제 변경을 클릭합니다.
      3. 사용할 결제 계정을 선택합니다.
    • 라이브 이벤트에 참석하는 경우 계정 이름이 Google Cloud Platform 평가판 결제 계정일 수 있습니다.

4. Cloud Shell 편집기 준비

  1. Cloud Shell 편집기로 이동합니다. Cloud Shell에서 사용자 인증 정보로 gcloud를 호출하도록 승인하라는 메시지가 표시되면 승인을 클릭하여 계속합니다.
    Cloud Shell을 승인하려면 클릭합니다.
  2. 터미널 창 열기
    1. 햄버거 메뉴 햄버거 메뉴 아이콘를 클릭합니다.
    2. 터미널을 클릭합니다.
    3. 새 터미널
      Cloud Shell 편집기에서 새 터미널 열기을 클릭합니다.
  3. 터미널에서 프로젝트 ID를 구성합니다.
    gcloud config set project [PROJECT_ID]
    [PROJECT_ID]를 프로젝트 ID로 바꿉니다. 예를 들어 프로젝트 ID가 lab-example-project이면 명령어는 다음과 같습니다.
    gcloud config set project lab-project-id-example
    gcloud에서 GCPI API에 사용자 인증 정보를 요청한다는 메시지가 표시되면 승인을 클릭하여 계속 진행합니다.
    Cloud Shell을 승인하려면 클릭합니다.
    실행이 완료되면 다음 메시지가 표시됩니다.
    Updated property [core/project].
    WARNING이 표시되고 Do you want to continue (Y/N)? 메시지가 표시되면 프로젝트 ID를 잘못 입력했을 가능성이 큽니다. 올바른 프로젝트 ID를 찾은 후 N, Enter를 누르고 gcloud config set project 명령어를 다시 실행해 봅니다.
  4. (선택사항) 프로젝트 ID를 찾는 데 문제가 있는 경우 다음 명령어를 실행하여 생성 시간순으로 내림차순으로 정렬된 모든 프로젝트의 프로젝트 ID를 확인합니다.
    gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime

5. Google API 사용 설정

터미널에서 이 실습에 필요한 Google API를 사용 설정합니다.

gcloud services enable \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     aiplatform.googleapis.com \
     logging.googleapis.com \
     monitoring.googleapis.com \
     cloudtrace.googleapis.com

이 명령어는 완료하는 데 다소 시간이 걸립니다. 결국 다음과 비슷한 성공 메시지가 표시됩니다.

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

ERROR: (gcloud.services.enable) HttpError accessing으로 시작하고 아래와 같은 오류 세부정보가 포함된 오류 메시지가 표시되면 1~2분 후에 명령어를 다시 시도합니다.

"error": {
  "code": 429,
  "message": "Quota exceeded for quota metric 'Mutate requests' and limit 'Mutate requests per minute' of service 'serviceusage.googleapis.com' ...",
  "status": "RESOURCE_EXHAUSTED",
  ...
}

6. 생성형 AI 애플리케이션 만들기

이 단계에서는 Gemini 모델을 사용하여 선택한 동물에 관한 재미있는 사실 10가지를 보여주는 간단한 요청 기반 애플리케이션의 코드를 작성합니다. 다음 단계에 따라 애플리케이션 코드를 만듭니다.

  1. 터미널에서 codelab-o11y 디렉터리를 만듭니다.
    mkdir "${HOME}/codelab-o11y"
  2. 현재 디렉터리를 codelab-o11y로 변경합니다.
    cd "${HOME}/codelab-o11y"
  3. Spring 프레임워크 시작 조건을 사용하여 Java 애플리케이션의 부트스트랩 코드를 다운로드합니다.
    curl https://start.spring.io/starter.zip \
    -d dependencies=web \
    -d javaVersion=17 \
    -d type=maven-project \
    -d bootVersion=3.4.1 -o java-starter.zip
  4. 부트스트랩 코드를 현재 폴더로 보관 파일 해제합니다.
    unzip java-starter.zip
  5. 폴더에서 보관 파일을 삭제합니다.
    rm java-starter.zip
  6. project.toml 파일을 만들어 Cloud Run에 코드를 배포할 때 사용할 Java 런타임 버전을 정의합니다.
    cat > "${HOME}/codelab-o11y/project.toml" << EOF
[[build.env]]
    name = "GOOGLE_RUNTIME_VERSION"
    value = "17"
EOF
  7. pom.xml 파일에 Google Cloud SDK 종속 항목을 추가합니다.
    1. Google Cloud Core 패키지를 추가합니다.
      sed -i 's/<dependencies>/<dependencies>\
\
        <dependency>\
            <groupId>com.google.cloud<\/groupId>\
            <artifactId>google-cloud-core<\/artifactId>\
            <version>2.49.1<\/version>\
        <\/dependency>\
        /g' "${HOME}/codelab-o11y/pom.xml"
    2. Google Cloud Vertex AI 패키지를 추가합니다.
      sed -i 's/<dependencies>/<dependencies>\
\
        <dependency>\
            <groupId>com.google.cloud<\/groupId>\
            <artifactId>google-cloud-vertexai<\/artifactId>\
            <version>1.16.0<\/version>\
        <\/dependency>\
        /g' "${HOME}/codelab-o11y/pom.xml"
  8. Cloud Shell 편집기에서 DemoApplication.java 파일을 엽니다.
    cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/DemoApplication.java"
    이제 DemoApplication.java 파일의 스캐폴드된 소스 코드가 터미널 위의 편집기 창에 표시됩니다. 파일의 소스 코드는 다음과 비슷합니다.
    package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
  9. 편집기에서 코드를 아래에 표시된 버전으로 바꿉니다. 코드를 바꾸려면 파일의 콘텐츠를 삭제한 다음 아래 코드를 편집기에 복사합니다.
    package com.example.demo;

import java.io.IOException;
import java.util.Collections;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.google.cloud.ServiceOptions;
import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.api.GenerateContentResponse;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import com.google.cloud.vertexai.generativeai.ResponseHandler;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        String port = System.getenv().getOrDefault("PORT", "8080");
        SpringApplication app = new SpringApplication(DemoApplication.class);
        app.setDefaultProperties(Collections.singletonMap("server.port", port));
        app.run(args);
    }
}

@RestController
class HelloController {
    private final String projectId = ServiceOptions.getDefaultProjectId();
    private VertexAI vertexAI;
    private GenerativeModel model;

    @PostConstruct
    public void init() {
        vertexAI = new VertexAI(projectId, "us-central1");
        model = new GenerativeModel("gemini-1.5-flash", vertexAI);
    }

    @PreDestroy
    public void destroy() {
        vertexAI.close();
    }

    @GetMapping("/")
    public String getFacts(@RequestParam(defaultValue = "dog") String animal) throws IOException {
        String prompt = "Give me 10 fun facts about " + animal + ". Return this as html without backticks.";
        GenerateContentResponse response = model.generateContent(prompt);
        return ResponseHandler.getText(response);
    }
}
    몇 초 후 Cloud Shell 편집기에서 코드를 자동으로 저장합니다.

생성형 AI 애플리케이션의 코드를 Cloud Run에 배포합니다.

  1. 터미널 창에서 명령어를 실행하여 애플리케이션의 소스 코드를 Cloud Run에 배포합니다.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    명령어로 새 저장소가 생성된다는 알림이 아래와 같이 표시됩니다. Enter 아이콘을 클릭합니다.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    배포 프로세스는 최대 몇 분 정도 걸릴 수 있습니다. 배포 프로세스가 완료되면 다음과 같은 출력이 표시됩니다.
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. 표시된 Cloud Run 서비스 URL을 브라우저의 별도 탭 또는 창에 복사합니다. 또는 터미널에서 다음 명령어를 실행하여 서비스 URL을 출력하고 Ctrl 키를 누른 상태에서 표시된 URL을 클릭하여 URL을 엽니다.
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    URL을 열면 500 오류가 발생하거나 다음 메시지가 표시될 수 있습니다.
    Sorry, this is just a placeholder...
    서비스 배포가 완료되지 않았음을 의미합니다. 잠시 기다린 후 페이지를 새로고침하세요. 끝에는 재미있는 강아지 정보로 시작하는 텍스트와 강아지에 관한 재미있는 정보 10가지가 표시됩니다.

애플리케이션과 상호작용하여 다양한 동물에 관한 재미있는 사실을 알아보세요. 이렇게 하려면 animal 매개변수를 URL에 추가합니다(예: ?animal=[ANIMAL], 여기서 [ANIMAL]는 동물 이름임). 예를 들어 ?animal=cat를 추가하면 고양이에 관한 재미있는 사실 10가지를, ?animal=sea turtle를 추가하면 바다거북에 관한 재미있는 사실 10가지를 확인할 수 있습니다.

7. Vertex API 호출 감사

Google API 호출을 감사하면 '누가, 언제, 어디서, 특정 API를 호출했는지'와 같은 질문에 답할 수 있습니다. 감사는 애플리케이션 문제를 해결하거나, 리소스 사용량을 조사하거나, 소프트웨어 포렌식 분석을 수행할 때 중요합니다.

감사 로그를 사용하면 관리 및 시스템 활동을 추적하고 '데이터 읽기' 및 '데이터 쓰기' API 작업 호출을 로깅할 수 있습니다. 콘텐츠 생성을 위한 Vertex AI 요청을 감사하려면 Cloud 콘솔에서 '데이터 읽기' 감사 로그를 사용 설정해야 합니다.

  1. 아래 버튼을 클릭하여 Cloud 콘솔에서 감사 로그 페이지를 엽니다.

  2. 페이지에 이 실습용으로 만든 프로젝트가 선택되어 있는지 확인합니다. 선택한 프로젝트는 햄버거 메뉴 바로 옆에 있는 페이지 왼쪽 상단에 표시됩니다.
    Google Cloud 콘솔 프로젝트 드롭다운
    필요한 경우 콤보박스에서 올바른 프로젝트를 선택합니다.
  3. 데이터 액세스 감사 로그 구성 표의 서비스 열에서 Vertex AI API 서비스를 찾고 서비스 이름 왼쪽에 있는 체크박스를 선택하여 서비스를 선택합니다.
    Vertex AI API 선택
  4. 오른쪽의 정보 패널에서 '데이터 읽기' 감사 유형을 선택합니다.
    데이터 읽기 로그 확인
  5. 저장을 클릭합니다.

감사 로그를 생성하려면 서비스 URL을 엽니다. ?animal= 매개변수의 값을 변경하면서 페이지를 새로고침하여 다른 결과를 가져옵니다.

감사 로그 살펴보기

  1. 아래 버튼을 클릭하여 Cloud 콘솔에서 로그 탐색기 페이지를 엽니다.

  2. 다음 필터를 쿼리 창에 붙여넣습니다.
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
    쿼리 창은 로그 탐색기 페이지 상단에 있는 편집기입니다.
    감사 로그 쿼리
  3. 쿼리 실행을 클릭합니다.
  4. 감사 로그 항목 중 하나를 선택하고 필드를 펼쳐 로그에 캡처된 정보를 검사합니다.
    메서드 및 사용된 모델을 비롯한 Vertex API 호출에 관한 세부정보를 확인할 수 있습니다. 호출자의 ID와 호출을 승인한 권한도 확인할 수 있습니다.

8. 생성형 AI와의 상호작용 로깅

감사 로그에 API 요청 매개변수 또는 응답 데이터가 없습니다. 하지만 이 정보는 애플리케이션 및 워크플로 분석 문제를 해결하는 데 중요할 수 있습니다. 이 단계에서는 애플리케이션 로깅을 추가하여 이 공백을 메웁니다.

구현은 Spring Boot와 함께 Logback을 사용하여 애플리케이션 로그를 표준 출력에 출력합니다. 이 메서드는 표준 출력으로 출력된 정보를 캡처하고 Cloud Logging에 자동으로 처리하는 Cloud Run 기능을 사용합니다. 정보를 구조화된 데이터로 캡처하려면 출력된 로그의 형식을 적절하게 지정해야 합니다. 아래 안내에 따라 애플리케이션에 구조화된 로깅 기능을 추가합니다.

  1. 브라우저에서 'Cloud Shell' 창 (또는 탭)으로 돌아갑니다.
  2. Cloud Shell 편집기에서 새 파일 LoggingEventGoogleCloudEncoder.java를 만들고 엽니다.
    cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/LoggingEventGoogleCloudEncoder.java"
  3. 다음 코드를 복사하여 붙여넣어 Google Cloud 구조화된 로그 형식에 따라 로그를 문자열로 인코딩된 JSON으로 인코딩하는 Logback 인코더를 구현합니다.
    package com.example.demo;

import static ch.qos.logback.core.CoreConstants.UTF_8_CHARSET;

import java.time.Instant;
import ch.qos.logback.core.encoder.EncoderBase;
import ch.qos.logback.classic.Level;
import ch.qos.logback.classic.spi.ILoggingEvent;
import java.util.HashMap;

import com.google.gson.Gson;

public class LoggingEventGoogleCloudEncoder extends EncoderBase<ILoggingEvent>  {
    private static final byte[] EMPTY_BYTES = new byte[0];
    private final Gson gson = new Gson();

    @Override
    public byte[] headerBytes() {
        return EMPTY_BYTES;
    }

    @Override
    public byte[] encode(ILoggingEvent e) {
        var timestamp = Instant.ofEpochMilli(e.getTimeStamp());
        var fields = new HashMap<String, Object>() {
            {
                put("timestamp", timestamp.toString());
                put("severity", severityFor(e.getLevel()));
                put("message", e.getMessage());
            }
        };
        var params = e.getKeyValuePairs();
        if (params != null && params.size() > 0) {
            params.forEach(kv -> fields.putIfAbsent(kv.key, kv.value));
        }
        var data = gson.toJson(fields) + "\n";
        return data.getBytes(UTF_8_CHARSET);
    }

    @Override
    public byte[] footerBytes() {
        return EMPTY_BYTES;
    }

    private static String severityFor(Level level) {
        switch (level.toInt()) {
            case Level.TRACE_INT:
            return "DEBUG";
            case Level.DEBUG_INT:
            return "DEBUG";
            case Level.INFO_INT:
            return "INFO";
            case Level.WARN_INT:
            return "WARNING";
            case Level.ERROR_INT:
            return "ERROR";
            default:
            return "DEFAULT";
        }
    }
}
  4. Cloud Shell 편집기에서 새 파일 logback.xml를 만들고 엽니다.
    cloudshell edit "${HOME}/codelab-o11y/src/main/resources/logback.xml"
  5. 다음 XML을 복사하여 붙여넣어 Logback이 로그를 표준 출력으로 출력하는 Logback 어펜더와 함께 인코더를 사용하도록 Logback을 구성합니다.
    <?xml version="1.0" encoding="UTF-8"?>
<configuration debug="true">
    <appender name="Console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="com.example.demo.LoggingEventGoogleCloudEncoder"/>
    </appender>

    <root level="info">
        <appender-ref ref="Console" />
    </root>
</configuration>
  6. Cloud Shell 편집기에서 DemoApplication.java 파일을 다시 엽니다.
    cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/DemoApplication.java"
  7. 편집기의 코드를 아래에 표시된 버전으로 바꾸어 생성형 AI 요청 및 응답을 로깅합니다. 코드를 바꾸려면 파일의 콘텐츠를 삭제한 다음 아래 코드를 편집기에 복사합니다.
    package com.example.demo;

import java.io.IOException;
import java.util.Collections;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.google.cloud.ServiceOptions;
import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.api.GenerateContentResponse;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import com.google.cloud.vertexai.generativeai.ResponseHandler;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        String port = System.getenv().getOrDefault("PORT", "8080");
        SpringApplication app = new SpringApplication(DemoApplication.class);
        app.setDefaultProperties(Collections.singletonMap("server.port", port));
        app.run(args);
    }
}

@RestController
class HelloController {
    private final String projectId = ServiceOptions.getDefaultProjectId();
    private VertexAI vertexAI;
    private GenerativeModel model;
    private final Logger LOGGER = LoggerFactory.getLogger(HelloController.class);

    @PostConstruct
    public void init() {
        vertexAI = new VertexAI(projectId, "us-central1");
        model = new GenerativeModel("gemini-1.5-flash", vertexAI);
    }

    @PreDestroy
    public void destroy() {
        vertexAI.close();
    }

    @GetMapping("/")
    public String getFacts(@RequestParam(defaultValue = "dog") String animal) throws IOException {
        String prompt = "Give me 10 fun facts about " + animal + ". Return this as html without backticks.";
        GenerateContentResponse response = model.generateContent(prompt);
        LOGGER.atInfo()
                .addKeyValue("animal", animal)
                .addKeyValue("prompt", prompt)
                .addKeyValue("response", response)
                .log("Content is generated");
        return ResponseHandler.getText(response);
    }
}

몇 초 후 Cloud Shell 편집기에서 변경사항을 자동으로 저장합니다.

생성형 AI 애플리케이션의 코드를 Cloud Run에 배포합니다.

  1. 터미널 창에서 명령어를 실행하여 애플리케이션의 소스 코드를 Cloud Run에 배포합니다.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    명령어로 새 저장소가 생성된다는 알림이 아래와 같이 표시됩니다. Enter 아이콘을 클릭합니다.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    배포 프로세스는 최대 몇 분 정도 걸릴 수 있습니다. 배포 프로세스가 완료되면 다음과 같은 출력이 표시됩니다.
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. 표시된 Cloud Run 서비스 URL을 브라우저의 별도 탭 또는 창에 복사합니다. 또는 터미널에서 다음 명령어를 실행하여 서비스 URL을 출력하고 Ctrl 키를 누른 상태에서 표시된 URL을 클릭하여 URL을 엽니다.
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    URL을 열면 500 오류가 발생하거나 다음 메시지가 표시될 수 있습니다.
    Sorry, this is just a placeholder...
    서비스 배포가 완료되지 않았음을 의미합니다. 잠시 기다린 후 페이지를 새로고침하세요. 끝에는 재미있는 강아지 정보로 시작하는 텍스트와 강아지에 관한 재미있는 정보 10가지가 표시됩니다.

애플리케이션 로그를 생성하려면 서비스 URL을 엽니다. ?animal= 매개변수의 값을 변경하면서 페이지를 새로고침하여 다른 결과를 가져옵니다.
애플리케이션 로그를 보려면 다음 단계를 따르세요.

  1. 아래 버튼을 클릭하여 Cloud 콘솔에서 로그 탐색기 페이지를 엽니다.

  2. 다음 필터를 쿼리 창(로그 탐색기 인터페이스의 2번)에 붙여넣습니다.
    LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
  3. 쿼리 실행을 클릭합니다.

쿼리 결과에는 프롬프트와 안전 등급을 포함한 Vertex AI 응답이 포함된 로그가 표시됩니다.

9. 생성형 AI와의 상호작용 수 집계

Cloud Run은 배포된 서비스를 모니터링하는 데 사용할 수 있는 관리형 측정항목을 기록합니다. 사용자 관리 모니터링 측정항목을 사용하면 데이터와 측정항목 업데이트 빈도를 더 효과적으로 관리할 수 있습니다. 이러한 측정항목을 구현하려면 데이터를 수집하여 Cloud Monitoring에 작성하는 코드를 작성해야 합니다. OpenTelemetry SDK를 사용하여 구현하는 방법은 다음 (선택사항) 단계를 참고하세요.

이 단계에서는 코드에 사용자 측정항목을 구현하는 대안인 로그 기반 측정항목을 보여줍니다. 로그 기반 측정항목을 사용하면 애플리케이션이 Cloud Logging에 작성하는 로그 항목에서 모니터링 측정항목을 생성할 수 있습니다. 이전 단계에서 구현한 애플리케이션 로그를 사용하여 유형 카운터의 로그 기반 측정항목을 정의합니다. 이 측정항목은 Vertex API를 성공적으로 호출한 횟수를 집계합니다.

  1. 이전 단계에서 사용한 로그 탐색기 창을 살펴봅니다. 쿼리 창에서 작업 드롭다운 메뉴를 찾아 클릭하여 엽니다. 아래 스크린샷을 참고하여 메뉴를 찾습니다.
    작업 드롭다운 메뉴가 있는 쿼리 결과 툴바
  2. 열린 메뉴에서 측정항목 만들기를 선택하여 로그 기반 측정항목 만들기 패널을 엽니다.
  3. 로그 기반 측정항목 만들기 패널에서 새 카운터 측정항목을 구성하려면 다음 단계를 따르세요.
    1. 측정항목 유형 설정: 카운터를 선택합니다.
    2. 세부정보 섹션에서 다음 필드를 설정합니다.
      • 로그 측정항목 이름: 이름을 model_interaction_count로 설정합니다. 이름 지정 시 특정 제한사항이 적용됩니다. 자세한 내용은 이름 지정 제한사항 문제 해결을 참고하세요.
      • 설명: 측정항목에 대한 설명을 입력합니다. 예를 들면 Number of log entries capturing successful call to model inference.입니다.
      • 단위: 이 필드를 공백으로 남겨두거나 숫자 1을 삽입하세요.
    3. 필터 선택 섹션의 값은 그대로 둡니다. 빌드 필터 필드에는 애플리케이션 로그를 확인하는 데 사용한 것과 동일한 필터가 있습니다.
    4. (선택사항) 각 동물의 호출 수를 집계하는 데 도움이 되는 라벨을 추가합니다. 참고: 이 라벨은 측정항목의 카디널리티를 크게 늘릴 수 있으며 프로덕션에서는 사용하지 않는 것이 좋습니다.
      1. 라벨 추가를 클릭합니다.
      2. 라벨 섹션에서 다음 필드를 설정합니다.
        • 라벨 이름: 이름을 animal로 설정합니다.
        • 설명: 라벨에 대한 설명을 입력합니다. 예를 들면 Animal parameter입니다.
        • 라벨 유형: STRING를 선택합니다.
        • 필드 이름: jsonPayload.animal을 입력합니다.
        • 정규 표현식: 비워둡니다.
      3. 완료를 클릭합니다.
    5. 측정항목 만들기를 클릭하여 측정항목을 만듭니다.

gcloud logging metrics create CLI 명령어를 사용하거나 google_logging_metric Terraform 리소스를 사용하여 로그 기반 측정항목 페이지에서 로그 기반 측정항목을 만들 수도 있습니다.

측정항목 데이터를 생성하려면 서비스 URL을 엽니다. 열린 페이지를 여러 번 새로고침하여 모델을 여러 번 호출합니다. 이전과 마찬가지로 매개변수에 다른 동물을 사용해 봅니다.

PromQL 쿼리를 입력하여 로그 기반 측정항목 데이터를 검색합니다. PromQL 쿼리를 입력하려면 다음 단계를 따르세요.

  1. 아래 버튼을 클릭하여 Cloud 콘솔에서 측정항목 탐색기 페이지를 엽니다.

  2. 쿼리 빌더 창의 툴바에서 이름이 < > MQL 또는 < > PromQL인 버튼을 선택합니다. 버튼 위치는 아래 그림을 참고하세요.
    측정항목 탐색기의 MQL 버튼 위치
  3. 언어 전환 버튼에 PromQL이 선택되어 있는지 확인합니다. 언어 전환 버튼은 쿼리 형식을 지정할 수 있는 동일한 툴바에 있습니다.
  4. 쿼리 편집기에 쿼리를 입력합니다.
    sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
    PromQL 사용에 관한 자세한 내용은 Cloud Monitoring의 PromQL을 참고하세요.
  5. 쿼리 실행을 클릭합니다. 다음 스크린샷과 유사한 선 차트가 표시됩니다.
    쿼리된 측정항목 표시

    자동 실행 전환 버튼이 사용 설정된 경우 쿼리 실행 버튼이 표시되지 않습니다.

10. (선택사항) 모니터링 및 추적에 Open Telemetry 사용

이전 단계에서 언급했듯이 OpenTelemetry (Otel) SDK를 사용하여 측정항목을 구현할 수 있습니다. 멀티 서비스 아키텍처에서 OTel을 사용하는 것이 좋습니다. 이 단계에서는 Spring Boot 애플리케이션에 OTel 계측을 추가하는 방법을 보여줍니다. 이 단계에서는 다음을 수행합니다.

  • 자동 추적 기능으로 Spring Boot 애플리케이션 계측
  • 성공적인 모델 호출 횟수를 모니터링하는 카운터 측정항목 구현
  • 추적과 애플리케이션 로그의 상관관계 파악

제품 수준 서비스에 권장되는 아키텍처는 OTel 수집기를 사용하여 여러 서비스의 모든 관측 가능성 데이터를 수집하고 처리하는 것입니다. 이 단계의 코드는 편의상 수집기를 사용하지 않습니다. 대신 Google Cloud에 데이터를 직접 쓰는 OTel 내보내기를 사용합니다.

OTel 구성요소 및 자동 추적을 사용하여 Spring Boot 애플리케이션 설정

  1. 브라우저에서 'Cloud Shell' 창 (또는 탭)으로 돌아갑니다.
  2. 터미널에서 추가 구성 매개변수를 사용하여 application.permissions 파일을 업데이트합니다.
    cat >> "${HOME}/codelab-o11y/src/main/resources/application.properties" << EOF
otel.logs.exporter=none
otel.traces.exporter=google_cloud_trace
otel.metrics.exporter=google_cloud_monitoring
otel.resource.attributes.service.name=codelab-o11y-service
otel.traces.sampler=always_on
EOF
    이 매개변수는 관측 가능성 데이터를 Cloud Trace 및 Cloud Monitoring으로 내보내는 것을 정의하고 모든 트레이스 샘플링을 적용합니다.
  3. 필요한 OpenTelemetry 종속 항목을 pom.xml 파일에 추가합니다.
    sed -i 's/<dependencies>/<dependencies>\
\
        <dependency>\
            <groupId>io.opentelemetry.instrumentation<\/groupId>\
            <artifactId>opentelemetry-spring-boot-starter<\/artifactId>\
        <\/dependency>\
        <dependency>\
            <groupId>com.google.cloud.opentelemetry<\/groupId>\
            <artifactId>exporter-auto<\/artifactId>\
            <version>0.33.0-alpha<\/version>\
        <\/dependency>\
        <dependency>\
            <groupId>com.google.cloud.opentelemetry<\/groupId>\
            <artifactId>exporter-trace<\/artifactId>\
            <version>0.33.0<\/version>\
        <\/dependency>\
        <dependency>\
            <groupId>com.google.cloud.opentelemetry<\/groupId>\
            <artifactId>exporter-metrics<\/artifactId>\
            <version>0.33.0<\/version>\
        <\/dependency>\
/g' "${HOME}/codelab-o11y/pom.xml"
  4. OpenTelemetry BOM을 pom.xml 파일에 추가합니다.
    sed -i 's/<\/properties>/<\/properties>\
    <dependencyManagement>\
        <dependencies>\
            <dependency>\
                <groupId>io.opentelemetry.instrumentation<\/groupId>\
                <artifactId>opentelemetry-instrumentation-bom<\/artifactId>\
                <version>2.12.0<\/version>\
                <type>pom<\/type>\
                <scope>import<\/scope>\
            <\/dependency>\
        <\/dependencies>\
    <\/dependencyManagement>\
/g' "${HOME}/codelab-o11y/pom.xml"
  5. Cloud Shell 편집기에서 DemoApplication.java 파일을 다시 엽니다.
    cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/DemoApplication.java"
  6. 현재 코드를 실적 측정항목을 증가시키는 버전으로 바꿉니다. 코드를 바꾸려면 파일의 콘텐츠를 삭제한 다음 아래 코드를 편집기에 복사합니다.
    package com.example.demo;

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.metrics.LongCounter;

import java.io.IOException;
import java.util.Collections;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.google.cloud.ServiceOptions;
import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.api.GenerateContentResponse;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import com.google.cloud.vertexai.generativeai.ResponseHandler;


@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        String port = System.getenv().getOrDefault("PORT", "8080");
        SpringApplication app = new SpringApplication(DemoApplication.class);
        app.setDefaultProperties(Collections.singletonMap("server.port", port));
        app.run(args);
    }
}

@RestController
class HelloController {
    private final String projectId = ServiceOptions.getDefaultProjectId();
    private VertexAI vertexAI;
    private GenerativeModel model;
    private final Logger LOGGER = LoggerFactory.getLogger(HelloController.class);
    private static final String INSTRUMENTATION_NAME = "genai-o11y/java/workshop/example";
    private static final AttributeKey<String> ANIMAL = AttributeKey.stringKey("animal");
    private final LongCounter counter;

    public HelloController(OpenTelemetry openTelemetry) {
        this.counter = openTelemetry.getMeter(INSTRUMENTATION_NAME)
                .counterBuilder("model_call_counter")
                .setDescription("Number of successful model calls")
                .build();
    }

    @PostConstruct
    public void init() {
        vertexAI = new VertexAI(projectId, "us-central1");
        model = new GenerativeModel("gemini-1.5-flash", vertexAI);
    }

    @PreDestroy
    public void destroy() {
        vertexAI.close();
    }

    @GetMapping("/")
    public String getFacts(@RequestParam(defaultValue = "dog") String animal) throws IOException {
        String prompt = "Give me 10 fun facts about " + animal + ". Return this as html without backticks.";
        GenerateContentResponse response = model.generateContent(prompt);
        LOGGER.atInfo()
                .addKeyValue("animal", animal)
                .addKeyValue("prompt", prompt)
                .addKeyValue("response", response)
                .log("Content is generated");
        counter.add(1, Attributes.of(ANIMAL, animal));
        return ResponseHandler.getText(response);
    }
}
  7. Cloud Shell 편집기에서 LoggingEventGoogleCloudEncoder.java 파일을 다시 엽니다.
    cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/LoggingEventGoogleCloudEncoder.java"
  8. 현재 코드를 작성된 로그에 추적 속성을 추가하는 버전으로 바꿉니다. 이 속성을 추가하면 로그를 올바른 트레이스 스팬과 연결할 수 있습니다. 코드를 바꾸려면 파일의 콘텐츠를 삭제한 다음 아래 코드를 편집기에 복사합니다.
    package com.example.demo;

import static ch.qos.logback.core.CoreConstants.UTF_8_CHARSET;

import java.time.Instant;
import java.util.HashMap;

import ch.qos.logback.core.encoder.EncoderBase;
import ch.qos.logback.classic.Level;
import ch.qos.logback.classic.spi.ILoggingEvent;
import com.google.cloud.ServiceOptions;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.context.Context;

import com.google.gson.Gson;


public class LoggingEventGoogleCloudEncoder extends EncoderBase<ILoggingEvent>  {
    private static final byte[] EMPTY_BYTES = new byte[0];
    private final Gson gson;
    private final String projectId;
    private final String tracePrefix;


    public LoggingEventGoogleCloudEncoder() {
        this.gson = new Gson();
        this.projectId = lookUpProjectId();
        this.tracePrefix = "projects/" + (projectId == null ? "" : projectId) + "/traces/";
    }

    private static String lookUpProjectId() {
        return ServiceOptions.getDefaultProjectId();
    }

    @Override
    public byte[] headerBytes() {
        return EMPTY_BYTES;
    }

    @Override
    public byte[] encode(ILoggingEvent e) {
        var timestamp = Instant.ofEpochMilli(e.getTimeStamp());
        var fields = new HashMap<String, Object>() {
            {
                put("timestamp", timestamp.toString());
                put("severity", severityFor(e.getLevel()));
                put("message", e.getMessage());
                SpanContext context = Span.fromContext(Context.current()).getSpanContext();
                if (context.isValid()) {
                    put("logging.googleapis.com/trace", tracePrefix + context.getTraceId());
                    put("logging.googleapis.com/spanId", context.getSpanId());
                    put("logging.googleapis.com/trace_sampled", Boolean.toString(context.isSampled()));
                }
            }
        };
        var params = e.getKeyValuePairs();
        if (params != null && params.size() > 0) {
            params.forEach(kv -> fields.putIfAbsent(kv.key, kv.value));
        }
        var data = gson.toJson(fields) + "\n";
        return data.getBytes(UTF_8_CHARSET);
    }

    @Override
    public byte[] footerBytes() {
        return EMPTY_BYTES;
    }

    private static String severityFor(Level level) {
        switch (level.toInt()) {
            case Level.TRACE_INT:
            return "DEBUG";
            case Level.DEBUG_INT:
            return "DEBUG";
            case Level.INFO_INT:
            return "INFO";
            case Level.WARN_INT:
            return "WARNING";
            case Level.ERROR_INT:
            return "ERROR";
            default:
            return "DEFAULT";
        }
    }
}

몇 초 후 Cloud Shell 편집기에서 변경사항을 자동으로 저장합니다.

생성형 AI 애플리케이션의 코드를 Cloud Run에 배포합니다.

  1. 터미널 창에서 명령어를 실행하여 애플리케이션의 소스 코드를 Cloud Run에 배포합니다.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    명령어로 새 저장소가 생성된다는 알림이 아래와 같이 표시됩니다. Enter 아이콘을 클릭합니다.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    배포 프로세스는 최대 몇 분 정도 걸릴 수 있습니다. 배포 프로세스가 완료되면 다음과 같은 출력이 표시됩니다.
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. 표시된 Cloud Run 서비스 URL을 브라우저의 별도 탭 또는 창에 복사합니다. 또는 터미널에서 다음 명령어를 실행하여 서비스 URL을 출력하고 Ctrl 키를 누른 상태에서 표시된 URL을 클릭하여 URL을 엽니다.
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    URL을 열면 500 오류가 발생하거나 다음 메시지가 표시될 수 있습니다.
    Sorry, this is just a placeholder...
    서비스 배포가 완료되지 않았음을 의미합니다. 잠시 기다린 후 페이지를 새로고침하세요. 끝에는 재미있는 강아지 정보로 시작하는 텍스트와 강아지에 관한 재미있는 정보 10가지가 표시됩니다.

원격 분석 데이터를 생성하려면 서비스 URL을 엽니다. ?animal= 매개변수의 값을 변경하면서 페이지를 새로고침하여 다른 결과를 가져옵니다.

애플리케이션 트레이스 살펴보기

  1. 아래 버튼을 클릭하여 Cloud 콘솔에서 Trace 탐색기 페이지를 엽니다.

  2. 가장 최근 트레이스 중 하나를 선택합니다. 아래 스크린샷과 같이 5~6개의 스팬이 표시됩니다.
    Trace 탐색기의 앱 스팬 뷰
  3. 이벤트 핸들러 (fun_facts 메서드) 호출을 추적하는 스팬을 찾습니다. 이름이 /인 마지막 스팬입니다.
  4. 트레이스 세부정보 창에서 로그 및 이벤트를 선택합니다. 이 특정 스팬과 상관관계가 있는 애플리케이션 로그가 표시됩니다. 상관관계는 트레이스 및 로그의 트레이스 및 스팬 ID를 사용하여 감지됩니다. 프롬프트를 작성한 애플리케이션 로그와 Vertex API의 응답이 표시됩니다.

카운터 측정항목 살펴보기

  1. 아래 버튼을 클릭하여 Cloud 콘솔에서 측정항목 탐색기 페이지를 엽니다.

  2. 쿼리 빌더 창의 툴바에서 이름이 < > MQL 또는 < > PromQL인 버튼을 선택합니다. 버튼 위치는 아래 그림을 참고하세요.
    측정항목 탐색기의 MQL 버튼 위치
  3. 언어 전환 버튼에 PromQL이 선택되어 있는지 확인합니다. 언어 전환 버튼은 쿼리 형식을 지정할 수 있는 동일한 툴바에 있습니다.
  4. 쿼리 편집기에 쿼리를 입력합니다.
    sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
  5. 쿼리 실행을 클릭합니다.자동 실행 전환 버튼이 사용 설정되어 있으면 쿼리 실행 버튼이 표시되지 않습니다.

11. (선택사항) 로그에서 난독화된 민감한 정보

10단계에서 애플리케이션이 Gemini 모델과 상호작용하는 정보가 로깅되었습니다. 이 정보에는 동물의 이름, 실제 프롬프트, 모델의 응답이 포함되었습니다. 이 정보를 로그에 저장하는 것은 안전하지만 다른 많은 시나리오에서는 필요하지 않습니다. 프롬프트에는 사용자가 저장하고 싶지 않은 개인 정보 또는 민감한 정보가 포함될 수 있습니다. 이 문제를 해결하려면 Cloud Logging에 기록되는 민감한 정보를 난독화하면 됩니다. 코드 수정을 최소화하려면 다음 솔루션을 사용하는 것이 좋습니다.

  1. 수신 로그 항목을 저장할 PubSub 주제 만들기
  2. 처리된 로그를 PubSub 주제로 리디렉션하는 로그 싱크를 만듭니다.
  3. 다음 단계에 따라 PubSub 주제로 리디렉션된 로그를 수정하는 Dataflow 파이프라인을 만듭니다.
    1. Pub/Sub 주제에서 로그 항목 읽기
    2. DLP 검사 API를 사용하여 항목의 페이로드에서 민감한 정보를 검사합니다.
    3. DLP 수정 방법 중 하나를 사용하여 페이로드의 민감한 정보를 수정합니다.
    4. 난독화된 로그 항목을 Cloud Logging에 작성
  4. 파이프라인 배포

12. (선택사항) 정리

Codelab에서 사용한 리소스와 API에 대한 비용이 청구되지 않도록 하려면 실습을 완료한 후 정리하는 것이 좋습니다. 비용이 청구되지 않도록 하는 가장 쉬운 방법은 Codelab에서 만든 프로젝트를 삭제하는 것입니다.

  1. 프로젝트를 삭제하려면 터미널에서 delete project 명령어를 실행합니다.
    PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet
    클라우드 프로젝트를 삭제하면 해당 프로젝트 내에서 사용되는 모든 리소스 및 API에 대한 청구가 중지됩니다. 다음 메시지가 표시되며 여기서 PROJECT_ID는 프로젝트 ID입니다.
    Deleted [https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID].

You can undo this operation for a limited period by running the command below.
    $ gcloud projects undelete PROJECT_ID

See https://cloud.google.com/resource-manager/docs/creating-managing-projects for information on shutting down projects.
  2. (선택사항) 오류가 발생하면 5단계를 참고하여 실습 중에 사용한 프로젝트 ID를 찾습니다. 첫 번째 안내의 명령어로 대체합니다. 예를 들어 프로젝트 ID가 lab-example-project이면 명령어는 다음과 같습니다.
    gcloud projects delete lab-project-id-example --quiet

13. 축하합니다

이 실습에서는 Gemini 모델을 사용하여 예측하는 생성형 AI 애플리케이션을 만들었습니다. 필수 모니터링 및 로깅 기능으로 애플리케이션을 계측했습니다. 애플리케이션과 소스 코드의 변경사항을 Cloud Run에 배포했습니다. 그런 다음 Google Cloud Observability 제품을 사용하여 애플리케이션의 성능을 추적하여 애플리케이션의 안정성을 보장할 수 있습니다.

현재 사용 중인 제품을 개선하기 위한 사용자 경험 (UX) 연구에 참여하고 싶다면 여기에서 등록하세요.

다음은 학습을 계속할 수 있는 몇 가지 방법입니다.