Ringkasan penyerapan OTLP

Dokumen ini memperkenalkan penggunaan Telemetry (OTLP) API, telemetry.googleapis.com, yang mengimplementasikan OpenTelemetry Protocol. Telemetry API memungkinkan Anda menyerap data log, metrik, dan trace berformat OTLP ke Google Cloud Observability:

  • Catatan log OTLP dikonversi menjadi entri log lalu dirutekan dan disimpan. Untuk mengetahui informasi tentang proses konversi, lihat bagian penyerapan log OTLP dalam dokumen ini.
  • Data metrik diserap ke Cloud Monitoring. Untuk mengetahui informasi tentang nama metrik dan label serta batasan penyerapan, lihat bagian penyerapan metrik OTLP dalam dokumen ini.
  • Data trace disimpan dalam format yang umumnya konsisten dengan OTLP. Untuk mengetahui informasi selengkapnya, lihat Penyerapan trace OTLP.

Anda dapat mengirim data telemetri ke Telemetry API dari aplikasi yang menggunakan SDK atau dengan mengekspor dari OpenTelemetry Collector.

Jika menggunakan Google Kubernetes Engine, Anda dapat menggunakan Managed OpenTelemetry untuk GKE bukan men-deploy dan mengonfigurasi OpenTelemetry Collector secara manual yang menggunakan Telemetry API.

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 gRPC OTLP, bukan pengekspor HTTP karena sebagian besar pengekspor SDK tidak mendukung penyegaran token dinamis.

Autentikasi

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

Untuk mengetahui contoh autentikasi saat menggunakan ekspor data trace langsung, lihat Mengonfigurasi autentikasi. Contoh ini mengilustrasikan cara mengonfigurasi pengekspor 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 Anda menggunakan Telemetry API, Anda juga harus melakukan hal berikut:

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

  • Memberikan 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 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 di LogEntry yang dihasilkan. Untuk mengetahui informasi selengkapnya tentang atribut mana yang diperlukan untuk penyerapan log berformat OTLP, lihat Pemetaan atribut OTLP ke jenis resource.

Untuk mendukung penyerapan log berformat OTLP, struktur Cloud Logging LogEntry berisi kolom tambahan, otel. Karena model data OTLP dan Cloud Logging memiliki struktur yang berbeda, 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 diserap ke Cloud Monitoring menggunakan OpenTelemetry Collector dan pengekspor otlphttp atau dikirim langsung menggunakan OpenTelemetry SDK, metrik OTLP akan dipetakan ke struktur metrik Cloud Monitoring. Untuk mendapatkan informasi tentang pemetaan tersebut, lihat hal berikut:

Google Cloud Observability mengonversi metrik ke format deret waktu Prometheus. Nama metrik tidak boleh memiliki domain atau domain prometheus.googleapis.com. Setelah konversi, nama metrik akan 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 lengkap, 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 adalah 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 dalam set _.. Semua karakter khusus diizinkan dalam nilai label.

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

Penyerapan data trace

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

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

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

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

  • 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 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 lengkapnya, 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 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 di LogEntryyang 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 individual, volume log yang disimpan dapat meningkat.

Untuk meminimalkan volume penyimpanan, sebaiknya lakukan hal berikut:

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

Penagihan data metrik

Penagihan untuk metrik OTLP dihitung 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 biaya dihitung untuk data tersebut.

Membuat kueri data log, metrik, dan trace

Anda dapat menggunakan halaman explorer—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 membuat kueri data metrik menggunakan Metrics Explorer:

  • Penting: Membuat kueri nama metrik dan kunci label dengan karakter khusus selain titik dua (:) dan garis bawah (_) mengharuskan Anda untuk mengapitnya dengan tanda kurung kurawal ({}) dan tanda kutip ("), 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 terduga. Kueri yang lebih umum histogram_quantile(.99, sum by (le) (metric)) diharapkan berfungsi.

  • Metrik delta mungkin tidak dapat dikueri dengan benar dalam situasi 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 batasan Cloud Logging API berlaku.

  • Data metrik: Kuota dan batasan 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. Dengan ukuran tumpukan maksimum 200 titik 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 batasan tambahan yang berlaku.

Langkah berikutnya