Menulis metrik OTLP menggunakan file bantuan OpenTelemetry

---

Tutorial ini menunjukkan cara menulis, men-deploy, dan memanggil layanan Cloud Run yang melaporkan metrik OTLP kustom ke Google Cloud Managed Service For Prometheus dengan menggunakan file bantuan OpenTelemetry.

Jika Anda memiliki layanan Cloud Run yang melaporkan metrik Prometheus, gunakan sidecar Prometheus untuk Cloud Run.

Tujuan

• Menulis, membangun, dan men-deploy layanan ke Cloud Run dengan file bantuan OpenTelemetry.
• Buat metrik kustom dan laporkan ke Google Cloud Managed Service For Prometheus.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloud yang dapat ditagih berikut:

• Cloud Build
• Artifact Registry
• Google Cloud Managed Service For Prometheus
• Cloud Run

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna baru Google Cloud mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Sebelum memulai

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build APIs.

   Enable the APIs

7. Instal dan lakukan inisialisasi gcloud CLI.
8. Perbarui Google Cloud CLI: gcloud components update

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menyelesaikan tutorial, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

• Editor Cloud Build (roles/cloudbuild.builds.editor)
• Cloud Run Admin (roles/run.admin)
• Buat Akun Layanan (roles/iam.serviceAccountCreator)
• Admin Project IAM (roles/resourcemanager.projectIamAdmin)
• Monitoring Metric Writer (roles/monitoring.metricWriter)
• Service Account User (roles/iam.serviceAccountUser)
• Pelanggan Service Usage (roles/serviceusage.serviceUsageConsumer)
• Storage Admin (roles/storage.admin)

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

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

Catatan: Peran dasar IAM mungkin juga berisi izin untuk menyelesaikan tutorial. Anda tidak boleh memberikan peran dasar dalam lingkungan produksi, tetapi Anda dapat memberikannya dalam lingkungan pengembangan atau pengujian.

Perhatikan juga bahwa identitas layanan Cloud Run memerlukan peran Monitoring Metric Writer (roles/monitoring.metricWriter). Akun layanan default Compute Engine mungkin memiliki peran ini secara default, tetapi Anda mungkin perlu menambahkannya jika telah mengubah izinnya atau menggunakan akun layanan yang berbeda.

Menyiapkan default gcloud

Untuk mengonfigurasi gcloud dengan setelan default untuk layanan Cloud Run Anda:

1. Setel project default Anda:

   gcloud config set project PROJECT_ID

   Ganti PROJECT_ID dengan nama project yang Anda buat untuk tutorial ini.

2. Konfigurasi gcloud untuk region yang Anda pilih:

   gcloud config set run/region REGION

   Ganti REGION dengan region Cloud Run pilihan Anda yang didukung.

Lokasi Cloud Run

Cloud Run bersifat regional, berarti infrastruktur yang menjalankan layanan Cloud Run Anda terletak di region tertentu dan dikelola oleh Google agar tersedia secara redundan di semua zona dalam region tersebut.

Memenuhi persyaratan latensi, ketersediaan, atau ketahanan adalah faktor utama untuk memilih region tempat layanan Cloud Run dijalankan. Pada umumnya, Anda dapat memilih region yang paling dekat dengan pengguna Anda, tetapi Anda harus mempertimbangkan lokasi dari produk Google Cloud lain yang digunakan oleh layanan Cloud Run Anda. Menggunakan produk Google Cloud secara bersamaan di beberapa lokasi dapat memengaruhi latensi serta biaya layanan Anda.

Cloud Run tersedia di region berikut:

Tergantung harga Tingkat 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• asia-south1 (Mumbai, India)
• europe-north1 (Finlandia) CO₂ Rendah
• europe-southwest1 (Madrid) CO₂ Rendah
• europe-west1 (Belgia) CO₂ Rendah
• europe-west4 (Belanda) CO₂ Rendah
• europe-west8 (Milan)
• europe-west9 (Paris) CO₂ Rendah
• me-west1 (Tel Aviv)
• us-central1 (Iowa) CO₂ Rendah
• us-east1 (South Carolina)
• us-east4 (North Virginia)
• us-east5 (Columbus)
• us-south1 (Dallas) CO₂ Rendah
• us-west1 (Oregon) CO₂ Rendah

Tergantung harga Tingkat 2

• africa-south1 (Johannesburg)
• asia-east2 (Hong Kong)
• asia-northeast3 (Seoul, Korea Selatan)
• asia-southeast1 (Singapura)
• asia-southeast2 (Jakarta)
• asia-south2 (Delhi, India)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Warsawa, Polandia)
• europe-west10 (Berlin) CO₂ Rendah
• europe-west12 (Turin)
• europe-west2 (London, Inggris Raya) CO₂ Rendah
• europe-west3 (Frankfurt, Jerman) CO₂ Rendah
• europe-west6 (Zurich, Swiss) CO₂ Rendah
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) CO₂ Rendah
• northamerica-northeast2 (Toronto) CO₂ Rendah
• southamerica-east1 (São Paulo, Brasil) CO₂ Rendah
• southamerica-west1 (Santiago, Cile) CO₂ Rendah
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

Jika sudah membuat layanan Cloud Run, Anda dapat melihat region di dasbor Cloud Run di Konsol Google Cloud.

OK

Membuat repositori gambar Artifact Registry

Membuat repositori Docker Artifact Registry untuk menghosting image layanan sampel:

gcloud artifacts repositories create run-otel \
    --repository-format=docker \
    --location=REGION \
    --project=PROJECT_ID

Ganti kode berikut:

• PROJECT_ID dengan nama project yang Anda buat untuk tutorial ini.
• REGION REGION dengan region Cloud Run yang didukung pilihan Anda.

Mengambil contoh kode

Untuk mengambil contoh kode agar dapat digunakan:

1. Clone repositori aplikasi contoh ke komputer lokal Anda:

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   Atau, Anda dapat mendownload contoh sebagai file ZIP dan mengekstraknya.

2. Ubah ke direktori yang berisi kode contoh Cloud Run:

   Go

   cd golang-samples/run/custom-metrics/

Meninjau kode

Kode untuk tutorial ini terdiri dari:

• Server yang menangani permintaan masuk dan menghasilkan metrik bernama sidecar_sample_counter.

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
	"go.opentelemetry.io/otel/metric"
	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/resource"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

var counter metric.Int64Counter

func main() {
	ctx := context.Background()
	shutdown := setupCounter(ctx)
	defer shutdown(ctx)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	http.HandleFunc("/", handler)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	counter.Add(context.Background(), 100)
	fmt.Fprintln(w, "Incremented sidecar_sample_counter metric!")
}

func setupCounter(ctx context.Context) func(context.Context) error {
	serviceName := os.Getenv("K_SERVICE")
	if serviceName == "" {
		serviceName = "sample-cloud-run-app"
	}
	r, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %v", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := sdkmetric.NewMeterProvider(
		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
		sdkmetric.WithResource(r),
	)

	meter := provider.Meter("example.com/metrics")
	counter, err = meter.Int64Counter("sidecar-sample-counter")
	if err != nil {
		log.Fatalf("Error creating counter: %s", err)
	}
	return provider.Shutdown
}

• Dockerfile yang menentukan lingkungan operasi untuk layanan.

FROM golang:1.21 as builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o sample-app

FROM alpine:3
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/sample-app /sample-app
CMD ["/sample-app"]

Contoh ini juga menyertakan file pada subdirektori collector untuk membuat OpenTelemetry Collector khusus:

• File konfigurasi untuk OpenTelemetry Collector.

  receivers:
    otlp:
      protocols:
        grpc:
        http:
  
  processors:
    batch:
      # batch metrics before sending to reduce API usage
      send_batch_max_size: 200
      send_batch_size: 200
      timeout: 5s
  
    memory_limiter:
      # drop metrics if memory usage gets too high
      check_interval: 1s
      limit_percentage: 65
      spike_limit_percentage: 20
  
    # automatically detect Cloud Run resource metadata                                                                                                                                               
    resourcedetection:
      detectors: [env, gcp]
      timeout: 2s
      override: false
  
    resource:
      attributes:
        # add instance_id as a resource attribute                                                                                                                                                    
      - key: service.instance.id
        from_attribute: faas.id
        action: upsert
        # parse service name from K_SERVICE Cloud Run variable                                                                                                                                       
      - key: service.name
        value: ${env:K_SERVICE}
        action: insert
  
  exporters:
    googlemanagedprometheus: # Note: this is intentionally left blank   
  
  extensions:
    health_check:
  
  service:
    extensions: [health_check]
    pipelines:
      metrics:
        receivers: [otlp]
        processors: [batch, memory_limiter, resourcedetection, resource]
        exporters: [googlemanagedprometheus]

• Dockerfile yang menggabungkan konfigurasi yang disediakan ke dalam image Collector upstream.

  FROM otel/opentelemetry-collector-contrib:0.101.0
  
  COPY collector-config.yaml /etc/otelcol-contrib/config.yaml

Mengirimkan kode

Kode pengiriman terdiri dari tiga langkah: mem-build image container dengan Cloud Build, mengupload image container ke Artifact Registry, dan men-deploy image container ke Cloud Run.

Untuk kode pengiriman Anda:

1. Build container layanan contoh Anda dan publikasikan di Artifact Registry:

   gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app

   Setelah berhasil, Anda akan melihat pesan SUCCESS yang berisi ID, waktu pembuatan, dan nama image. Image tersebut disimpan di Artifact Registry dan dapat digunakan kembali jika diinginkan.

2. Build container Collector Anda dan publikasikan di Artifact Registry:

   gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics

   Setelah berhasil, Anda akan melihat pesan SUCCESS yang berisi ID, waktu pembuatan, dan nama image. Image tersebut disimpan di Artifact Registry dan dapat digunakan kembali jika diinginkan.

3. Men-deploy aplikasi Anda:

   YAML

   1. Buat file baru bernama service.yaml dengan:

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: SERVICE-NAME
        annotations:
          run.googleapis.com/launch-stage: BETA
      spec:
        template:
          metadata:
            annotations:
              run.googleapis.com/container-dependencies: "{app:[collector]}"
          spec:
            containers:
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
              name: app
              ports:
              - containerPort: CONTAINER_PORT
              env:
              - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
                value: "http://localhost:4317"
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
              name: collector
              startupProbe:
                httpGet:
                  path: /
                  port: 13133
      

   2. Ganti kode berikut:
      • CONTAINER_PORT dengan port yang diproses oleh container masuk layanan Anda. Secara default, nilainya adalah 8080.
      • SERVICE-NAME dengan nama apa pun untuk layanan Anda, seperti custom-metrics-sample-service.

4. Buat layanan baru dengan perintah berikut:

   gcloud run services replace service.yaml

   Perintah ini menampilkan URL layanan. Gunakan URL ini untuk mencoba aplikasi contoh dalam Melakukan percobaan.

Melakukan Percobaan

Dengan menggunakan URL dari perintah gcloud run dalam Mengirimkan kode, hubungkan ke layanan untuk membuat beberapa contoh metrik (Anda dapat menjalankan perintah ini beberapa kali untuk menghasilkan data yang lebih beragam):

curl -H \
"Authorization: Bearer $(gcloud auth print-identity-token)" \
SERVICE_URL

Ganti SERVICE_URL dengan URL layanan Anda.

Selanjutnya, buka Metrics Explorer di bagian Cloud Monitoring pada Konsol Google Cloud, lalu pilih metrik sidecar_sample_counter.

Anda juga dapat membuat kueri metrik dengan PromQL. Misalnya, kueri di bawah akan memfilter metrik berdasarkan ID instance Cloud Run:

sidecar_sample_counter{instance="INSTANCE_ID"}

Ganti INSTANCE_ID dengan ID instance apa pun untuk layanan Anda (tersedia di log instance atau dari server metadata).

Kueri ini menghasilkan chart seperti di bawah ini:

Pembersihan

Jika Anda membuat project baru untuk tutorial ini, hapus project tersebut. Jika Anda menggunakan project yang ada dan ingin mempertahankannya tanpa ada perubahan yang ditambahkan dalam tutorial ini, hapus resource yang dibuat untuk tutorial.

Menghapus project

Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project yang Anda buat untuk tutorial.

Untuk menghapus project:

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 hilang. Saat membuat project ini, Anda mungkin telah membuat project ID kustom yang ingin digunakan di 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 beberapa arsitektur, tutorial atau panduan memulai, dengan menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Menghapus resource tutorial

1. Hapus layanan Cloud Run yang Anda deploy dalam tutorial ini:

   gcloud run services delete SERVICE-NAME

   Dengan SERVICE-NAME adalah nama layanan pilihan Anda.

   Anda juga dapat menghapus layanan Cloud Run dari Konsol Google Cloud.

2. Hapus konfigurasi region default gcloud yang Anda tambahkan selama penyiapan tutorial:

    gcloud config unset run/region
   

3. Hapus konfigurasi project:

    gcloud config unset project
   

4. Hapus resource Google Cloud lain yang dibuat dalam tutorial ini:

   • Menghapus repositori Docker Artifact Registry

Langkah berikutnya

Contoh lainnya, termasuk contoh untuk trace dan log, tersedia di GitHub.