Dukungan OTLP di Google Cloud Observability

Anda dapat menyerap data log, metrik, dan trace berformat OTLP ke Google Cloud Observability dengan menggunakan Telemetry (OTLP) API, yang menerapkan OpenTelemetry Protocol. API ini memungkinkan Anda mengumpulkan telemetri netral vendor dari SDK dan pengumpul 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 rekaman log OTLP menjadi entri log dan merutekannya untuk penyimpanan.
  • Data metrik: Memetakan data metrik ke deret waktu Prometheus di Cloud Monitoring.
  • Data rekaman aktivitas: Menyimpan rekaman aktivitas terdistribusi dalam format yang umumnya konsisten dengan OTLP.

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

Dukungan protokol

Endpoint OTLP mendukung semua protokol transport dan serialisasi OTLP, termasuk http/protobuf, http/json, dan grpc. Saat mengekspor langsung dari aplikasi menggunakan SDK, sebaiknya gunakan eksportir OTLP gRPC daripada eksportir HTTP karena sebagian besar eksportir SDK tidak mendukung penggantian token dinamis.

Autentikasi

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

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

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

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

  • Berikan peran Identity and Access Management (IAM) berikut kepada pengguna atau 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 rekaman aktivitas.

Penyerapan OTLP

Bagian ini menjelaskan cara data log, metrik, dan rekaman aktivitas 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 struktur, kolom otel menyimpan salinan metadata resource, cakupan, dan entitas 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 di 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 entitas 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 dimasukkan 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 bagian berikut:

Google Cloud Observability mengonversi metrik ke format deret waktu Prometheus. Nama metrik harus tidak memiliki domain atau memiliki domain prometheus.googleapis.com. Setelah konversi, nama metrik mencakup awalan prometheus.googleapis.com dan sufiks 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 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 regular expression [a-zA-Z][a-zA-Z0-9_:./-]* akan ditolak. Satu-satunya karakter khusus yang diizinkan dalam nama metrik adalah yang ada dalam set _:./-.
  • 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 yang ada 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 API ini memberikan kuota penyerapan yang lebih tinggi daripada Cloud Trace API.

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

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

Setiap item dalam setiap array scopeSpans.spans menjadi rentang yang disimpan tunggal:

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

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 penagihan dan penyimpanan Cloud Logging saat Anda menggunakan Telemetry API untuk menyerap log karena perubahan volume log.

Perubahan terbesar pada penyimpanan dan penagihan untuk project Google Cloud Anda terjadi saat 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 banyak item dalam array logRecords. Kolom scopeLogs.scope disalin ke kolom otel untuk setiap entri log individual.

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

Untuk meminimalkan volume penyimpanan, sebaiknya lakukan hal berikut:

  • Gunakan pemroses OpenTelemetry Collector, seperti pemroses transform, untuk menghapus atribut cakupan atau resource 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 "Sampel Prometheus yang Diserap", yang sama dengan yang digunakan untuk metrik dari Google Cloud Managed Service for Prometheus.

Penagihan data Trace

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

Membuat kueri data log, metrik, dan rekaman aktivitas

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

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

  • Penting: Pembuatan kueri nama metrik dan kunci label dengan karakter khusus selain titik dua (:) dan garis bawah (_) mengharuskan Anda menyertakannya dalam tanda kurung kurawal ({}) dan tanda kutip ("), sesuai dengan spesifikasi UTF-8 PromQL. Misalnya, kueri berikut valid:

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

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

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

Batas dan kuota

Batas Telemetry API berlaku untuk semua jenis sinyal.

Kuota dan batasan 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 di-ingest oleh Telemetry API adalah 60.000 permintaan per menit. Dengan ukuran tumpukan maksimum 200 titik per permintaan, kuota ini adalah kuota default yang efektif sebesar 200.000 sampel per detik. Anda dapat meminta penambahan kuota.

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

Langkah berikutnya