Informasi referensi kemampuan observasi microservice

Data konfigurasi

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

Kolom Spesifikasi
project_id String

ID project tujuan pengiriman data kemampuan observasi. Jika kosong, plugin kemampuan observasi gRPC akan mencoba mengambil project ID dari variabel lingkungan, atau dari kredensial default.

Jika tidak ditemukan, fungsi init kemampuan observasi 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 cocok akan digunakan. Jika RPC tidak cocok dengan entri, RPC akan berlanjut ke entri berikutnya dalam daftar.
cloud_logging.client_rpc_events[].methods[] Daftar [String]

Daftar ID metode.

Secara default, daftar ini kosong, tidak ada metode yang cocok.

Nilai metode ini dalam bentuk [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. Parameter ini tidak didukung jika client_rpc_events[].exclude bernilai true.
  • Karakter pengganti * tidak dapat digunakan pada nama layanan secara independen, */[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 false, yang berarti metode yang dinyatakan oleh client_rpc_events[].methods[] akan disertakan dalam data log.

Jika nilainya benar, karakter pengganti (*) tidak dapat digunakan sebagai nilai bulat 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, key-value pair yang melebihi batas tidak akan dicatat 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.
cloud_logging.server_rpc_events[] Daftar

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

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

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

Daftar string yang dapat memilih sekelompok metode.

Secara default, daftar ini kosong, tidak ada metode yang cocok.

Nilai metode ini dalam bentuk [service]/[method].

* diterima sebagai karakter pengganti untuk:
  • Nama metode. Jika nilainya [service]/*, nilai tersebut cocok dengan semua metode dalam layanan yang ditentukan.
  • Nilai seluruh metode yang cocok dengan [service]/[method] apa pun. Tidak didukung jika server_rpc_events[].exclude bernilai benar (true).
  • Karakter pengganti * tidak dapat digunakan pada nama layanan secara independen, */[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 bulat dalam entri server_rpc_events[].methods[] apa pun.
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, key-value pair yang melebihi batas tidak akan dicatat 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 tersebut akan dipotong.

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

Mengaktifkan Cloud Monitoring. Tidak ada opsi konfigurasi. Jika Anda memberikan keberatan 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 yang kosong memungkinkan pelacakan dengan opsi konfigurasi default. Jika Anda tidak memberikan objek konfigurasi, perekaman akan dinonaktifkan.

Misalnya, bagian konfigurasi kosong memungkinkan perekaman aktivitas dengan opsi konfigurasi default.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Saat perekaman aktivitas diaktifkan, meskipun dengan frekuensi pengambilan sampel `0`, keputusan untuk mengambil sampel rekaman aktivitas tertentu akan diterapkan.
cloud_trace.sampling_rate Angka

Setelan global yang mengontrol kemungkinan RPC dilacak. Contoh:
  • Nilai 0.05 berarti ada kemungkinan 5% RPC akan dilacak.
  • Nilai 1.0 berarti setiap panggilan akan dilacak.
  • Nilai 0 berarti jangan memulai trace baru.

Secara default, sampling_rate adalah 0.

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

Objek JSON yang berisi serangkaian key-value pair. Kunci dan nilai adalah {i>string<i}.

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

Definisi trace

Bagian ini memberikan informasi tentang perekaman aktivitas.

Melacak propagasi konteks

Agar pelacakan lintas layanan berfungsi, pemilik layanan harus mendukung propagasi konteks rekaman aktivitas yang diterima dari upstream (atau dimulai dengan sendirinya) ke downstream. Konteks rekaman aktivitas disebarkan 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 telemetri ke layanan yang sesuai.

Tanpa dukungan propagasi, layanan downstream tidak dapat menghasilkan span untuk rekaman aktivitas. Span yang sudah ada tidak akan terpengaruh. Plugin kemampuan observasi Microservice mendukung OpenCensus Binary Format untuk encoding dan encoding konteks rekaman aktivitas.

Rentang

Nama span diformat sebagai berikut:

Jenis Nilai contoh Penggunaan
Span 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 CLIENT dan Recv. untuk rentang RPC SERVER di depan nama metode lengkap.
Rentang upaya Attempt.helloworld.Greeter.SayHello Melampirkan awalan Attempt. di depan nama metode lengkap.

Label span

Integrasi tersebut memberikan label span yang berbeda.

Untuk span percobaan, dua atribut tambahan terkait percobaan ulang (label span) dilampirkan:

Label Contoh nilai Penggunaan
upaya-rpc-sebelumnya 0 Upaya percobaan ulang dihitung sebelum RPC ini.
percobaan-ulang transparan True/False Apakah RPC ini dimulai oleh percobaan ulang transparan.

Definisi metrik

Metrik berikut tersedia dan ditampilkan di dasbor yang bernama Microservices (gRPC) Monitoring untuk perjalanan pengguna umum.

Berikut adalah metrik dari metrik sisi klien gRPC:

Nama Metrik Deskripsi Jenis, jenis, unit Label
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs Jumlah upaya RPC klien yang dimulai, termasuk yang belum diselesaikan. 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 end-to-end 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 dibutuhkan 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 upaya 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, jenis, 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 (terkompresi tidak terenkripsi) yang dikirim ke 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 (terkompresi tidak terenkripsi) 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 dibutuhkan RPC dari perspektif (HTTP2 / inproc / cronet) transport server.		 Kumulatif, Distribusi, md grpc_server_method

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

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

  • 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

Deskripsi tag:

  • grpc_client_method: Nama lengkap metode gRPC, termasuk paket, layanan, dan metode, misalnya, google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status: Kode status server gRPC diterima, misalnya, OK, CANCELLED, DEADLINE_EXCEEDED
  • grpc_server_method: Nama lengkap metode gRPC, 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 catatan log

Log kemampuan observasi Microservice 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. Biasanya, sebagian dari URI adalah dalam bentuk host atau host:port.
callId String

Secara unik mengidentifikasi panggilan [client/server] yang merupakan UUID. 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 pencatat peristiwa adalah:
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName String

Nama layanan.
methodName String

Nama metode RPC.
pembanding Objek

Informasi alamat pembanding. Di sisi klien, peer akan dicatat ke dalam log berdasarkan peristiwa header server dan peristiwa cuplikan. Di sisi server, {i>peer<i} selalu dicatat ke peristiwa {i>header<i} klien.
peer.type String

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

Isi 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 peristiwanya.

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

String yang mewakili google.protobuf.Duration, misalnya "1,2 dtk".

Nilai waktu tunggu RPC.
payload.metadata Mapping[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 sedang di-log (misalnya, pesan dapat dipotong 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. Pesan ini selalu berupa pesan google.rpc.Status yang dienkode.
payloadTruncated Bool

True 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 tidak ada di lingkungan yang tidak memiliki jaminan ketahanan atau urutan.

Label resource

Label resource mengidentifikasi sumber yang menghasilkan data kemampuan observasi. Setiap label resource merupakan pasangan nilai kunci, dengan kunci adalah nilai yang telah ditentukan sebelumnya dan spesifik untuk lingkungan sumber (misalnya, GKE atau Compute Engine).

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

Berikut adalah kunci variabel lingkungan:

  • CONTAINER_NAME
  • NAMESPACE

Misalnya, bagian env di bawah ini mencakup 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 khusus merepresentasikan informasi tambahan yang disediakan pengguna dalam data kemampuan observasi. Label terdiri dari kunci dan nilai. Pasangan nilai kunci dilampirkan ke data pelacakan sebagai label span, ke data metrik sebagai label metrik, dan ke data logging sebagai label entri log. Semua label khusus adalah jenis STRING.

Anda dapat memberikan label khusus dalam konfigurasi dengan menentukan daftar key-value pair untuk labels. Implementasi ini akan membaca konfigurasi dan membuat label terpisah untuk setiap pasangan nilai kunci, lalu melampirkan label ke data kemampuan observasi. 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