Informasi referensi kemampuan observasi microservice

Data konfigurasi

Data konfigurasi yang ditemukan dalam variabel lingkungan ditentukan dalam tabel berikut.

Kolom Spesifikasi
project_id String

ID project tempat data visibilitas dikirim. Jika kosong, plugin observabilitas gRPC akan mencoba mengambil project ID dari variabel lingkungan, atau dari kredensial default.

Jika tidak ditemukan, fungsi init observabilitas akan menampilkan error.
cloud_logging Objek

Opsi logging dikategorikan dalam tabel ini.
Jika tidak ada, logging akan dinonaktifkan.
cloud_logging.client_rpc_events[] Daftar

Daftar konfigurasi client_rpc_events, yang mewakili konfigurasi untuk RPC keluar dari biner.

Konfigurasi client_rpc_events dievaluasi dalam urutan teks, yang pertama yang cocok akan digunakan. Jika tidak cocok dengan entri, RPC akan melanjutkan ke entri berikutnya dalam daftar.
cloud_logging.client_rpc_events[].methods[] Daftar [String]

Daftar ID metode.

Secara default, daftar kosong, tidak cocok dengan metode apa pun.

Nilai metode ini berupa [service]/[method].

* diterima sebagai karakter pengganti untuk:
  • Nama metode. Jika nilainya [service]/*, nilai tersebut cocok dengan semua metode dalam layanan yang ditentukan.
  • Seluruh nilai kolom yang cocok dengan [service]/[method] apa pun. Peristiwa ini tidak didukung jika client_rpc_events[].exclude bernilai benar.
  • Karakter pengganti * tidak dapat digunakan pada nama layanan secara terpisah, */[method] tidak didukung.

Nama layanan, jika ditentukan, harus berupa nama layanan yang sepenuhnya memenuhi syarat, termasuk nama paket.

Contoh:
  • goo.Foo/Bar hanya memilih metode Bar dari layanan goo.Foo, di sini goo adalah nama paket.
  • goo.Foo/* memilih semua metode dari layanan goo.Foo
  • * memilih semua metode dari semua layanan.
cloud_logging.client_rpc_events[].exclude Bool

Apakah metode yang ditunjukkan oleh client_rpc_events[].methods[] harus dikecualikan dari logging.

Nilai defaultnya adalah salah, yang berarti metode yang ditunjukkan oleh client_rpc_events[].methods[] disertakan dalam data log.

Jika nilainya benar, karakter pengganti (*) tidak dapat digunakan sebagai nilai keseluruhan dalam client_rpc_events[].methods[].
cloud_logging.client_rpc_events[].max_metadata_bytes Int

Jumlah maksimum byte metadata yang akan dicatat ke dalam log. Jika ukuran metadata lebih besar dari batas yang ditentukan, pasangan nilai kunci yang melebihi batas tidak akan dicatat ke dalam log.

Nilai defaultnya adalah 0, yang berarti tidak ada metadata yang dicatat ke dalam log.
cloud_logging.client_rpc_events[].max_message_bytes Int

Jumlah maksimum byte setiap pesan yang akan dicatat ke dalam log. Jika ukuran pesan lebih besar dari batas yang ditentukan, konten yang melebihi batas akan terpotong.

Nilai defaultnya adalah 0, yang berarti tidak ada payload pesan yang dicatat ke dalam log.
cloud_logging.server_rpc_events[] Daftar

Daftar konfigurasi server_rpc_events, mewakili konfigurasi untuk RPC yang masuk ke biner.

Konfigurasi server_rpc_events dievaluasi dalam urutan teks, yang pertama yang cocok akan digunakan. Jika tidak cocok dengan entri, RPC akan melanjutkan ke entri

berikutnya dalam daftar.
cloud_logging.server_rpc_events[].methods[] Daftar [String]

Daftar string yang dapat memilih grup metode.

Secara default, daftar kosong, tidak cocok dengan metode apa pun.

Nilai metode ini berupa [service]/[method].

* diterima sebagai karakter pengganti untuk:
  • Nama metode. Jika nilainya [service]/*, nilai tersebut cocok dengan semua metode dalam layanan yang ditentukan.
  • Seluruh nilai metode yang cocok dengan [service]/[method] apa pun. Fitur ini tidak didukung jika server_rpc_events[].exclude bernilai benar.
  • Karakter pengganti * tidak dapat digunakan pada nama layanan secara terpisah, */[method] tidak didukung.

Nama layanan, jika ditentukan, harus berupa nama layanan yang sepenuhnya memenuhi syarat, termasuk nama paket.

Contoh:
  • goo.Foo/Bar hanya memilih metode Bar dari layanan goo.Foo, di sini goo adalah nama paket.
  • goo.Foo/* memilih semua metode dari layanan goo.Foo
  • * memilih semua metode dari semua layanan.
cloud_logging.server_rpc_events[].exclude Bool

Apakah metode yang ditunjukkan oleh server_rpc_events[].methods[] harus dikecualikan dari logging.

Nilai defaultnya adalah false, yang berarti bahwa metode yang ditunjukkan oleh server_rpc_events[].methods[] dicatat ke dalam log.

Jika nilainya benar, karakter pengganti (*) tidak dapat digunakan sebagai nilai keseluruhan dalam entri server_rpc_events[].methods[].
cloud_logging.server_rpc_events[].max_metadata_bytes Int

Jumlah maksimum byte metadata yang akan dicatat ke dalam log. Jika ukuran metadata lebih besar dari batas yang ditentukan, pasangan nilai kunci yang melebihi batas tidak akan dicatat ke dalam log.

Nilai defaultnya adalah 0, yang berarti tidak ada metadata yang dicatat ke dalam log.
cloud_logging.server_rpc_events[].max_message_bytes Int

Jumlah maksimum byte setiap pesan yang akan dicatat ke dalam log. Jika ukuran pesan lebih besar dari batas yang ditentukan, konten yang melewati batas akan terpotong.

Nilai defaultnya adalah 0, yang berarti tidak ada payload pesan yang dicatat ke dalam log.
cloud_monitoring Objek

Mengaktifkan Cloud Monitoring. Tidak ada opsi konfigurasi. Jika Anda memberikan ketidaksetujuan konfigurasi kosong, pemantauan akan diaktifkan. Jika Anda tidak menyediakan objek konfigurasi, pemantauan akan dinonaktifkan.

Misalnya, jika tidak ada opsi lain yang ditentukan, bagian konfigurasi kosong akan mengaktifkan pemantauan.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Objek

Bagian konfigurasi kosong memungkinkan pelacakan dengan opsi konfigurasi default. Jika Anda tidak memberikan objek konfigurasi, pelacakan akan dinonaktifkan.

Misalnya, bagian konfigurasi kosong memungkinkan pelacakan dengan opsi konfigurasi default.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Saat pelacakan diaktifkan, bahkan dengan frekuensi sampling `0`, keputusan untuk mengambil sampel trace tertentu akan diterapkan.
cloud_trace.sampling_rate Jumlah

Setelan global yang mengontrol probabilitas RPC dilacak. Misalnya:
  • Nilai 0.05 berarti ada peluang 5% RPC dilacak.
  • Nilai 1.0 berarti setiap panggilan dilacak.
  • Nilai 0 berarti jangan memulai rekaman aktivitas baru.

Secara default, sampling_rate adalah 0.

Plugin ini mengikuti keputusan pengambilan sampel di upstream. Jika RPC dipilih untuk pengambilan sampel upstream, plugin akan mengumpulkan span dan mengupload data ke backend, terlepas dari setelan frekuensi sampling untuk plugin.
labels Objek

Objek JSON yang berisi kumpulan key-value pair. Kunci dan nilai adalah string.

Label diterapkan di Cloud Logging, Cloud Monitoring, dan Cloud Trace secara bersamaan.

Definisi rekaman aktivitas

Bagian ini memberikan informasi tentang pelacakan.

Melacak penerapan konteks

Agar pelacakan lintas layanan berfungsi, pemilik layanan harus mendukung penyebaran konteks rekaman aktivitas yang diterima dari upstream (atau dimulai dengan sendirinya) ke downstream. Konteks trace diterapkan di antara layanan melalui metadata gRPC. Pastikan Anda mengaktifkan Cloud Monitoring, Cloud Logging, Cloud Trace API, dan Microservices API, yang memungkinkan layanan dalam konfigurasi ini melaporkan data telemetrinya ke layanan yang sesuai.

Tanpa dukungan propagasi, layanan downstream tidak dapat menghasilkan span untuk trace. Rentang yang ada tidak terpengaruh. Plugin Kemampuan observasi microservice mendukung Format Biner OpenCensus untuk mengenkode dan mengenkode konteks rekaman aktivitas.

Span

Nama span diformat sebagai berikut:

Jenis Nilai contoh Penggunaan
Rentang RPC [Sent|Recv].helloworld.Greeter.SayHello Nama span adalah nama metode lengkap, yang dihubungkan dengan titik, tanpa garis miring awalan.
Nama span diawali dengan Sent. untuk span RPC KLIEN dan Recv. untuk span RPC SERVER di depan nama metode lengkap.
Rentang upaya Attempt.helloworld.Greeter.SayHello Melampirkan awalan Attempt. di depan nama metode lengkap.

Label span

Integrasi ini memberikan label span yang berbeda.

Untuk rentang percobaan, dua atribut terkait percobaan ulang tambahan (label rentang) disertakan:

Label Contoh nilai Penggunaan
previous-rpc-attempts 0 Jumlah upaya percobaan ulang sebelum RPC ini.
transparent-retry True/False Apakah RPC ini dimulai oleh percobaan ulang transparan.

Definisi metrik

Metrik berikut tersedia dan ditampilkan di dasbor bernama Pemantauan Layanan Mikro (gRPC) untuk perjalanan pengguna umum.

Berikut adalah metrik dari metrik sisi klien gRPC:

Nama Metrik Deskripsi Jenis, tipe, unit Label
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs Jumlah upaya RPC klien yang dimulai, termasuk yang belum selesai. Kumulatif, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs Jumlah RPC klien yang selesai, misalnya, saat respons diterima atau dikirim oleh server. Kumulatif, Int64, 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency Waktu menyeluruh yang diperlukan untuk menyelesaikan upaya RPC, termasuk waktu yang diperlukan untuk memilih subsaluran. Kumulatif, Distribusi, md grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency Total waktu yang diperlukan library gRPC untuk menyelesaikan RPC dari perspektif aplikasi. Kumulatif, Distribusi, md grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc Total byte (dikompresi, tidak dienkripsi) yang dikirim di semua pesan permintaan per percobaan RPC. Kumulatif, Distribusi, Menurut grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc Total byte (dikompresi, tidak dienkripsi) yang diterima di semua pesan respons per upaya RPC. Kumulatif, Distribusi, Menurut grpc_client_method, grpc_client_status

Metrik sisi server gRPC berikut tersedia:

Nama Metrik Deskripsi Jenis, tipe, unit Label
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
Jumlah RPC yang pernah diterima di server, termasuk RPC yang belum selesai.		 Kumulatif, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
Jumlah total RPC yang selesai, misalnya, saat respons dikirim oleh server.		 Kumulatif, Int64, 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
Total byte (dikompresi, tidak dienkripsi) yang dikirim di semua pesan respons per RPC.		 Kumulatif, Distribusi, Menurut grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
Total byte (dikompresi, tidak dienkripsi) yang diterima di semua pesan permintaan per RPC.		 Kumulatif, Distribusi, Menurut grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
Total waktu yang diperlukan RPC dari perspektif transpor server (HTTP2 / inproc / cronet).		 Kumulatif, Distribusi, md grpc_server_method

Setiap distribusi dalam tabel di atas berisi histogram dengan bucket sebagai berikut:

  • Ukuran dalam byte: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296

  • Latensi dalam md: 0, 0,01, 0,05, 0,1, 0,3, 0,6, 0,8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000

Deskripsi tag:

  • grpc_client_method: Nama metode gRPC lengkap, termasuk paket, layanan, dan metode, misalnya, google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status: Kode status server gRPC yang diterima, misalnya, OK, CANCELLED, DEADLINE_EXCEEDED
  • grpc_server_method: Nama metode gRPC lengkap, termasuk paket, layanan, dan metode, misalnya, com.exampleapi.v4.BookshelfService/Checkout
  • grpc_server_status: Kode status server gRPC yang ditampilkan, misalnya, OK, CANCELLED, DEADLINE_EXCEEDED

Definisi kumpulan log

Log kemampuan observasi Microservices diupload ke Cloud Logging menggunakan nama log (PROJECT_ID adalah placeholder untuk string yang mewakili project Anda):

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

Berikut adalah representasi JSON dari data log yang dihasilkan:

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

Tabel berikut menjelaskan kolom dalam entri log:

Kolom Spesifikasi
otoritas String

Satu proses dapat digunakan untuk menjalankan beberapa server virtual dengan identitas yang berbeda.

Otoritas adalah nama identitas server tersebut. Ini biasanya merupakan bagian dari URI dalam bentuk host atau host:port.
callId String

Mengidentifikasi panggilan [klien/server] yang merupakan UUID secara unik. Setiap panggilan dapat memiliki beberapa entri log. Semuanya memiliki callId yang sama.
jenis String

Jenis peristiwa log.

Jenis peristiwa adalah:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger String

Jenis logger peristiwa.

Jenis logger peristiwa adalah:
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName String

Nama layanan.
methodName String

Nama metode RPC.
pembanding Informasi alamat peer Objek

. Di sisi klien, peer dicatat ke dalam log pada peristiwa header server dan peristiwa trailer. Di sisi server, peer selalu dicatat di peristiwa header klien.
peer.type String

Jenis alamat, baik IPv4, IPv6, maupun UNIX.
peer.address String

Konten alamat.
peer.ip_port Int

Nomor port untuk alamat. Hanya tersedia untuk alamat IPv4 dan IPv6.
payload Objek

Payload dapat mencakup kombinasi metadata, waktu tunggu, pesan, dan status, bergantung pada peristiwa.

  • Untuk peristiwa pesan, payload adalah data aktual yang diteruskan sebagai pesan klien/server dan panjang pesan.
  • Untuk peristiwa header, payload menyertakan nama dan nilai header.
  • Untuk peristiwa trailer, payload menyertakan detail status beserta metadata trailer (jika ada).
  • Untuk peristiwa header klien, jika waktu tunggu ditetapkan, payload juga akan menyertakan waktu tunggu.
payload.timeout String

String yang mewakili google.protobuf.Duration, seperti "1,2 s".

Nilai waktu tunggu RPC.
payload.metadata Pemetaan[String, String]

Digunakan oleh peristiwa header atau peristiwa cuplikan.
payload.message String (Byte)

Payload pesan.
payload.messageLength Int

Ukuran pesan, terlepas dari apakah pesan lengkap dicatat ke dalam log atau tidak (misalnya, pesan dapat terpotong atau dihilangkan).
payload.statusCode String

Kode status gRPC.
payload.statusMessage String

Pesan status gRPC.
payload.statusDetails String

Nilai kunci metadata grpc-status-details-bin, jika ada. Ini selalu berupa pesan google.rpc.Status yang dienkode.
payloadTruncated Bool

Benar jika kolom pesan atau metadata terpotong atau dihilangkan karena opsi konfigurasi.
sequenceId Int

ID urutan pesan untuk panggilan ini. Pesan pertama memiliki nilai 1, untuk membedakan dari nilai yang tidak ditetapkan. Tujuan kolom ini adalah untuk mendeteksi entri yang hilang di lingkungan tempat ketahanan atau urutan tidak terjamin.

Label resource

Label resource mengidentifikasi sumber yang menghasilkan data visibilitas. Setiap label resource adalah pasangan nilai kunci, dengan kunci adalah nilai standar yang spesifik untuk lingkungan sumber (misalnya, GKE atau Compute Engine).

Untuk metrik dan pelacakan pada deployment GKE, label resource diisi secara default, kecuali untuk nama penampung dan nama namespace. Nilai yang tidak ada dapat diisi menggunakan Downward API.

Berikut adalah kunci variabel lingkungan:

  • CONTAINER_NAME
  • NAMESPACE

Misalnya, bagian env berikut menyertakan dua label resource:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

Label khusus

Label kustom mewakili informasi tambahan yang disediakan pengguna dalam data visibilitas. Label terdiri dari kunci dan nilai. Pasangan nilai kunci disertakan ke data pelacakan sebagai label span, ke data metrik sebagai label metrik, dan ke data logging sebagai label entri log. Semua label kustom berjenis STRING.

Anda dapat memberikan label kustom dalam konfigurasi dengan menentukan daftar key-value pair untuk labels. Implementasi membaca konfigurasi dan membuat label terpisah untuk setiap pasangan nilai kunci, lalu melampirkan label ke data observabilitas. Contoh:

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

Setiap entri log memiliki label tambahan berikut:

{
   "DATACENTER": "SAN_JOSE_DC"
   "APP_ID": "24512"
}

Langkah selanjutnya