Dukungan OTLP di Google Cloud Observability

Anda dapat menyerap data log, metrik, dan trace berformat OTLP ke Google Cloud Observability menggunakan Telemetry (OTLP) API, yang mengimplementasikan OpenTelemetry Protocol. Dengan API ini, Anda dapat mengumpulkan telemetri yang tidak bergantung pada vendor dari SDK dan kolektor OpenTelemetry tanpa menggunakan pengekspor Google Cloud kustom.

Saat Anda mengirim telemetri ke project menggunakan Telemetry API, Google Cloud Observability memproses setiap sinyal sebagai berikut:

  • Data log: Mengonversi data log OTLP menjadi entri log dan merutekannya untuk penyimpanan.
  • Data metrik: Memetakan data metrik ke deret waktu Prometheus di Cloud Monitoring.
  • Data trace: Menyimpan trace terdistribusi dalam format yang umumnya konsisten dengan OTLP.

Jika Anda menjalankan workload di Google Kubernetes Engine, Anda dapat menggunakan OpenTelemetry Terkelola untuk GKE, bukan men-deploy dan mengelola OpenTelemetry Collector secara manual.

Dukungan protokol

Endpoint OTLP mendukung semua protokol transportasi dan serialisasi OTLP, termasuk http/protobuf, http/json, dan grpc. Saat mengekspor langsung dari aplikasi menggunakan SDK, sebaiknya gunakan pengekspor OTLP gRPC, bukan pengekspor HTTP, karena sebagian besar pengekspor SDK tidak mendukung pemuatan ulang token dinamis.

Autentikasi

Anda harus mengonfigurasi pengekspor dengan kredensial yang diperlukan untuk mengirim data ke project Google Cloud Anda. Misalnya, saat menggunakan kolektor, biasanya Anda menggunakan ekstensi googleclientauth untuk melakukan autentikasi dengan kredensial Google.

Untuk contoh autentikasi saat menggunakan ekspor langsung data trace, lihat Mengonfigurasi autentikasi. Contoh ini menggambarkan cara mengonfigurasi pengekspor dengan Google Cloud Kredensial Default Aplikasi (ADC) dan menambahkan Library Google Auth khusus bahasa ke aplikasi Anda.

Untuk mengirim data telemetri ke project Google Cloud menggunakan Telemetry API, Anda juga harus melakukan hal berikut:

  • Mengonfigurasi project kuota. Untuk mempelajari lebih lanjut, lihat Menetapkan project kuota.

  • Berikan peran Identity and Access Management (IAM) berikut kepada pengguna atau ke akun layanan yang digunakan aplikasi:

    • Peran Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) di project kuota.
    • Peran Cloud Telemetry Writer (roles/telemetry.writer) di project. Peran ini memungkinkan aplikasi Anda menulis data log, metrik, dan trace.

Penyerapan OTLP

Bagian ini menjelaskan cara data log, metrik, dan trace Anda dikonversi dari OTLP menjadi struktur data Google Cloud Observability.

Penyerapan data log

Saat Anda menggunakan Telemetry API untuk menyerap log berformat OTLP, data log Anda akan dikonversi menjadi entri log Cloud Logging. Permintaan log berformat OTLP yang masuk dalam JSON memiliki struktur umum berikut:

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

Setiap item dalam setiap array logRecords menjadi satu entri log Cloud Logging. Atribut resource menentukan resource yang dimonitor dalam LogEntry yang dihasilkan. Untuk mengetahui informasi selengkapnya tentang atribut yang diperlukan untuk penyerapan log berformat OTLP, lihat Pemetaan atribut OTLP ke jenis resource.

Untuk mendukung penyerapan log berformat OTLP, struktur LogEntry Cloud Logging berisi kolom tambahan, otel. Karena model data OTLP dan Cloud Logging berbeda dalam strukturnya, kolom otel mempertahankan salinan metadata resource, cakupan, dan entity dari permintaan OTLP yang masuk.

Misalnya, jika Anda mengirim payload resourceLogs OTLP seperti berikut ke Telemetry API, setiap entri log yang dihasilkan akan berisi kolom resource (untuk resource yang dimonitor) dan kolom otel, seperti yang ditunjukkan pada tab lainnya:

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Karena entri log Cloud Logging bersifat mandiri dan tidak ditautkan ke skema resource eksternal, semua metadata resource, cakupan, dan entity OTLP disalin ke setiap entri log.

Penyerapan data metrik

OTLP untuk metrik Prometheus hanya berfungsi saat menggunakan OpenTelemetry Collector versi 0.140.0 atau yang lebih baru.

Saat metrik diserap ke Cloud Monitoring menggunakan OpenTelemetry Collector dan pengekspor otlphttp atau dikirim langsung menggunakan OpenTelemetry SDK, metrik OTLP dipetakan ke struktur metrik Cloud Monitoring. Untuk mendapatkan informasi tentang pemetaan tersebut, lihat referensi berikut:

Google Cloud Observability mengonversi metrik ke dalam format deret waktu Prometheus. Nama metrik tidak boleh memiliki domain atau domain prometheus.googleapis.com. Setelah konversi, nama metrik menyertakan awalan prometheus.googleapis.com dan akhiran tambahan, berdasarkan jenis titik OTLP. Metrik Cloud Monitoring yang dihasilkan memiliki struktur berikut:

prometheus.googleapis.com/{metric_name}/{suffix}

Selain itu, untuk setiap resource OpenTelemetry yang unik, konversi akan menambahkan metrik target_info yang berisi semua atribut resource kecuali service.name, service.instance.id, dan service.namespace.

Karena nama metrik dan kunci label di Cloud Monitoring tidak mendukung UTF-8 penuh, data metrik dapat ditolak:

  • Nama metrik yang tidak sesuai dengan ekspresi reguler [a-zA-Z][a-zA-Z0-9_:./-]* akan ditolak. Satu-satunya karakter khusus yang diizinkan dalam nama metrik ada dalam kumpulan _:./-.
  • Titik data yang berisi atribut (yaitu, kunci label) yang tidak sesuai dengan ekspresi reguler [a-zA-Z_][a-zA-Z0-9_.]* akan ditolak. Satu-satunya karakter khusus yang diizinkan dalam kunci label adalah dalam set _.. Semua karakter khusus diizinkan dalam nilai label.

Untuk mencegah penolakan metrik Anda karena alasan ini, gunakan fungsi replace_pattern untuk mengubah nama dan atribut metrik Anda.

Melacak penyerapan data

Terlepas dari apakah Anda menggunakan Telemetry API atau Cloud Trace API, data trace yang masuk disimpan dalam format yang konsisten dengan OTLP. Namun, sebaiknya gunakan Telemetry API karena menyediakan kuota penyerapan yang lebih tinggi daripada Cloud Trace API.

Berikut adalah contoh data trace yang mungkin dikirim dari aplikasi ke project Google Cloud Anda:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

Setiap item dalam setiap array scopeSpans.spans menjadi satu span yang disimpan:

  • Kolom resource setiap span berisi salinan data resourceSpans.resource.attributes.
  • Kolom instrumentation_scope setiap span berisi salinan data scopeSpans.scope.
  • Setiap span sesuai dengan satu entri dalam array scopeSpans.spans. Kolom seperti traceId, spanId, dan kind dipetakan ke kolom dengan nama yang sama dalam skema trace.

Untuk informasi selengkapnya, baca dokumen berikut:

Penagihan

Penagihan untuk data log, metrik, dan trace yang diserap menggunakan Telemetry API bergantung pada sinyal telemetri. Untuk mengetahui informasi selengkapnya, lihat halaman Penagihan.

Penagihan data log

Anda mungkin melihat perubahan pada nilai penyimpanan dan penagihan Cloud Logging saat menggunakan Telemetry API untuk menyerap log karena adanya perubahan pada volume log.

Perubahan terbesar pada penyimpanan dan penagihan untuk project Google Cloud Anda terjadi jika kedua hal berikut terpenuhi:

  • Kolom resource berisi atribut kardinalitas tinggi atau sejumlah besar atribut. Atribut resource ini menentukan resource yang dimonitor dalam LogEntry yang dihasilkan.
  • Kolom scopeLogs berisi sejumlah besar item dalam array logRecords. Kolom scopeLogs.scope disalin ke kolom otel untuk setiap entri log individual.

Karena metadata resource dan cakupan ini disalin ke setiap entri log, volume log yang disimpan dapat meningkat.

Untuk meminimalkan volume penyimpanan, sebaiknya lakukan hal berikut:

  • Gunakan pemroses OpenTelemetry Collector, seperti pemroses transform, untuk menghapus atribut resource atau cakupan yang tidak diperlukan sebelum mengekspor data.
  • Jika Anda tidak memerlukan metadata tambahan yang dipertahankan di kolom otel, gunakan opsi pemetaan lama, gcp.use_legacy_mapping, yang mencegah kolom otel diisi.

Penagihan data metrik

Penagihan untuk metrik OTLP diperhitungkan dalam SKU "Prometheus Samples Ingested", yang sama dengan yang digunakan untuk metrik dari Google Cloud Managed Service for Prometheus.

Penagihan data Trace

API yang Anda gunakan untuk mengirim data trace ke project tidak memengaruhi cara penghitungan biaya untuk data tersebut.

Membuat kueri data log, metrik, dan trace

Anda dapat menggunakan halaman penjelajah—Logs Explorer, Metrics Explorer, dan Trace Explorer—untuk membuat kueri data log, metrik, dan trace. Anda juga dapat menggunakan halaman Observability Analytics untuk menganalisis data log dan trace menggunakan SQL.

Tips berikut mungkin berguna saat Anda mengkueri data metrik menggunakan Metrics Explorer:

  • Penting: Untuk mengkueri nama metrik dan kunci label dengan karakter khusus selain titik dua (:) dan garis bawah (_), Anda harus menggabungkannya dalam tanda kurung kurawal ({}) dan tanda petik ("), sesuai dengan spesifikasi UTF-8 PromQL. Misalnya, berikut adalah kueri yang valid:

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • Mempertahankan label le saat membuat kueri histogram eksponensial dapat menampilkan hasil yang tidak diharapkan. Kueri histogram_quantile(.99, sum by (le) (metric)) yang lebih umum diperkirakan akan berfungsi.

  • Metrik delta mungkin tidak membuat kueri dengan benar dalam keadaan tertentu, seperti delta yang sangat jarang.

Batas dan kuota

Batas Telemetry API berlaku untuk semua jenis sinyal.

Kuota dan batas berikut juga berlaku:

  • Data log: Kuota dan batas Cloud Logging API berlaku.

  • Data metrik: Kuota dan batas Cloud Monitoring API berlaku. Misalnya, metrik tidak boleh memiliki lebih dari 200 label.

    Kuota default untuk metrik yang diserap oleh Telemetry API adalah 60.000 permintaan per menit. Pada ukuran batch maksimum 200 poin per permintaan, kuota ini adalah kuota default efektif sebesar 200.000 sampel per detik. Anda dapat meminta penambahan kuota.

  • Data trace: Tidak ada kuota atau batas tambahan yang berlaku.

Langkah berikutnya