Teknik observasi praktis untuk aplikasi AI Generatif di Java

1. Ringkasan

Aplikasi AI generatif memerlukan visibilitas seperti aplikasi lainnya. Apakah ada teknik visibilitas khusus yang diperlukan untuk AI Generatif?

Di lab ini, Anda akan membuat aplikasi AI Generatif sederhana. Deploy ke Cloud Run. Dan lengkapi dengan kemampuan pemantauan dan logging penting menggunakan layanan dan produk observabilitas Google Cloud.

Yang akan Anda pelajari

• Menulis aplikasi yang menggunakan Vertex AI dengan Cloud Shell Editor
• Menyimpan kode aplikasi di GitHub
• Menggunakan gcloud CLI untuk men-deploy kode sumber aplikasi ke Cloud Run

• Menambahkan kemampuan pemantauan dan logging ke aplikasi Gen AI
• Menggunakan metrik berbasis log
• Menerapkan logging dan pemantauan dengan Open Telemetry SDK
• Dapatkan insight tentang penanganan data responsible AI

2. Prasyarat

Jika belum memiliki Akun Google, Anda harus membuat akun baru.

Gunakan akun pribadi, bukan akun kantor atau sekolah. Akun kerja dan sekolah mungkin memiliki batasan yang mencegah Anda mengaktifkan API yang diperlukan untuk lab ini.

3. Penyiapan project

1. Login ke Konsol Google Cloud dengan Akun Google Anda.
2. Buat project baru atau pilih untuk menggunakan kembali project yang ada. Catat project ID project yang baru saja Anda buat atau pilih.
3. Aktifkan penagihan untuk project.
   • Menyelesaikan lab ini akan dikenai biaya penagihan kurang dari $5.
   • Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource guna menghindari tagihan lebih lanjut.
   • Pengguna baru memenuhi syarat untuk Uji Coba Gratis senilai$300 USD.
4. Pastikan penagihan diaktifkan di Project saya di Penagihan Cloud
   • Jika project baru Anda bertuliskan Billing is disabled di kolom Billing account:
     1. Klik tiga titik di kolom Actions
     2. Klik Ubah penagihan
     3. Pilih akun penagihan yang ingin Anda gunakan
   • Jika Anda menghadiri acara live, akun tersebut kemungkinan akan diberi nama Akun Penagihan Uji Coba Google Cloud Platform

Jika Anda menghadiri workshop langsung, dapatkan kredit sebesar$5 USD untuk digunakan sebagai akun penagihan untuk lab ini.
CATATAN: Kredit hanya tersedia pada hari workshop dan jumlah kredit terbatas.

4. Menyiapkan Cloud Shell Editor

1. Buka Cloud Shell Editor. Jika Anda melihat pesan berikut, yang meminta untuk memberikan otorisasi pada Cloud Shell agar dapat memanggil gcloud dengan kredensial Anda, klik Authorize untuk melanjutkan.
   
2. Buka jendela terminal
   1. Klik menu tiga garis
   2. Klik Terminal
   3. Klik New Terminal
      
3. Di terminal, konfigurasikan project ID Anda:

   gcloud config set project [PROJECT_ID]
   

   Ganti [PROJECT_ID] dengan ID project Anda. Misalnya, jika project ID Anda adalah lab-example-project, perintahnya adalah:

   gcloud config set project lab-project-id-example
   

   Jika Anda melihat pesan berikut, yang menyatakan bahwa gcloud meminta kredensial Anda ke GCPI API, klik Authorize untuk melanjutkan.
   
   Jika berhasil dieksekusi, Anda akan melihat pesan berikut:

   Updated property [core/project].
   

   Jika Anda melihat WARNING dan ditanya Do you want to continue (Y/N)?, berarti Anda mungkin salah memasukkan project ID. Tekan N, tekan Enter, dan coba jalankan perintah gcloud config set project lagi setelah Anda menemukan project ID yang benar.
4. (Opsional) Jika Anda mengalami masalah saat menemukan project ID, jalankan perintah berikut untuk melihat project ID semua project Anda yang diurutkan berdasarkan waktu pembuatan dalam urutan menurun:

   gcloud projects list \
        --format='value(projectId,createTime)' \
        --sort-by=~createTime
   

5. Mengaktifkan Google API

Di terminal, aktifkan Google API yang diperlukan untuk lab ini:

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

Pemrosesan perintah ini memerlukan waktu beberapa saat. Pada akhirnya, perintah ini akan menampilkan pesan sukses yang mirip dengan pesan berikut:

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

Jika Anda menerima pesan error yang diawali dengan ERROR: (gcloud.services.enable) HttpError accessing dan berisi detail error seperti di bawah, coba lagi perintah setelah penundaan 1-2 menit.

"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. Membuat aplikasi AI Generatif

Pada langkah ini, Anda akan menulis kode aplikasi berbasis permintaan sederhana yang menggunakan model Gemini untuk menampilkan 10 fakta menarik tentang hewan pilihan Anda. Lakukan hal berikut untuk membuat kode aplikasi.

1. Di terminal, buat direktori codelab-o11y:

   mkdir "${HOME}/codelab-o11y"
   

2. Ubah direktori saat ini menjadi codelab-o11y:

   cd "${HOME}/codelab-o11y"
   

3. Download kode bootstrap aplikasi Java menggunakan pemicu framework Spring:

   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. Ekstrak kode bootstrap ke folder saat ini:

   unzip java-starter.zip
   

5. Dan hapus file arsip dari folder:

   rm java-starter.zip
   

6. Buat file project.toml untuk menentukan versi Java Runtime yang akan digunakan saat men-deploy kode ke Cloud Run:

   cat > "${HOME}/codelab-o11y/project.toml" << EOF
   [[build.env]]
       name = "GOOGLE_RUNTIME_VERSION"
       value = "17"
   EOF
   

7. Tambahkan dependensi Google Cloud SDK ke file pom.xml:
   1. Tambahkan paket 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. Tambahkan paket 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. Buka file DemoApplication.java di Cloud Shell Editor:

   cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/DemoApplication.java"
   

   Kode sumber file DemoApplication.java yang dibuat scaffold kini akan muncul di jendela editor di atas terminal. Kode sumber file akan mirip dengan kode berikut:

   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. Ganti kode di editor dengan versi yang ditampilkan di bawah. Untuk mengganti kode, hapus konten file, lalu salin kode di bawah ke editor:

   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);
       }
   }
   

   Setelah beberapa detik, Editor Cloud Shell akan otomatis menyimpan kode Anda.

Men-deploy kode aplikasi AI Generatif ke Cloud Run

1. Di jendela terminal, jalankan perintah untuk men-deploy kode sumber aplikasi ke Cloud Run.

   gcloud run deploy codelab-o11y-service \
        --source="${HOME}/codelab-o11y/" \
        --region=us-central1 \
        --allow-unauthenticated
   

   Jika Anda melihat perintah seperti di bawah ini, yang memberi tahu Anda bahwa perintah tersebut akan membuat repositori baru. Klik 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)?
   

   Proses deployment dapat memerlukan waktu hingga beberapa menit. Setelah proses deployment selesai, Anda akan melihat output seperti:

   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. Salin URL layanan Cloud Run yang ditampilkan ke tab atau jendela terpisah di browser Anda. Atau, jalankan perintah berikut di terminal untuk mencetak URL layanan dan klik URL yang ditampilkan sambil menahan tombol Ctrl untuk membuka URL:

   gcloud run services list \
        --format='value(URL)' \
        --filter='SERVICE:"codelab-o11y-service"'
   

   Saat URL dibuka, Anda mungkin mendapatkan error 500 atau melihat pesan:

   Sorry, this is just a placeholder...
   

   Artinya, layanan tidak menyelesaikan deployment-nya. Tunggu beberapa saat, lalu muat ulang halaman. Di bagian akhir, Anda akan melihat teks yang diawali dengan Fakta Menarik tentang dan berisi 10 fakta menarik tentang.

Coba berinteraksi dengan aplikasi untuk mendapatkan fakta menarik tentang berbagai hewan. Untuk melakukannya, tambahkan parameter animal ke URL, seperti ?animal=[ANIMAL] dengan [ANIMAL] adalah nama hewan. Misalnya, tambahkan ?animal=cat untuk mendapatkan 10 fakta menarik tentang kucing atau ?animal=sea turtle untuk mendapatkan 10 fakta menarik tentang penyu.

Biarkan tab (atau jendela) URL layanan ini tetap terbuka karena Anda akan memerlukannya dalam langkah-langkah berikut.

7. Mengaudit panggilan Vertex API Anda

Mengaudit panggilan Google API akan memberikan jawaban atas pertanyaan seperti "Siapa yang memanggil API tertentu, di mana, dan kapan?". Auditing penting saat Anda memecahkan masalah aplikasi, menyelidiki penggunaan resource, atau melakukan analisis forensik software.

Log audit memungkinkan Anda melacak aktivitas administratif dan sistem serta mencatat panggilan ke operasi API "pembacaan data" dan "penulisan data". Untuk mengaudit permintaan Vertex AI guna membuat konten, Anda harus mengaktifkan log audit "Pembacaan Data" di konsol Cloud.

Mengaktifkan log audit "Pembacaan Data" dapat menimbulkan biaya tambahan.

1. Klik tombol di bawah untuk membuka halaman Log Audit di konsol Cloud
   Buka Log Audit
   
2. Pastikan halaman memiliki project yang Anda buat untuk lab ini dipilih. Project yang dipilih ditampilkan di pojok kiri atas halaman tepat dari menu tiga garis:
   
   Jika perlu, pilih project yang benar dari combobox.
3. Di tabel Data Access audit logs configuration, di kolom Service, temukan layanan Vertex AI API dan pilih layanan dengan mencentang kotak yang terletak di sebelah kiri nama layanan.
   
4. Di panel info di sebelah kanan, pilih jenis audit "Data Read".
   
5. Klik Simpan.

Untuk membuat log audit, buka URL layanan. Muat ulang halaman sambil mengubah nilai parameter ?animal= untuk mendapatkan hasil yang berbeda.

Menjelajahi log audit

1. Klik tombol di bawah untuk membuka halaman Logs Explorer di Cloud Console:
   Buka Logs Explorer
   
2. Tempel filter berikut ke dalam panel Kueri.

   LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
   protoPayload.serviceName="aiplatform.googleapis.com"
   

   Panel Kueri adalah editor yang terletak di dekat bagian atas halaman Logs Explorer:
   
3. Klik Run query.
4. Pilih salah satu entri log audit dan luaskan kolom untuk memeriksa informasi yang dicatat dalam log.
   Anda dapat melihat detail tentang panggilan Vertex API, termasuk metode dan model yang digunakan. Anda juga dapat melihat identitas pemanggil dan izin yang mengizinkan panggilan.

8. Mencatat interaksi dengan AI Generatif

Anda tidak menemukan parameter permintaan API atau data respons dalam log audit. Namun, informasi ini dapat menjadi penting untuk memecahkan masalah analisis alur kerja dan aplikasi. Pada langkah ini, kita akan memenuhi kesenjangan ini dengan menambahkan logging aplikasi.

Implementasi menggunakan Logback dengan Spring Boot untuk mencetak log aplikasi ke output standar. Metode ini menampilkan kemampuan Cloud Run untuk mengambil informasi yang dicetak ke output standar dan menyerapnya ke Cloud Logging secara otomatis. Untuk mengambil informasi sebagai data terstruktur, log yang dicetak harus diformat dengan benar. Ikuti petunjuk di bawah untuk menambahkan kemampuan logging terstruktur ke aplikasi.

1. Kembali ke jendela (atau tab) 'Cloud Shell' di browser Anda.
2. Buat dan buka file LoggingEventGoogleCloudEncoder.java baru di Cloud Shell Editor:

   cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/LoggingEventGoogleCloudEncoder.java"
   

3. Salin dan tempel kode berikut untuk menerapkan encoder Logback yang mengenkode log sebagai JSON stringified dengan mengikuti format log terstruktur Google Cloud:

   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. Buat dan buka file logback.xml baru di Cloud Shell Editor:

   cloudshell edit "${HOME}/codelab-o11y/src/main/resources/logback.xml"
   

5. Salin dan tempel XML berikut untuk mengonfigurasi Logback agar menggunakan encoder dengan Logback appender yang mencetak log ke output standar:

   <?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. Buka kembali file DemoApplication.java di Cloud Shell Editor:

   cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/DemoApplication.java"
   

7. Ganti kode di editor dengan versi yang ditampilkan di bawah untuk mencatat permintaan dan respons Gen AI. Untuk mengganti kode, hapus konten file, lalu salin kode di bawah ke editor:

   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);
       }
   }
   

Setelah beberapa detik, Cloud Shell Editor akan otomatis menyimpan perubahan Anda.

Men-deploy kode aplikasi AI Generatif ke Cloud Run

1. Di jendela terminal, jalankan perintah untuk men-deploy kode sumber aplikasi ke Cloud Run.

   gcloud run deploy codelab-o11y-service \
        --source="${HOME}/codelab-o11y/" \
        --region=us-central1 \
        --allow-unauthenticated
   

   Jika Anda melihat perintah seperti di bawah ini, yang memberi tahu Anda bahwa perintah tersebut akan membuat repositori baru. Klik 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)?
   

   Proses deployment dapat memerlukan waktu hingga beberapa menit. Setelah proses deployment selesai, Anda akan melihat output seperti:

   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. Salin URL layanan Cloud Run yang ditampilkan ke tab atau jendela terpisah di browser Anda. Atau, jalankan perintah berikut di terminal untuk mencetak URL layanan dan klik URL yang ditampilkan sambil menahan tombol Ctrl untuk membuka URL:

   gcloud run services list \
        --format='value(URL)' \
        --filter='SERVICE:"codelab-o11y-service"'
   

   Saat URL dibuka, Anda mungkin mendapatkan error 500 atau melihat pesan:

   Sorry, this is just a placeholder...
   

   Artinya, layanan tidak menyelesaikan deployment-nya. Tunggu beberapa saat, lalu muat ulang halaman. Di bagian akhir, Anda akan melihat teks yang diawali dengan Fakta Menarik tentang dan berisi 10 fakta menarik tentang.

Untuk membuat log aplikasi, buka URL layanan. Muat ulang halaman sambil mengubah nilai parameter ?animal= untuk mendapatkan hasil yang berbeda.
Untuk melihat log aplikasi, lakukan hal berikut:

1. Klik tombol di bawah untuk membuka halaman Logs Explorer di Cloud Console:
   Buka Logs Explorer
   
2. Tempel filter berikut ke panel Kueri (#2 di antarmuka Log Explorer):

   LOG_ID("run.googleapis.com%2Fstdout") AND
   severity=DEBUG
   

3. Klik Run query.

Hasil kueri menampilkan log dengan perintah dan respons Vertex AI termasuk rating keamanan.

Perhatikan bahwa perintah dan respons Vertex API yang dicatat ke dalam log dapat berisi informasi sensitif yang tidak dimaksudkan untuk diamati.

9. Menghitung interaksi dengan AI Generatif

Cloud Run menulis metrik terkelola yang dapat digunakan untuk memantau layanan yang di-deploy. Metrik pemantauan yang dikelola pengguna memberikan kontrol yang lebih besar atas data dan frekuensi pembaruan metrik. Untuk menerapkan metrik tersebut, Anda harus menulis kode yang mengumpulkan data dan menulisnya ke Cloud Monitoring. Lihat langkah berikutnya (opsional) untuk mengetahui cara menerapkannya menggunakan OpenTelemetry SDK.

Langkah ini menunjukkan alternatif untuk menerapkan metrik pengguna dalam kode - metrik berbasis log. Metrik berbasis log memungkinkan Anda membuat metrik pemantauan dari entri log yang ditulis aplikasi Anda ke Cloud Logging. Kita akan menggunakan log aplikasi yang telah diimplementasikan di langkah sebelumnya untuk menentukan metrik berbasis log dari penghitung jenis. Metrik ini akan menghitung jumlah panggilan yang berhasil ke Vertex API.

1. Lihat jendela Logs Explorer yang kita gunakan di langkah sebelumnya. Di panel Kueri, temukan menu drop-down Tindakan, lalu klik untuk membukanya. Lihat screenshot di bawah untuk menemukan menu:
   
2. Di menu yang terbuka, pilih Create metric untuk membuka panel Create log-based metric.
3. Ikuti langkah-langkah berikut untuk mengonfigurasi metrik penghitung baru di panel Buat metrik berbasis log:
   1. Tetapkan Jenis metrik: Pilih Penghitung.
   2. Tetapkan kolom berikut di bagian Detail:
      • Log metric name: Tetapkan nama ke model_interaction_count. Beberapa batasan penamaan berlaku; Lihat Pemecahan masalah batasan penamaan untuk mengetahui detailnya.
      • Deskripsi: Masukkan deskripsi untuk metrik. Misalnya, Number of log entries capturing successful call to model inference.
      • Unit: Biarkan kosong atau masukkan angka 1.
   3. Biarkan nilai di bagian Filter selection. Perhatikan bahwa kolom Build filter memiliki filter yang sama dengan yang kita gunakan untuk melihat log aplikasi.
   4. (Opsional) Tambahkan label yang membantu menghitung jumlah panggilan untuk setiap hewan. CATATAN: label ini berpotensi meningkatkan kardinalitas metrik secara signifikan dan tidak direkomendasikan untuk digunakan dalam produksi:
      1. Klik Tambahkan label.
      2. Tetapkan kolom berikut di bagian Label:
         • Nama label: Tetapkan nama ke animal.
         • Deskripsi: Masukkan deskripsi label. Misalnya, Animal parameter.
         • Jenis label: Pilih STRING.
         • Nama kolom: Ketik jsonPayload.animal.
         • Regular expression: Biarkan kosong.
      3. Klik Selesai
   5. Klik Create metric untuk membuat metrik.

Anda juga dapat membuat metrik berbasis log dari halaman Metrik berbasis log, menggunakan perintah CLI gcloud logging metrics create atau dengan resource Terraform google_logging_metric.

Untuk membuat data metrik, buka URL layanan. Muat ulang halaman yang terbuka beberapa kali untuk melakukan beberapa panggilan ke model. Seperti sebelumnya, coba gunakan hewan yang berbeda dalam parameter.

Masukkan kueri PromQL untuk menelusuri data metrik berbasis log. Untuk memasukkan kueri PromQL, lakukan hal berikut:

1. Klik tombol di bawah untuk membuka halaman Metrics Explorer di konsol Cloud:
   Buka Metrics Explorer
   
2. Di toolbar panel pembuat kueri, pilih tombol yang namanya < > MQL atau < > PromQL. Lihat gambar di bawah untuk mengetahui lokasi tombol.
   
3. Pastikan PromQL dipilih di tombol Language. Tombol bahasa berada di toolbar yang sama dengan yang memungkinkan Anda memformat kueri.
4. Masukkan kueri Anda ke editor Kueri:

   sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
   

   Untuk informasi selengkapnya tentang penggunaan PromQL, lihat PromQL di Cloud Monitoring.
5. Klik Run Query. Anda akan melihat diagram garis yang mirip dengan screenshot ini:
   
   
   Perhatikan bahwa saat tombol Jalankan Otomatis diaktifkan, tombol Jalankan Kueri tidak akan ditampilkan.

10. (Opsional) Menggunakan Open Telemetry untuk pemantauan dan perekaman aktivitas

Seperti yang disebutkan pada langkah sebelumnya, Anda dapat menerapkan metrik menggunakan OpenTelemetry (Otel) SDK. Menggunakan OTel pada arsitektur multi-layanan adalah praktik yang direkomendasikan. Langkah ini menunjukkan cara menambahkan instrumentasi OTel ke aplikasi Spring Boot. Pada langkah ini, Anda akan melakukan hal berikut:

• Menginstrumentasikan aplikasi Spring Boot dengan kemampuan pelacakan otomatis
• Mengimplementasikan metrik penghitung untuk memantau jumlah panggilan model yang berhasil
• Menghubungkan pelacakan dengan log aplikasi

Arsitektur yang direkomendasikan untuk layanan tingkat produk adalah menggunakan pengumpul OTel untuk mengumpulkan dan menyerap semua data visibilitas dari beberapa layanan. Kode dalam langkah ini tidak menggunakan kolektor agar lebih praktis. Sebagai gantinya, alat ini menggunakan ekspor OTel yang menulis data langsung ke Google Cloud.

Menyiapkan aplikasi Spring Boot dengan komponen OTel dan pelacakan otomatis

1. Kembali ke jendela (atau tab) 'Cloud Shell' di browser Anda.
2. Di terminal, perbarui file application.permissions dengan parameter konfigurasi tambahan:

   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
   

   Parameter ini menentukan ekspor data kemampuan observasi ke Cloud Trace dan Cloud Monitoring serta menerapkan pengambilan sampel semua trace.
3. Tambahkan dependensi OpenTelemetry yang diperlukan ke file 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. Tambahkan BOM OpenTelemetry ke file 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. Buka kembali file DemoApplication.java di Cloud Shell Editor:

   cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/DemoApplication.java"
   

6. Ganti kode saat ini dengan versi yang menambahkan metrik performa. Untuk mengganti kode, hapus konten file, lalu salin kode di bawah ke editor:

   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. Buka kembali file LoggingEventGoogleCloudEncoder.java di Cloud Shell Editor:

   cloudshell edit "${HOME}/codelab-o11y/src/main/java/com/example/demo/LoggingEventGoogleCloudEncoder.java"
   

8. Ganti kode saat ini dengan versi yang menambahkan atribut pelacakan ke log yang ditulis. Penambahan atribut memungkinkan log dikorelasikan dengan span rekaman aktivitas yang benar. Untuk mengganti kode, hapus konten file, lalu salin kode di bawah ke editor:

   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";
           }
       }
   }
   

Setelah beberapa detik, Cloud Shell Editor akan otomatis menyimpan perubahan Anda.

Men-deploy kode aplikasi AI Generatif ke Cloud Run

1. Di jendela terminal, jalankan perintah untuk men-deploy kode sumber aplikasi ke Cloud Run.

   gcloud run deploy codelab-o11y-service \
        --source="${HOME}/codelab-o11y/" \
        --region=us-central1 \
        --allow-unauthenticated
   

   Jika Anda melihat perintah seperti di bawah ini, yang memberi tahu Anda bahwa perintah tersebut akan membuat repositori baru. Klik 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)?
   

   Proses deployment dapat memerlukan waktu hingga beberapa menit. Setelah proses deployment selesai, Anda akan melihat output seperti:

   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. Salin URL layanan Cloud Run yang ditampilkan ke tab atau jendela terpisah di browser Anda. Atau, jalankan perintah berikut di terminal untuk mencetak URL layanan dan klik URL yang ditampilkan sambil menahan tombol Ctrl untuk membuka URL:

   gcloud run services list \
        --format='value(URL)' \
        --filter='SERVICE:"codelab-o11y-service"'
   

   Saat URL dibuka, Anda mungkin mendapatkan error 500 atau melihat pesan:

   Sorry, this is just a placeholder...
   

   Artinya, layanan tidak menyelesaikan deployment-nya. Tunggu beberapa saat, lalu muat ulang halaman. Di bagian akhir, Anda akan melihat teks yang diawali dengan Fakta Menarik tentang dan berisi 10 fakta menarik tentang.

Untuk membuat data telemetri, buka URL layanan. Muat ulang halaman sambil mengubah nilai parameter ?animal= untuk mendapatkan hasil yang berbeda.

Menjelajahi rekaman aktivitas aplikasi

1. Klik tombol di bawah untuk membuka halaman Trace Explorer di konsol Cloud:
   Buka Trace Explorer
   
2. Pilih salah satu rekaman aktivitas terbaru. Anda akan melihat 5 atau 6 span yang terlihat seperti pada screenshot di bawah.
   
3. Temukan span yang melacak panggilan ke pengendali peristiwa (metode fun_facts). Ini akan menjadi span terakhir dengan nama /.
4. Di panel Trace details, pilih Logs & events. Anda akan melihat log aplikasi yang berkorelasi dengan span tertentu ini. Korelasi terdeteksi menggunakan ID trace dan span dalam trace dan dalam log. Anda akan melihat log aplikasi yang menulis perintah dan respons Vertex API.

Menjelajahi metrik penghitung

1. Klik tombol di bawah untuk membuka halaman Metrics Explorer di konsol Cloud:
   Buka Metrics Explorer
   
2. Di toolbar panel pembuat kueri, pilih tombol yang namanya < > MQL atau < > PromQL. Lihat gambar di bawah untuk mengetahui lokasi tombol.
   
3. Pastikan PromQL dipilih di tombol Language. Tombol bahasa berada di toolbar yang sama dengan yang memungkinkan Anda memformat kueri.
4. Masukkan kueri Anda ke editor Kueri:

   sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
   

5. Klik Run Query.Jika tombol Auto-run diaktifkan, tombol Run Query tidak akan ditampilkan.

11. (Opsional) Informasi sensitif yang di-obfuscate dari log

Langkah ini bersifat edukatif. Petunjuk dalam langkah ini tidak dimaksudkan untuk dieksekusi.

Pada Langkah 10, kita mencatat informasi tentang interaksi aplikasi dengan model Gemini. Informasi ini mencakup nama hewan, perintah sebenarnya, dan respons model. Meskipun menyimpan informasi ini dalam log seharusnya aman, hal ini tidak perlu dilakukan untuk banyak skenario lainnya. Perintah ini dapat mencakup beberapa informasi pribadi atau sensitif yang tidak ingin disimpan oleh pengguna. Untuk mengatasi hal ini, Anda dapat mengaburkan data sensitif yang ditulis ke Cloud Logging. Untuk meminimalkan perubahan kode, solusi berikut direkomendasikan.

1. Membuat topik PubSub untuk menyimpan entri log yang masuk
2. Buat sink log yang mengalihkan log yang diserap ke topik PubSub.
3. Buat pipeline Dataflow yang mengubah log yang dialihkan ke topik PubSub dengan mengikuti langkah-langkah berikut:
   1. Membaca entri log dari topik PubSub
   2. Memeriksa payload entri untuk menemukan informasi sensitif menggunakan DLP inspection API
   3. Samarkan informasi sensitif dalam payload menggunakan salah satu metode penyamaran DLP
   4. Menulis entri log yang di-obfuscate ke Cloud Logging
4. Men-deploy pipeline

12. (Opsional) Membersihkan

Untuk menghindari risiko dikenai biaya untuk resource dan API yang digunakan dalam codelab, sebaiknya bersihkan setelah Anda menyelesaikan lab. Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project yang Anda buat untuk codelab.

Perhatian: Menghapus project memiliki efek berikut:

– Semua hal dalam project akan dihapus. Jika menggunakan project yang sudah ada untuk tugas dalam dokumen ini, saat Anda menghapusnya, pekerjaan lain yang telah Anda lakukan dalam project tersebut juga akan terhapus.
– Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang masih ingin Anda gunakan pada masa mendatang. Untuk mempertahankan URL yang menggunakan project ID, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

Jika Anda berencana mempelajari aplikasi yang Anda buat, menggunakan kembali project dapat menghemat waktu dan membantu Anda agar tidak melampaui batas kuota project.

1. Untuk menghapus project, jalankan perintah hapus project di terminal:

   PROJECT_ID=$(gcloud config get-value project)
   gcloud projects delete ${PROJECT_ID} --quiet
   

   Menghapus project Cloud akan menghentikan penagihan untuk semua resource dan API yang digunakan dalam project tersebut. Anda akan melihat pesan ini dengan PROJECT_ID sebagai project ID Anda:

   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. (Opsional) Jika Anda menerima error, lihat Langkah 5 untuk menemukan project ID yang Anda gunakan selama lab. Ganti dengan perintah dalam petunjuk pertama. Misalnya, jika project ID Anda adalah lab-example-project, perintahnya adalah:

   gcloud projects delete lab-project-id-example --quiet
   

13. Selamat

Di lab ini, Anda telah membuat aplikasi AI Generatif yang menggunakan model Gemini untuk membuat prediksi. Dan melengkapi aplikasi dengan kemampuan pemantauan dan logging yang penting. Anda telah men-deploy aplikasi dan perubahan dari kode sumber ke Cloud Run. Kemudian, Anda dapat menggunakan produk Google Cloud Observability untuk melacak performa aplikasi, sehingga Anda dapat memastikan keandalan aplikasi.

Jika Anda tertarik untuk diikutsertakan dalam studi riset pengalaman pengguna (UX) untuk meningkatkan kualitas produk yang Anda gunakan saat ini, daftar di sini.

Berikut beberapa opsi untuk melanjutkan pembelajaran Anda:

• Codelab Cara men-deploy aplikasi chat yang didukung gemini di Cloud Run
• Codelab Cara menggunakan panggilan fungsi Gemini dengan Cloud Run
• Cara menggunakan Cloud Run Jobs Video Intelligence API untuk memproses Video adegan demi adegan
• Workshop on demand Pengenalan Google Kubernetes Engine
• Pelajari lebih lanjut cara mengonfigurasi metrik penghitung dan distribusi menggunakan log aplikasi
• Menulis metrik OTLP menggunakan file bantuan OpenTelemetry
• Referensi untuk penggunaan Open Telemetry di Google Cloud

• Membuat trace dan metrik OpenTelemetry dengan Go