Codelab Ekstensi Ringkasan Dasbor Looker

1. Sebelum memulai

Dalam codelab ini (1), Anda akan menyiapkan Ekstensi Ringkasan Dasbor Looker secara lokal untuk Anda coba dan kembangkan secara lokal. Kemudian (2) Anda akan men-deploy ekstensi ke produksi agar pengguna Looker lain di instance Looker Anda dapat menggunakannya. Terakhir, (3) Anda dapat mengikuti langkah-langkah tambahan untuk meningkatkan kualitas dan fungsi ekstensi. Semua bagian non-opsional harus diselesaikan secara berurutan.

Ringkasan Ekstensi Ringkasan Dasbor Looker

Secara fungsional, Ekstensi Peringkasan Dasbor Looker mengirimkan data dasbor Looker Anda ke model Gemini Vertex AI. Model Gemini kemudian menampilkan ringkasan data dasbor Anda dan resep langkah berikutnya. Ekstensi menampilkan ringkasan dan langkah berikutnya sebagai kartu di dasbor, yang mengintegrasikan ke dalam pengalaman dasbor Anda. Selain itu, ekstensi ini dapat mengekspor ringkasan dan langkah berikutnya ke Slack atau Google Chat. Ekstensi ini menggunakan aplikasi frontend React yang dipadukan dengan layanan backend websocket untuk mengirim dan menerima data ke dan dari model Gemini Vertex AI.

Prasyarat

  • Pemahaman dasar tentang pengembangan Node, Docker, dan Terraform
  • Pemahaman tentang penyiapan project Looker LookML

Yang akan Anda pelajari

  • Cara menyiapkan dan mengembangkan ekstensi secara lokal
  • Cara men-deploy ekstensi ke produksi agar pengguna Looker lain di instance Looker Anda dapat menggunakannya
  • Cara menyesuaikan performa ekstensi secara opsional dan memperluas fungsinya.
  • Cara mengelola ekstensi yang di-deploy dalam produksi

Yang Anda butuhkan

  • Instance Looker, baik melalui Lisensi Asli Looker, Uji Coba Looker Core aktif, atau lisensi Looker Core aktif.
  • Izin develop dan deploy di instance Looker Anda.
  • Izin untuk mengedit dasbor yang ingin Anda coba dengan ekstensi.
  • Kunci Looker API dari instance Looker Anda.
  • Project Google Cloud dengan penagihan diaktifkan di dalamnya.
  • Cloud Run API, Vertex AI API, dan Artifact Registry API yang diaktifkan pada project.
  • Akses ke lingkungan lokal dengan gcloud CLI yang diinstal. Langkah-langkah codelab mengasumsikan lingkungan bergaya Linux.

2. Menyiapkan backend untuk pengembangan lokal

Di bagian ini, Anda akan menyiapkan layanan backend websocket untuk dicoba dan dikembangkan secara lokal. Layanan akan memiliki akses ke Vertex AI.

  1. Instal Node versi 18 atau yang lebih baru di lingkungan lokal Anda. Ikuti petunjuk ini untuk menginstal Node.
  2. Clone repositori ekstensi ke direktori beranda lokal Anda, lalu buka direktori root repositori. Untuk tujuan codelab ini, semua contoh kode akan mengasumsikan repositori yang di-clone berada di direktori beranda lokal Anda.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Buka direktori root repositori yang di-clone dan ganti nama file .env.example menjadi .env agar Anda dapat menetapkan variabel lingkungan di bagian selanjutnya dalam codelab ini.
cd ~/dashboard-summarization
mv .env.example .env
  1. Buka direktori src backend soket web repositori yang di-clone. Direktori ini berisi kode sumber untuk server.
cd ~/dashboard-summarization/websocket-service/src
  1. Instal dependensi layanan dengan NPM.
npm install
  1. Ganti nama file looker-example.ini menjadi looker.ini.
mv looker-example.ini looker.ini
  1. Di dalam update file looker.ini:
  2. client_id dan client_secret dengan data dari kunci Looker API Anda.
  3. base_url dengan URL instance Looker Anda dalam format: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Teks di antara tanda kurung (header bagian) dengan host URL instance Looker Anda.

Misalnya, jika client ID Anda adalah ABC123, secret klien Anda adalah XYZ789, dan URL instance Looker Anda adalah https://mycompany.cloud.looker.com, file looker.ini Anda akan terlihat persis seperti ini:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Tentukan project ID Google Cloud Anda dan tetapkan di variabel lingkungan PROJECT. Ganti YOUR_PROJECT_ID dengan ID project Anda.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI menyediakan model Gemini di beberapa wilayah yang tercantum di sini. Tentukan region yang akan digunakan oleh backend lokal Anda untuk mengirim dan menerima data dari model Gemini Vertex AI. Tetapkan region di variabel lingkungan REGION Anda. Ganti YOUR_VERTEX_REGION dengan region Anda, seperti us-central1.
export REGION="YOUR_VERTEX_REGION"
  1. Sekarang mulai layanan lokal Anda.
npm start
  1. Layanan backend websocket lokal Anda akan berjalan di http://localhost:5000.

Anda telah selesai menyiapkan layanan backend websocket di lingkungan lokal.

Layanan ini berfungsi sebagai antarmuka antara ekstensi frontend Anda dan model Gemini Vertex AI. Layanan ini akan mengambil data dasbor dan LookML dari ekstensi frontend Anda dengan data yang dikueri dari Looker dan memerintahkan model Gemini Vertex AI. Kemudian, layanan akan mengalirkan respons Gemini ke ekstensi frontend yang akan ditampilkan di dasbor Anda.

Anda juga dapat membuat perubahan pada kode sumber layanan backend. Anda harus menghentikan proses layanan terlebih dahulu, membuat perubahan kode, lalu menjalankan npm start lagi.

3. Menyiapkan frontend untuk pengembangan lokal

Di bagian ini, Anda akan menyiapkan ekstensi frontend yang dapat dicoba dan dikembangkan secara lokal.

  1. Di lingkungan lokal yang sama dari langkah sebelumnya, buka direktori root repositori yang di-clone dan instal dependensi server frontend untuk frontend Anda.
cd ~/dashboard-summarization
npm install
  1. Memulai server pengembangan frontend lokal
npm run develop
  1. Server frontend lokal Anda kini menayangkan JavaScript ekstensi di http://localhost:8080/bundle.js.
  2. Buka browser web, lalu login ke instance Looker Anda.
  3. Ikuti petunjuk ini untuk menyiapkan project LookML kosong. Beri nama ringkasan dasbor proyek. Sekarang, project LookML kosong akan terbuka secara otomatis di Looker IDE pada tab browser Anda saat ini.
  4. Buat file manifes project di root project LookML. File akan disebut manifest.lkml. Jika Anda tidak tahu caranya, ikuti petunjuk ini tentang cara menambahkan file ke project LookML.
  5. Ganti konten file manifest.lkml baru dengan konten manifest.lkml di direktori root repositori tertutup Anda. Pilih tombol "Simpan Perubahan" di sudut kanan atas untuk menyimpan perubahan ke file.
  6. Di tab browser terpisah, buka daftar koneksi database di instance Looker Anda. Ikuti petunjuk ini jika Anda tidak tahu caranya.
  7. Pilih Nama satu koneksi database Looker. Tidak masalah koneksi mana yang Anda pilih. Jika Anda tidak memiliki izin untuk melihat koneksi database, hubungi admin Looker dan minta nama satu koneksi database Looker.
  8. Kembali ke tab browser dengan project LookML Anda yang terbuka di IDE Looker. Buat file model di project LookML Anda dan beri nama ringkasan dasbor file.
  9. Ganti konten file dasbor-summarization.model.lkml dengan contoh kode di bawah. Pastikan untuk mengganti string dalam tanda kutip ganda dengan nama koneksi database yang Anda pilih di langkah 9. Simpan perubahan pada file.
connection: "<YOUR_CONNECTION_NAME>"
  1. Siapkan repositori untuk menyimpan project Anda. Pilih tombol "Configure Git" di kanan atas. Pilih "Siapkan repositori bare". Pilih "Buat Repositori".
  2. Sekarang Anda memiliki repositori dasar untuk menyimpan file project LookML. Kembali ke project di IDE Looker dengan memilih "Kembali ke project" atau kembali secara manual.
  3. Pilih tombol "Validate LookML" di pojok kanan atas. Tombol akan berubah menjadi "Commit changes and push".
  4. Pilih tombol ""Commit changes and push". Tambahkan pesan apa pun yang Anda inginkan dan pilih "Commit".
  5. Pilih "Deploy to Production" di sudut kanan atas Looker IDE. Sekarang Anda telah menambahkan ekstensi ke instance Looker.
  6. Buka dasbor Looker tempat Anda ingin menambahkan ekstensi.
  7. Ikuti petunjuk untuk menambahkan kartu ekstensi ke dasbor Anda. Tambahkan ekstensi baru ke dasbor sebagai kartu.
  8. Pastikan layanan backend websocket lokal yang Anda siapkan sebelumnya sedang berjalan.

Selamat! Sekarang Anda dapat mencoba Ekstensi Peringkasan Dasbor Looker di dasbor. Ekstensi Anda akan mengirimkan metadata dasbor ke layanan backend websocket lokal dan akan menampilkan output Gemini dari layanan backend langsung dalam kartu ekstensi dasbor Anda.

Ketika server frontend lokal berjalan, Anda dapat membuat perubahan pada kode sumber JavaScript ekstensi dan server akan otomatis membangun dan menyalurkan perubahan. Anda harus memuat ulang halaman dasbor atau ekstensi untuk melihat perubahannya.

4. Men-deploy backend ke produksi

Di bagian ini, Anda akan menyiapkan layanan backend websocket untuk menayangkan instance ekstensi ringkasan dasbor di dasbor mana pun di instance Looker. Tindakan ini akan memungkinkan pengguna Looker lain mencoba ekstensi di dasbor mereka sendiri tanpa perlu menyiapkan layanan backend mereka sendiri. Langkah-langkah ini mengasumsikan bahwa Anda telah berhasil men-deploy backend untuk pengembangan lokal di lingkungan lokal yang sama sebelumnya.

  1. Ikuti petunjuk ini untuk menyiapkan Kredensial Default Aplikasi di lingkungan lokal Anda dengan project ID Anda untuk langkah berikutnya.
  2. Buat repositori Artifact Registry untuk image Docker layanan backend Anda. Ganti YOUR_REGION dengan region tempat Anda ingin repositori berada.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Buka direktori src backend web socket repositori yang di-clone.
cd ~/dashboard-summarization/websocket-service/src
  1. Edit file cloudbuild.yaml dan ganti semua instance YOUR_REGION dan YOUR_PROJECT_ID dengan region dan project ID Anda. Simpan perubahan pada file.
  2. Kirim build menggunakan Cloud Build yang akan membangun image Docker layanan backend dan mengirimnya ke repo Artifact Registry yang baru saja Anda buat. Ganti YOUR_REGION dengan region tempat Anda ingin menggunakan layanan Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. Ingat, URL image Docker yang baru dibuat berada di YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Ganti YOUR_PROJECT_ID dengan ID project Anda. Ganti YOUR_REGION dengan region dari langkah 2 yang Anda gunakan untuk membuat repositori Artifact Registry.
  2. Buka direktori websocket-service/terraform di repositori yang Anda clone.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Tentukan lokasi Google Cloud Run yang Anda inginkan untuk menjalankan layanan backend websocket. Pilih dari lokasi ini.
  2. Edit file variables.tf dan ganti YOUR_PROJECT_ID dan YOUR_DOCKER_IMAGE_URL dengan nilai yang sesuai. Periksa langkah 6 untuk mengetahui URL image docker Anda. Ganti YOUR_REGION dengan wilayah yang Anda pilih di langkah 8 sebelumnya. Simpan perubahan ke file.
  3. Deploy resource yang akan digunakan layanan backend Anda menggunakan terraform.
terraform init
terraform plan
terraform apply
  1. Simpan Endpoint URL Cloud Run yang Di-deploy untuk bagian berikutnya.

Selamat! Anda telah men-deploy layanan backend websocket dan sekarang layanan tersebut berjalan di Google Cloud Run. Sekarang, setiap instance ekstensi Ringkasan Dasbor Looker dapat berkomunikasi dengan layanan backend Anda. Sebaiknya Anda selalu memiliki setidaknya satu instance layanan backend websocket yang berjalan di Cloud Run. Persistensi layanan backend Anda mempertahankan integritas streaming data antara layanan backend websocket dan frontend ekstensi, serta membantu mempertahankan setiap sesi pengguna saat mereka menggunakan ekstensi Anda.

5. Men-deploy frontend ke produksi

Untuk bagian terakhir ini, Anda akan melakukan langkah terakhir untuk men-deploy frontend ekstensi agar tersedia bagi semua pengguna Looker di instance Looker Anda.

  1. Buka direktori root repositori yang di-clone.
cd ~/dashboard-summarization
  1. Edit .File env. Ganti YOUR_CLOUD_RUN_URL dengan Endpoint URL Cloud Run dari bagian sebelumnya. Simpan perubahan file Anda. Tindakan ini akan mengarahkan frontend ekstensi produksi ke layanan backend websocket Anda yang berjalan di Cloud Run.
  2. Buat JavaScript ekstensi. Direktori dist akan otomatis dibuat dengan file bundle.js dan file lain di dalamnya.
npm run build
  1. Buka browser web, lalu login ke instance Looker Anda. Buka nav kiri samping dan aktifkan tombol "Development Mode" di bagian bawah.
  2. Dengan navigasi samping kiri terbuka, pilih "Develop", lalu scroll ke bawah dan pilih "dashboard-summarization", project LookML ekstensi Anda. Anda sekarang seharusnya berada di Looker IDE untuk project LookML.
  3. Tarik lalu lepas semua file di direktori dist yang dibuat sebelumnya ke direktori utama project di "File Browser". Ikuti petunjuk ini jika Anda memerlukan bantuan lebih lanjut.
  4. Buka file manifest.lkml di dalam Looker IDE. Di dalam file, ganti baris
url: "http://localhost:8080/bundle.js"

dengan

file: "bundle.js"

Ganti YOUR_CLOUD_RUN_URL dengan Cloud Run URL Endpoint dari akhir bagian terakhir. Simpan perubahan pada file.

  1. Pilih tombol "Validate LookML" di pojok kanan atas. Tombol akan berubah menjadi "Commit changes and push".
  2. Pilih tombol ""Commit changes and push". Tambahkan pesan apa pun yang Anda inginkan dan pilih "Commit".
  3. Pilih "Deploy to Production" di pojok kanan atas Looker IDE.

Selamat! Sekarang Anda telah mengaktifkan semua pengguna Looker di instance Looker untuk menambahkan Ekstensi Peringkasan Dasbor Looker ke dasbor mereka. Saat pengguna Looker lainnya menggunakan ekstensi, semua instance ekstensi akan melakukan panggilan ke layanan backend websocket yang di-deploy dan berjalan di Google Cloud Run.

Perhatikan, jika Anda membuat perubahan pada kode sumber, Anda harus:

  1. Membuat kembali JavaScript ekstensi Anda
  2. Ganti file yang dihasilkan yang telah Anda tambahkan ke project LookML dengan file yang baru dibuat dari direktori dist.
  3. Memvalidasi, melakukan commit, dan men-deploy perubahan project LookML ke produksi

Coba Ekstensi Peringkasan Dasbor Looker. Sebaiknya kontribusikan ekstensi ini dan bantu ekstensi ini memenuhi kebutuhan komunitas Looker dengan lebih baik. Jangan ragu untuk membuat permintaan pull di repositori.

Lihat bagian opsional berikut untuk mengaktifkan ekspor Slack/Google Chat, menyesuaikan ringkasan dan langkah berikutnya Gemini, serta menyiapkan logging Gemini.

6. [Opsional] Menyiapkan kemampuan ekspor

Setelah Anda dan pengguna Looker mencoba ekstensi Peringkasan Dasbor Looker, mari bagikan insight ekstensi kepada audiens yang lebih banyak. Ikuti bagian ini untuk mengaktifkan ekstensi Anda agar dapat mengirim ringkasan dan langkah berikutnya ke Google Chat atau Slack. Anda harus memahami penyiapan Oauth untuk melanjutkan bagian codelab ini.

Mengaktifkan ekspor Google Chat

  1. Aktifkan Chat API di project Google Cloud Anda.
  2. Ikuti langkah 1 dari petunjuk penyiapan OAuth Google Workspace. Untuk cakupan, Anda harus menyertakan spaces.messages.create.
  3. Ikuti langkah 2 petunjuk penyiapan OAuth Google Workspace. Tambahkan URL instance pencari Anda sebagai URI di bagian "Authorized JavaScript origin", misalnya https://mycompany.cloud.looker.com. Catat Client ID yang dihasilkan.
  4. Tentukan ID ruang Google Chat yang ingin Anda jadikan tujuan ekspor ringkasan. Jika Anda tidak yakin caranya, ikuti petunjuk berikut.
  5. Edit file .File env. Ganti YOUR_GOOGLE_CLIENT_ID dengan Client-ID. Ganti YOUR_GOOGLE_SPACE_ID dengan ID ruang Google Chat. Simpan perubahan file Anda. Tindakan ini akan mengonfigurasi frontend ekstensi Anda agar dapat mengirimkan insight-nya ke ruang Google Chat yang Anda inginkan.
  6. Jika Anda menjalankan frontend ekstensi secara lokal, bangun ulang ekstensi Anda. Jika Anda men-deploy frontend ekstensi, deploy ulang frontend ekstensi.

Mengaktifkan ekspor Slack

  1. Ikuti langkah 1 dan 2 dokumen developer Slack resmi untuk menyiapkan Aplikasi OAuth. Untuk cakupan, Anda harus menyertakan chat:write dan channels:read. Catat client ID dan rahasia klien yang dibuat.
  2. Tentukan ID channel Slack yang ingin Anda ekspor ringkasannya.
  3. Edit file .File env. Ganti YOUR_SLACK_CLIENT_ID dengan Client ID. Ganti YOUR_SLACK_CLIENT_SECRET dengan Rahasia Klien. Ganti YOUR_SLACK_CHANNEL_ID dengan ID channel. Simpan perubahan file Anda. Tindakan ini akan mengonfigurasi frontend ekstensi agar dapat mengirim insight-nya ke channel Slack yang Anda inginkan.
  4. Jika Anda menjalankan frontend ekstensi secara lokal, build ulang ekstensi. Jika Anda men-deploy frontend ekstensi, deploy ulang frontend ekstensi.

Sekarang ekstensi Anda dapat mengekspor ringkasannya langsung ke Slack atau Google Chat. Perlu diingat bahwa ekstensi hanya dapat mengirim ringkasan ke ruang chat Google atau saluran Slack tertentu yang di-hardcode. Anda dapat menambahkan cakupan Oauth tambahan dan mengubah kode untuk mengambil dan menampilkan daftar ruang dan saluran yang akan dikirimi ringkasan.

7. [Opsional] Menyesuaikan ringkasan dan langkah berikutnya

Ekstensi memberi perintah pada model Gemini dengan semua metadata dan data kueri dasbor. Anda dapat meningkatkan akurasi, detail, dan kedalaman ringkasan serta langkah preskriptif dengan menambahkan sebanyak mungkin metadata dan konteks ke dasbor itu sendiri. Coba langkah-langkah ini untuk setiap dasbor yang menyertakan ekstensi Anda:

  • Ikuti petunjuk ini untuk menambahkan detail dasbor ke dasbor. Hal ini akan membantu memberi tahu LLM tentang konteks umum dasbor.
  • Ikuti petunjuk ini untuk menambahkan catatan ke setiap kartu dasbor. Hal ini akan membantu memberi tahu LLM tentang konteks setiap kueri individu di dasbor. Catatan kontekstual kecil akan diperhitungkan dalam ringkasan yang dihasilkan.

Makin banyak informasi yang dapat Anda tambahkan ke dasbor, makin baik ringkasan dan langkah berikutnya dari ekstensi tersebut. Anda dapat mengubah kode untuk menyertakan metadata dasbor tambahan dalam perintah ke model Gemini.

8. [Opsional] Siapkan logging model Gemini

Setiap kali pengguna memberi tahu ekstensi agar membuat ringkasan untuk dasbor, ekstensi akan melakukan panggilan ke Vertex AI untuk setiap kueri di dasbor, ditambah satu panggilan terakhir untuk memformat semua ringkasan. Ikuti bagian ini untuk mencatat panggilan Vertex AI yang dibuat ekstensi Anda sehingga Anda dapat memperkirakan dan memantau biaya dan traffic Vertex AI. Anda hanya perlu mengikuti petunjuk ini jika telah men-deploy layanan backend websocket.

  1. Tentukan lokasi Cloud Run untuk layanan backend websocket yang di-deploy.
  2. Ikuti petunjuk ini untuk menyiapkan sink log yang akan merutekan log ke Big Query. Tujuan sink harus berupa BigQuery. Tetapkan filter penyertaan dengan contoh kode berikut dengan YOUR_CLOUD_RUN_LOCATION diganti dengan lokasi Cloud Run di langkah sebelumnya.
resource.type = "cloud_run_revision"
resource.labels.service_name = "websocket-service"
resource.labels.location = "YOUR_CLOUD_RUN_LOCATION"
 severity>=DEFAULT
jsonPayload.component="dashboard-summarization-logs"

9. Selamat!

Anda telah menyiapkan ekstensi Peringkasan Dasbor Looker secara lokal untuk Anda coba. Anda juga telah men-deploy ekstensi ke Google Cloud sehingga pengguna lain juga dapat mencobanya. Sekarang, Anda dan pengguna lain dapat mengakses ringkasan dan langkah berikutnya yang didukung Gemini langsung dari dalam dasbor.

10. Langkah berikutnya