Men-deploy Managed OpenTelemetry untuk GKE

Dokumen ini menjelaskan cara menyiapkan OpenTelemetry Terkelola untuk GKE guna mengirim trace, metrik, dan log OpenTelemetry Protocol (OTLP) ke Google Cloud Observability dari aplikasi yang berjalan di GKE.

Untuk mengetahui detail selengkapnya tentang cara kerja OpenTelemetry Terkelola untuk GKE, lihat OpenTelemetry Terkelola untuk GKE.

Anda dapat menggunakan OpenTelemetry Terkelola untuk GKE guna melakukan hal berikut:

  • Konfigurasikan workload yang berjalan di GKE untuk mengirim trace, metrik, dan log OpenTelemetry Protocol (OTLP) ke kolektor terkelola.
  • Menerima trace, metrik, dan log OpenTelemetry Protocol (OTLP) dari aplikasi yang berjalan di GKE.
  • Mengekspor data tersebut ke Google Cloud Observability.

Jika Anda memerlukan pemfilteran dan kontrol tingkat kolektor, gunakan Google-Built OpenTelemetry Collector, bukan penawaran terkelola ini.

Sebelum memulai

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  2. Instal Google Cloud CLI.

  3. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  4. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init

  5. Buat atau pilih project Google Cloud .

    Peran yang diperlukan untuk memilih atau membuat project

    • Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    • Buat project Google Cloud :

      gcloud projects create PROJECT_ID

      Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

    • Pilih project Google Cloud yang Anda buat:

      gcloud config set project PROJECT_ID

      Ganti PROJECT_ID dengan nama project Google Cloud Anda.

  6. Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.

  7. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

  8. Aktifkan API GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring, Cloud Trace, jika belum diaktifkan:

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran. 

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

  9. Instal Google Cloud CLI.

  10. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  11. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut: 

    gcloud init

  12. Buat atau pilih project Google Cloud .

    Peran yang diperlukan untuk memilih atau membuat project

    • Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
    • Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

    • Buat project Google Cloud :

      gcloud projects create PROJECT_ID

      Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

    • Pilih project Google Cloud yang Anda buat:

      gcloud config set project PROJECT_ID

      Ganti PROJECT_ID dengan nama project Google Cloud Anda.

  13. Pastikan Anda memiliki izin yang diperlukan untuk menyelesaikan panduan ini.

  14. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

  15. Aktifkan API GKE, Telemetry (OTLP), Cloud Logging, Cloud Monitoring, Cloud Trace, jika belum diaktifkan:

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran. 

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

Persyaratan

Untuk menggunakan Managed OpenTelemetry untuk GKE, Anda harus memenuhi persyaratan berikut:

  • Cluster harus memiliki GKE versi 1.34.1-gke.2178000 atau yang lebih baru. Untuk mengonfigurasi protokol ekspor OTLP sebagai gRPC di resource kustom Instrumentasi, Anda harus menggunakan GKE versi 1.37.1-gke.1697000 atau yang lebih baru.
  • gcloud CLI diaktifkan dengan versi 576.0.0 atau yang lebih baru.
  • Jika menggunakan Terraform untuk menyediakan infrastruktur GKE, Anda harus menggunakan terraform-provider-google pada versi v8.8.0 atau yang lebih baru.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengaktifkan dan menggunakan OpenTelemetry terkelola GKE, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Biaya

Lihat Penagihan untuk mengetahui detail tentang biaya yang terkait dengan penggunaan OpenTelemetry Terkelola untuk GKE.

Mengaktifkan OpenTelemetry Terkelola untuk GKE di cluster

Untuk menyiapkan OpenTelemetry Terkelola untuk GKE, Anda harus melakukan hal berikut:

  • Mengaktifkan OpenTelemetry Terkelola untuk GKE di cluster.
  • Konfigurasikan aplikasi yang Anda pantau untuk mengirim sinyal ke endpoint kolektor terkelola.

Saat Anda mengaktifkan Managed OpenTelemetry untuk GKE, objek berikut akan di-deploy ke cluster:

  • Deployment kolektor OpenTelemetry Terkelola GKE yang di-deploy dalam namespace gke-managed-otel. Endpoint kolektor OpenTelemetry terkelola dalam cluster untuk log, metrik, dan trace adalah sebagai berikut:
    • Endpoint HTTP: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4318
    • Endpoint gRPC: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317

  • Definisi resource kustom, instrumentations.telemetry.googleapis.com, yang dapat Anda gunakan untuk menyiapkan konfigurasi otomatis workload Anda.

    Untuk mengetahui detail selengkapnya tentang resource kustom, lihat resource kustom dalam dokumentasi Kubernetes.

Mengaktifkan di cluster baru

Untuk mengaktifkan OpenTelemetry Terkelola untuk GKE di cluster baru, ikuti langkah-langkah berikut:

gcloud

Untuk cluster Autopilot, gunakan perintah berikut:

gcloud container clusters create-auto CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Ganti kode berikut:

  • CLUSTER_NAME: nama cluster.
  • PROJECT_ID: Google Cloud Project ID
  • LOCATION: region atau zona.
  • VERSION: versi GKE. Lihat Persyaratan untuk mengetahui versi minimum yang dapat Anda gunakan.

Untuk cluster Standard, gunakan perintah berikut:

gcloud container clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION \
  --cluster-version=VERSION

Ganti kode berikut:

  • CLUSTER_NAME: nama cluster.
  • PROJECT_ID: Google Cloud Project ID
  • LOCATION: region atau zona.
  • VERSION: versi GKE. Lihat Persyaratan untuk mengetahui versi minimum yang dapat Anda gunakan.

Konsol

  • Untuk cluster Autopilot, lakukan hal berikut:

    1. Di konsol Google Cloud , buka halaman Create an Autopilot cluster.

      Buka Create an Autopilot cluster

    2. Di panel navigasi, klik Advanced settings.

    3. Di bagian Operations, pilih Enable managed OpenTelemetry.

    4. Klik Create.

  • Untuk cluster Standard, lakukan hal berikut:

    1. Di konsol Google Cloud , buka halaman Create a Kubernetes cluster.

      Buka Membuat cluster Kubernetes

    2. Di panel navigasi, klik Advanced settings.
    3. Di baris Managed OpenTelemetry, klik Edit configuration.
    4. Pilih Enable managed OpenTelemetry.
    5. Klik Simpan.
    6. Klik Create.

Terraform

Untuk mengaktifkan OpenTelemetry Terkelola untuk GKE di cluster baru menggunakan Terraform, lihat contoh berikut:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Untuk mempelajari lebih lanjut cara menggunakan Terraform, lihat Dukungan Terraform untuk GKE.

Mengaktifkan di cluster yang ada

Untuk mengaktifkan OpenTelemetry Terkelola untuk GKE di cluster yang ada, ikuti langkah-langkah berikut:

gcloud

  1. Pastikan versi cluster memenuhi persyaratan. Untuk mengetahui detail tentang cara mengupgrade cluster yang ada, lihat Upgrade cluster standar dan Upgrade cluster Autopilot.

  2. Aktifkan OpenTelemetry Terkelola untuk GKE menggunakan perintah berikut:

    gcloud container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=COLLECTION_AND_INSTRUMENTATION_COMPONENTS \
  --location=LOCATION

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster.
    • PROJECT_ID: Google Cloud Project ID
    • LOCATION: region atau zona.

Konsol

  1. Pastikan versi cluster memenuhi persyaratan. Untuk mengetahui detail tentang cara mengupgrade cluster yang ada, lihat Upgrade cluster standar dan Upgrade cluster Autopilot.

  2. Di konsol Google Cloud , buka halaman cluster Kubernetes:

    Buka Kubernetes clusters

  3. Klik nama cluster.

  4. Dalam daftar Features, cari opsi Managed OpenTelemetry. Jika tercantum sebagai dinonaktifkan, klik edit Edit, lalu pilih Enable managed OpenTelemetry.

  5. Klik Simpan perubahan.

Terraform

Untuk mengaktifkan OpenTelemetry Terkelola untuk GKE di cluster yang ada, tambahkan blok managed_opentelemetry_config ke resource google_container_cluster yang ada, seperti contoh berikut:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 8.8.0"
    }
  }
}

resource "google_container_cluster" "default" {
  name     = "gke-standard-regional-with-managed-otel"
  location = "us-west1"

  initial_node_count = 1
  release_channel {
    channel = "RAPID" # The default rapid version already has the feature available.
  }

  managed_opentelemetry_config {
    scope = "COLLECTION_AND_INSTRUMENTATION_COMPONENTS"
  }
}

Untuk mempelajari lebih lanjut cara menggunakan Terraform, lihat Dukungan Terraform untuk GKE.

Mengonfigurasi aplikasi Anda untuk menggunakan kolektor OpenTelemetry Terkelola

Aplikasi harus dikonfigurasi agar dapat mengirim sinyal ke endpoint kolektor terkelola. Setelah aplikasi dikonfigurasi, kolektor OpenTelemetry Terkelola akan menerima sinyal dari aplikasi yang berjalan di cluster tempat kolektor diaktifkan. Sinyal dari aplikasi mencakup trace, metrik, dan log.

Untuk mengirim sinyal OpenTelemetry, aplikasi harus sudah diinstrumentasikan untuk menghasilkan metrik OpenTelemetry. Untuk mengetahui detailnya, lihat workload yang didukung.

Anda dapat mengonfigurasi aplikasi secara manual untuk mengirim sinyal ke endpoint kolektor terkelola, atau Anda dapat menggunakan konfigurasi otomatis. Sebaiknya jangan gunakan kedua metode secara bersamaan untuk workload yang sama, karena konfigurasi otomatis dapat mengganti perubahan manual. Kombinasi ini mungkin akan mempersulit pelacakan perubahan pada konfigurasi.

Bagian berikut menjelaskan cara mengonfigurasi aplikasi untuk mengirim sinyal ke kolektor menggunakan konfigurasi otomatis.

Menyiapkan konfigurasi otomatis

Konfigurasi otomatis menggunakan variabel lingkungan untuk mengonfigurasi workload agar mengirim sinyal ke endpoint kolektor terkelola.

Untuk mengaktifkan injeksi otomatis variabel lingkungan ke dalam Pod, Anda menggunakan resource kustom Instrumentasi. Variabel lingkungan memiliki konfigurasi OpenTelemetry, dan dapat dimasukkan ke beberapa Pod dengan label yang cocok dalam namespace atau semua Pod dalam namespace.

Kemudian, saat aplikasi di-deploy ke namespace, GKE menggunakan konfigurasi tersebut untuk otomatis memasukkan variabel lingkungan ke Pod tempat workload berjalan.

  1. Untuk mengonfigurasi resource kustom Instrumentasi, lakukan hal berikut:

    1. Simpan manifes Instrumentation berikut dalam file bernama otlp-auto-config-namespace.yaml:

      apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL

      Ganti kode berikut:

      • NAMESPACE: namespace yang berisi Pod yang ingin Anda targetkan untuk instrumentasi otomatis. Gunakan default untuk menargetkan namespace default.
      • NAME: nama objek Instrumentasi dalam file manifes.
      • (Opsional) Label yang dilampirkan ke Pod yang akan ditarget. Jika pemilih kosong ditentukan ({}), semua Pod di namespace akan ditargetkan.
        • KEY: kunci label.
        • VALUE: nilai label.
      • TRACE_RATIO: rasio data rekaman aktivitas yang akan dikumpulkan. Jika tidak ditentukan, defaultnya adalah 1.0. Untuk mengetahui detail selengkapnya, lihat Mengubah frekuensi sampling trace.
      • METRICS_INTERVAL: interval, dalam milidetik, data pemantauan yang akan dikumpulkan. Defaultnya adalah 30000. Nilai harus non-negatif, dengan minimum 5.000 md, maksimum 300.000 md, dan kelipatan 5.000 md. Untuk mengetahui detail selengkapnya, lihat Mengubah interval ekspor metrik.

    2. Jika Anda ingin mengubah setelan apa pun, lihat bagian berikut untuk mengubah konfigurasi.

    3. Terapkan konfigurasi dengan menjalankan perintah berikut:

      kubectl apply -f otlp-auto-config-namespace.yaml

  2. Untuk memasukkan variabel lingkungan secara otomatis, Anda harus men-deploy aplikasi ke namespace di cluster yang telah menerapkan konfigurasi.

    • Untuk menerapkan konfigurasi ke workload yang belum berjalan di namespace, deploy workload menggunakan perintah berikut:

      kubectl apply -f DEPLOYMENT_NAME -n NAMESPACE

      Ganti kode berikut:

      • DEPLOYMENT_NAME: nama deployment.
      • NAMESPACE: namespace.

    • Untuk menerapkan konfigurasi ke workload yang sudah berjalan di namespace, deploy ulang workload menggunakan perintah berikut:

      kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

      Ganti kode berikut:

      • DEPLOYMENT_NAME: nama deployment.
      • NAMESPACE: namespace.

Setelah Anda menerapkan konfigurasi ke cluster, GKE akan otomatis mengonfigurasi semua workload saat di-deploy ke cluster. Workload diinstrumentasikan dengan memasukkan variabel lingkungan ke Pod tempat workload berjalan.

Saat workload yang dikonfigurasi dengan variabel lingkungan ini berjalan di cluster tempat kolektor terkelola di-deploy, workload tersebut akan mengirimkan sinyal OpenTelemetry ke kolektor terkelola saat berjalan. Sinyal ini tersedia untuk Anda lihat di Google Cloud Observability.

Untuk mengetahui detail selengkapnya tentang cara melihat sinyal, lihat Melihat telemetri. Untuk contoh, lihat Membuat contoh telemetri.

Memodifikasi konfigurasi

Untuk mengubah konfigurasi, Anda perlu melakukan hal berikut:

  1. Ubah file manifes Instrumentasi.

  2. Terapkan konfigurasi yang telah diubah.

  3. Deploy ulang atau mulai ulang aplikasi di namespace yang sesuai di cluster Anda setelah menerapkan konfigurasi yang diubah.

Untuk mengetahui detail selengkapnya tentang langkah-langkah ini, ikuti petunjuk di bagian Menyiapkan konfigurasi otomatis.

Mengonfigurasi protokol ekspor OTLP (HTTP atau gRPC)

Secara default, konfigurasi otomatis menyiapkan workload untuk mengekspor telemetri melalui HTTP. Di GKE versi 1.37.1-gke.1697000 dan yang lebih baru, Anda dapat mengonfigurasi resource kustom Instrumentasi untuk mengekspor telemetri melalui HTTP atau gRPC.

Resource kustom Instrumentasi hanya mendukung satu protokol untuk semua penyedia. Untuk menggunakan gRPC, tetapkan pengekspor ke otlp_grpc: {} untuk setiap penyedia yang Anda gunakan, dan tetapkan penyedia yang tidak digunakan ke null. Misalnya, untuk menonaktifkan metrik, gunakan meter_provider: null.

Contoh berikut adalah file manifes Instrumentasi yang dikonfigurasi untuk mengekspor telemetri melalui gRPC untuk penyedia trace, metrik, dan logging:

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: NAMESPACE
  name: NAME
spec:
  selector:
    matchLabels:
      KEY: VALUE
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "TRACE_RATIO"
      processors:
      - batch:
          exporter:
            otlp_grpc: {}
    meter_provider:
      readers:
      - periodic:
          interval: METRICS_INTERVAL
          exporter:
            otlp_grpc: {}
    logger_provider:
      processors:
      - batch:
          exporter:
            otlp_grpc: {}

Ganti kode berikut:

  • NAMESPACE: namespace yang berisi Pod yang ingin Anda targetkan untuk instrumentasi otomatis. Gunakan default untuk menargetkan namespace default.
  • NAME: nama objek Instrumentasi dalam file manifes.
  • (Opsional) Label yang dilampirkan ke Pod yang akan ditarget. Jika pemilih kosong ditentukan ({}), semua Pod di namespace akan ditargetkan.
    • KEY: kunci label.
    • VALUE: nilai label.
  • TRACE_RATIO: rasio data rekaman aktivitas yang akan dikumpulkan. Jika tidak ditentukan, defaultnya adalah 1.0. Untuk mengetahui detail selengkapnya, lihat Mengubah frekuensi sampling trace.
  • METRICS_INTERVAL: interval, dalam milidetik, data pemantauan yang akan dikumpulkan. Defaultnya adalah 30000. Nilai harus non-negatif, dengan minimum 5.000 md, maksimum 300.000 md, dan kelipatan 5.000 md. Untuk mengetahui detail selengkapnya, lihat Mengubah interval ekspor metrik.

Mengubah jumlah atau frekuensi pengumpulan data

Anda dapat mengubah jumlah data trace yang dikumpulkan dengan mengubah frekuensi sampling trace.

Anda dapat mengubah frekuensi pengiriman data pemantauan ke Cloud Monitoring dengan mengubah interval ekspor metrik.

Anda tidak dapat mengubah jumlah atau frekuensi data logging yang dikumpulkan. Namun, Anda dapat menonaktifkan semua logging, metrik, atau data pelacakan agar tidak dikumpulkan. Untuk mengetahui detailnya, lihat Memilih jenis sinyal yang akan dikumpulkan.

Mengubah frekuensi sampling trace

Workload dapat menghasilkan data trace dalam jumlah besar. Untuk situasi Anda sendiri, penting bagi Anda untuk menentukan keseimbangan antara biaya pengumpulan dan penyimpanan data, serta tingkat detail yang Anda perlukan agar data tersebut berguna.

Perilaku SDK OpenTelemetry default adalah always_on, yang setara dengan rasio 1.

Berikut adalah contoh konfigurasi frekuensi sampel trace. Dalam contoh ini, rasionya adalah 0,25 sehingga data trace dikumpulkan dengan rasio 25 persen. Ubah angka rasio ini untuk mengubah frekuensi sampel.

    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.25"

Mengubah interval ekspor metrik

Interval ekspor metrik menentukan perincian data yang dapat Anda lihat dalam grafik di Cloud Monitoring.

Berikut adalah contoh konfigurasi interval ekspor metrik. Dalam contoh ini, interval ekspornya adalah 30.000 mdtk.

Interval ekspor metrik digunakan untuk menentukan interval penundaan antara awal dua ekspor metrik berturut-turut dari SDK OpenTelemetry.

Nilai interval ini harus non-negatif, dengan minimum 5.000 md, maksimum 300.000 md, dan kelipatan 5.000 md. Nilai dinyatakan dalam milidetik.

meter_provider:
  readers:
  - periodic:
      interval: 30000

Memilih jenis sinyal yang akan dikumpulkan

Anda dapat mengontrol jenis sinyal yang dikumpulkan dari workload dengan menonaktifkan jenis sinyal yang tidak ingin Anda kumpulkan. Jenis sinyal adalah trace, metrik, dan log.

Anda dapat menonaktifkan jenis sinyal menggunakan variabel lingkungan di container tempat workload berjalan. Anda dapat mengubah variabel lingkungan dengan mengubah resource kustom Instrumentasi, lalu men-deploy ulang workload ke container.

Contoh berikut adalah file manifes Instrumentasi yang dikonfigurasi untuk pengumpulan data trace saja. Pengumpulan log dan metrik dinonaktifkan karena meter_provider dan logger_provider ditetapkan ke null.

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-disable-metrics-logs
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: true
  otelSDKConfig:
    meter_provider: null
    logger_provider: null

Mengumpulkan data perintah dan respons multimodal

Di cluster GKE versi 1.35.2-gke.1210000 atau yang lebih baru, Anda dapat mengonfigurasi OpenTelemetry Terkelola untuk GKE agar mengumpulkan data perintah dan respons multimodal.

Fungsi ini tersedia untuk agen ReAct LangGraph dan agen AI generatif yang dibangun dengan framework Agent Development Kit (ADK).

Saat Anda mengumpulkan data perintah dan respons multimodal dengan OpenTelemetry Terkelola untuk GKE, konten lengkap perintah dan respons pengguna akhir Anda akan dikumpulkan. Data perintah dan respons ini disimpan di bucket Cloud Storage. Untuk mengetahui detail tentang cara mengelola bucket penyimpanan, termasuk mengontrol akses atau menghapus data, lihat dokumentasi Cloud Storage.

Anda dapat menggunakan produk seperti Model Armor dan Sensitive Data Protection untuk mengelola data sensitif yang mungkin ada dalam perintah dan respons.

Untuk mengonfigurasi Managed OpenTelemetry untuk GKE agar mengumpulkan data perintah dan respons multimodal, lakukan hal berikut:

  1. Konfigurasikan project Google Cloud dan SDK yang Anda gunakan dengan mengikuti petunjuk di bagian Mengumpulkan perintah dan respons multimodal.

  2. Buat atau identifikasi bucket Cloud Storage yang akan digunakan untuk mengumpulkan perintah dan respons multimodal. Untuk mengetahui detailnya, lihat Membuat bucket.

  3. Beri akun layanan yang digunakan aplikasi Anda izin storage.objects.create untuk bucket Cloud Storage.

    Izin ini memungkinkan aplikasi Anda menulis objek ke bucket Cloud Storage. Objek ini menyimpan perintah dan respons yang dibuat dan diterima oleh aplikasi agentic. Untuk mengetahui informasi selengkapnya, lihat Menetapkan dan mengelola kebijakan IAM pada bucket.

  4. Konfigurasikan kolom promptsResponses.uploadBasePath di resource kustom Instrumentasi, misalnya:

    apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: prompts-responses
spec:
  selector: {}
  promptsResponses:
    uploadBasePath: gs://BUCKET_NAME

    Ganti BUCKET_NAME dengan nama bucket Cloud Storage.

Saat resource kustom Instrumentasi diperbarui dan workload dimulai ulang, variabel lingkungan yang mengonfigurasi perintah dan respons akan dimasukkan ke dalam container workload.

Untuk mengetahui detail selengkapnya tentang jenis media yang dapat Anda kumpulkan dan cara menjelajahi perintah dan respons multimodal, lihat Mengumpulkan dan melihat perintah dan respons multimodal.

Menonaktifkan konfigurasi otomatis workload

Untuk menonaktifkan instrumentasi otomatis workload dengan konfigurasi yang ditentukan, hapus resource kustom Instrumentasi dari cluster Anda. Untuk melakukannya, gunakan perintah berikut:

kubectl delete instrumentations.telemetry.googleapis.com INSTRUMENTATION_NAME -n NAMESPACE

Ganti kode berikut:

  • INSTRUMENTATION_NAME: nama resource kustom Instrumentasi.
  • NAMESPACE: namespace yang berisi Pod tempat Anda ingin menonaktifkan konfigurasi otomatis.

Untuk menonaktifkan injeksi variabel lingkungan otomatis untuk sementara sambil mempertahankan konfigurasi instrumentasi otomatis untuk penggunaan di masa mendatang, tetapkan autoInstrumentationConfig.configInjection.enabled ke false dan terapkan resource kustom yang telah diupdate.

Berikut adalah contoh resource kustom dengan injeksi variabel lingkungan otomatis yang dinonaktifkan untuk sementara:

apiVersion: telemetry.googleapis.com/v1alpha1
kind: Instrumentation
metadata:
  namespace: default
  name: otlp-auto-config-example
spec:
  selector:
    matchLabels: # Update the labels to match your workloads
      app: telemetrygen-app
  autoInstrumentationConfig:
    configInjection:
      enabled: false # disable environment variables config injection
  otelSDKConfig:
  ... # preserve OpenTelemetry configuration for future use

Setelah Anda menghapus resource kustom atau mengupdatenya untuk menonaktifkan injeksi konfigurasi otomatis, GKE tidak akan menginstrumentasikan workload baru secara otomatis yang ditargetkan oleh resource kustom Instrumentation.

Untuk berhenti mengekspor sinyal OTLP ke kolektor terkelola dari workload yang sebelumnya diinstrumentasikan oleh resource kustom, Anda harus memulai ulang workload agar perubahan diterapkan. Untuk melakukannya, gunakan perintah berikut:

kubectl rollout restart deployment DEPLOYMENT_NAME -n NAMESPACE

Ganti kode berikut:

  • DEPLOYMENT_NAME: nama deployment.
  • NAMESPACE: namespace.

Melihat telemetri

Saat workload yang dikonfigurasi berjalan di GKE dengan OpenTelemetry Terkelola untuk GKE diaktifkan, sinyal OpenTelemetry akan dikirim ke Google Cloud Observability.

Untuk mengetahui detail tentang cara melihat data di Google Cloud Observability, lihat referensi berikut:

Membuat contoh telemetri

Bagian ini menjelaskan cara men-deploy aplikasi contoh dan mengarahkan aplikasi tersebut ke endpoint OTLP dari kolektor OpenTelemetry Terkelola. Kemudian, Anda dapat melihat telemetri di Google Cloud.

Aplikasi contoh adalah generator kecil yang mengekspor trace, log, dan metrik ke kolektor OpenTelemetry terkelola dalam cluster. Aplikasi di-hard code untuk menggunakan endpoint gRPC kolektor: http://opentelemetry-collector.gke-managed-otel.svc.cluster.local:4317

Jika sudah memiliki aplikasi yang diinstrumentasikan dengan OpenTelemetry SDK, Anda dapat membuat telemetri dari aplikasi dengan mengarahkan aplikasi ke endpoint kolektor, atau mengonfigurasi instrumentasi otomatis untuk aplikasi.

Untuk men-deploy aplikasi contoh, lakukan hal berikut:

  1. Hubungkan ke cluster tempat Anda telah mengaktifkan OpenTelemetry Terkelola. Untuk melakukannya, lihat Menetapkan cluster default untuk perintah kubectl.

  2. Jalankan perintah berikut:

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/gke-app.yaml

    Setelah beberapa menit, telemetri yang dihasilkan oleh aplikasi mulai mengalir melalui kolektor ke backend Google Cloud untuk setiap sinyal.

    1. Pastikan telemetri diserap dengan melihat log, metrik, dan trace dari aplikasi demo di konsol Google Cloud :

    2. Untuk melihat metrik, lakukan tindakan berikut:

      1. Di konsol Google Cloud , buka halaman Metrics Explorer:

        Buka Metrics Explorer

      2. Jalankan kueri PromQL berikut di Metrics Explorer:

        sum(avg_over_time({"__name__"="gen","namespace"="opentelemetry-demo","job"="telemetrygen"}[1h]))

    3. Untuk melihat trace, lakukan hal berikut:

      1. Di konsol Google Cloud , buka halaman Trace Explorer.

        Buka Trace Explorer

      2. Memfilter span trace berdasarkan nama span yang sama dengan lets-go.

    4. Untuk melihat log, lakukan hal berikut:

      1. Di Konsol Google Cloud , buka halaman Logs Explorer.

        Buka Logs Explorer

      2. Jalankan kueri berikut:

        resource.type="k8s_pod"
resource.labels.namespace_name="opentelemetry-demo"

Menonaktifkan OpenTelemetry Terkelola untuk GKE

Anda dapat menonaktifkan OpenTelemetry Terkelola untuk GKE di cluster. Saat Anda menonaktifkan kolektor, kolektor Managed OpenTelemetry akan dihapus dari cluster, dan tidak ada data telemetri baru yang dikumpulkan.

Untuk menonaktifkan OpenTelemetry Terkelola untuk GKE, gunakan langkah-langkah berikut.

gcloud

Untuk menonaktifkan Managed OpenTelemetry for GKE untuk cluster, jalankan perintah gcloud berikut:

  gcloud container clusters update CLUSTER_NAME \
  --project=PROJECT_ID \
  --managed-otel-scope=NONE \
  --location=LOCATION

Ganti kode berikut:

  • CLUSTER_NAME: nama cluster.
  • PROJECT_ID: Google Cloud Project ID
  • LOCATION: region atau zona.

Konsol

  1. Di konsol, buka daftar cluster:

    Buka Kubernetes clusters

  2. Pilih cluster tempat Anda ingin menonaktifkan OpenTelemetry Terkelola.

  3. Di Cluster details, di samping Managed OpenTelemetry, pilih ikon edit.

  4. Hapus centang pada kotak untuk menonaktifkan fitur.

Terraform

Untuk menonaktifkan OpenTelemetry Terkelola untuk GKE, perbarui blok managed_opentelemetry_config di resource google_container_cluster Anda untuk menetapkan cakupan ke NONE.

  1. Perbarui file konfigurasi Terraform Anda:

    resource "google_container_cluster" "default" {
  name     = "CLUSTER_NAME"
  location = "LOCATION"
  project  = "PROJECT_ID"

  # ... other configuration ...

  managed_opentelemetry_config {
    scope = "NONE"
  }
}

  2. Terapkan konfigurasi Terraform:

    terraform apply

Ganti kode berikut:

  • CLUSTER_NAME: nama cluster.
  • LOCATION: region atau zona.
  • PROJECT_ID: Google Cloud Project ID

Saat Anda menonaktifkan Managed OpenTelemetry untuk GKE, CustomResourceDefinition Instrumentasi dan resource kustom Instrumentasi apa pun yang Anda buat tidak akan dihapus dari cluster.

Jika Anda mengaktifkan kembali OpenTelemetry terkelola, OpenTelemetry akan menggunakan konfigurasi yang dipertahankan dalam resource kustom Instrumentasi.

Jika Anda memiliki data telemetri yang telah dikumpulkan oleh OpenTelemetry Terkelola untuk GKE, menonaktifkan kolektor tidak akan memengaruhi data ini. Data yang ada tetap disimpan di Google Cloud Observability, dan tidak ada data telemetri baru yang dikumpulkan.

Pemecahan masalah

Workload dengan hak istimewa partner Autopilot

Jika Anda mencoba menggunakan konfigurasi otomatis dengan workload dengan hak istimewa partner Autopilot, Anda mungkin melihat bahwa Pod workload ditolak.

Injeksi konfigurasi OpenTelemetry tidak didukung untuk workload dengan hak istimewa dari partner GKE Autopilot. Menargetkan workload tersebut menggunakan resource kustom Instrumentasi untuk mengaktifkan injeksi variabel lingkungan OpenTelemetry dapat menyebabkan workload gagal mencocokkan daftar yang diizinkan workload dengan hak istimewa Autopilot, yang berarti Pod yang diinjeksikan konfigurasi akan ditolak oleh GKE Autopilot.

Log, metrik, atau trace tidak terlihat di konsol Google Cloud

Data mungkin tidak terlihat karena berbagai alasan. Alasan ini mencakup tidak adanya izin untuk melihat data, atau konfigurasi yang salah yang mencegah data dikumpulkan.

Langkah-langkah yang dapat Anda lakukan untuk menyelesaikan masalah umum adalah sebagai berikut:

  • Pastikan Anda telah mengaktifkan semua API yang diperlukan di project Anda.

  • Pastikan resource kustom Instrumentasi dikonfigurasi dengan benar, dengan namespace yang cocok dengan namespace tempat workload berjalan, dan pemilih yang cocok dengan label workload Anda.

  • Periksa Pod workload untuk melihat apakah variabel lingkungan diinjeksikan dengan benar.

  • Periksa log container kolektor OpenTelemetry untuk melihat apakah ada error di kolektor. Untuk melakukannya, jalankan perintah berikut:

    kubectl logs -n gke-managed-otel -l app=opentelemetry-collector -c opentelemetry-collector

Menonaktifkan sinyal telemetri tidak berfungsi

Saat Anda menonaktifkan sinyal telemetri menggunakan resource kustom Instrumentasi, pastikan Anda menerapkan resource kustom dan men-deploy ulang workload.

Saat menerapkan resource kustom, gunakan Server-Side Apply dalam perintah kubectl apply saat mengupdate resource kustom Instrumentasi.

Untuk mengetahui detail tentang cara menonaktifkan sinyal telemetri, lihat Memilih jenis sinyal yang akan dikumpulkan.

Variabel yang dimasukkan OpenTelemetry tidak terlihat di workload saya

Variabel dimasukkan ke dalam container Pod workload, bukan workload. Periksa Pod, bukan objek pemilik seperti ReplicaSet atau Deployment.

Misalnya, untuk mengonfirmasi bahwa variabel dimasukkan dengan benar untuk contoh workload di namespace default yang digunakan di bagian sebelumnya Membuat telemetri, lakukan hal berikut:

  1. Jalankan perintah berikut:

    kubectl get pods -n default -l app=telemetrygen-app -o yaml

  2. Periksa spec.containers[*].env Pod.

  3. Pastikan ada objek Instrumentation di namespace yang sama dan periksa apakah objek tersebut menargetkan Pod dan mengaktifkan fitur injeksi konfigurasi. Untuk melakukannya, jalankan perintah berikut:

    kubectl get instrumentations.telemetry.googleapis.com -n default -o yaml

Variabel dimasukkan ke dalam container hanya saat Pod dibuat karena Kubernetes API tidak mengizinkan modifikasi sebagian besar kolom dalam spesifikasi Pod yang ada, seperti variabel lingkungan. Agar konfigurasi diterapkan pada workload yang dibuat sebelum Anda membuat objek Instrumentasi, mulai ulang workload. Misalnya, untuk Deployment bernama telemetry-gen-app, jalankan perintah berikut:

kubectl rollout restart deployment -n default telemetry-gen-app

Jumlah data trace yang berlebihan di Cloud Trace

Untuk mengurangi pengumpulan data yang dikumpulkan oleh Cloud Trace, Anda dapat mengonfigurasi sampler berbasis induk dengan rasio ID trace untuk hanya mengambil sampel persentase trace Anda.

Misalnya, tambahkan kode berikut ke objek Instrumentation:

spec:
  otelSDKConfig:
    tracer_provider:
      sampler:
        parent_based:
          root:
            trace_id_ratio_based:
              ratio: "0.01"

Perilaku SDK OpenTelemetry default adalah pelacakan "always_on", yang setara dengan rasio 1.

Variabel lingkungan tidak cocok dengan konfigurasi

Jika Anda telah melakukan update pada objek Instrumentasi, pastikan Anda telah memulai ulang Pod seperti yang dijelaskan di bagian Mengubah konfigurasi.

Jika Anda melihat konfigurasi yang salah untuk Pod, pastikan Pod tersebut ditargetkan dengan benar oleh objek Instrumentation, dan Anda tidak memiliki beberapa objek Instrumentation yang menargetkan Pod yang sama:

kubectl get instrumentations --all-namespaces \
-o custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,SELECTOR:.spec.selector

kubectl get pod -n ${NAMESPACE:?} ${POD_NAME:?} --show-labels

Perhatikan bahwa pemilih kosong menargetkan semua Pod di namespace-nya.

Jika beberapa instrumentasi menargetkan Pod yang sama saat dibuat, instrumentasi yang terakhir diperbarui akan diterapkan.

Perintah kubectl logs tidak menampilkan output

Saat log di-streaming langsung dari aplikasi ke kolektor OpenTelemetry, log akan mengabaikan jalur logging standar untuk runtime container. Ini adalah skenario umum saat menggunakan OpenTelemetry untuk log. Secara default, pengekspor mengirimkan log ke endpoint otlp, bukan ke aliran data stdout dan stderr.

Dalam hal ini, karena log tidak ditulis ke stream stdout atau stderr untuk diambil oleh runtime container, perintah kubectl logs tidak akan menampilkan output apa pun untuk aplikasi tersebut. Sebagai gantinya, output logging tersedia di Cloud Logging.

Jika ingin menggunakan OpenTelemetry SDK dan juga mengirim log ke aliran data stdout, Anda dapat mengonfigurasinya menggunakan pengekspor log. Untuk mengetahui informasi selengkapnya, lihat Logs Exporter - Output standar.

Langkah berikutnya