Menyiapkan Plugin OpenTelemetry Dasar di gRPC C++

1. Pengantar

Dalam codelab ini, Anda akan menggunakan gRPC untuk membuat klien dan server yang membentuk dasar aplikasi pemetaan rute yang ditulis dalam C++.

Di akhir tutorial, Anda akan memiliki aplikasi gRPC HelloWorld sederhana yang diinstrumentasikan dengan plugin gRPC OpenTelemetry dan dapat melihat metrik kemampuan observasi yang diekspor di Prometheus.

Yang akan Anda pelajari

• Cara menyiapkan Plugin OpenTelemetry untuk aplikasi gRPC C++ yang sudah ada
• Menjalankan instance Prometheus lokal
• Mengekspor metrik ke Prometheus
• Melihat metrik dari dasbor Prometheus

2. Sebelum memulai

Yang Anda butuhkan

• git
• curl
• build-essential
• clang
• bazel untuk membuat contoh dalam codelab ini

Instal prasyarat:

sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get install -y git curl build-essential clang

bazel dapat diinstal melalui bazelisk. Versi terbaru dapat ditemukan di sini.

Cara sederhana untuk menyiapkannya adalah dengan menginstalnya sebagai biner bazel di PATH Anda sebagai berikut:

sudo cp bazelisk-linux-amd64 /usr/local/bin/bazel
sudo chmod a+x /usr/local/bin/bazel

Atau, Anda juga dapat menggunakan CMake. Petunjuk untuk menggunakan CMake dapat ditemukan di sini.

Mendapatkan kode

Untuk menyederhanakan pembelajaran Anda, codelab ini menawarkan struktur kode sumber bawaan untuk membantu Anda memulai. Langkah-langkah berikut akan memandu Anda menginstrumentasi Plugin OpenTelemetry gRPC dalam aplikasi.

grpc-codelabs

Kode sumber scaffold untuk codelab ini tersedia di direktori github ini. Jika Anda memilih untuk tidak menerapkan kode sendiri, kode sumber yang sudah selesai tersedia di direktori completed.

Pertama, clone repo codelab grpc dan cd ke folder grpc-cpp-opentelemetry:

git clone https://github.com/grpc-ecosystem/grpc-codelabs.git
cd grpc-codelabs/codelabs/grpc-cpp-opentelemetry/

Atau, Anda dapat mendownload file .zip yang hanya berisi direktori codelab dan mengekstraknya secara manual.

Download ZIP

Bangun library gRPC menggunakan bazel:

bazel build start_here/...

Catatan: Membangun gRPC mungkin memerlukan waktu beberapa menit. Sementara itu, kita dapat melanjutkan ke langkah berikutnya untuk menginstrumentasi contoh gRPC dengan plugin gRPC OpenTelemetry.

3. Mendaftarkan Plugin OpenTelemetry

Kita memerlukan aplikasi gRPC untuk menambahkan plugin gRPC OpenTelemetry. Dalam codelab ini, kita akan menggunakan klien dan server HelloWorld gRPC sederhana yang akan kita instrumentasikan dengan plugin gRPC OpenTelemetry.

Langkah pertama Anda adalah mendaftarkan Plugin OpenTelemetry yang dikonfigurasi dengan pengekspor Prometheus di klien. Buka codelabs/grpc-cpp-opentelemetry/start_here/greeter_callback_client.cc dengan editor favorit Anda, dan ubah main() agar terlihat seperti ini -

int main(int argc, char **argv) {
  absl::ParseCommandLine(argc, argv);

  // Codelab Solution: Register a global gRPC OpenTelemetry plugin configured
  // with a prometheus exporter.
  opentelemetry::exporter::metrics::PrometheusExporterOptions opts;
  opts.url = absl::GetFlag(FLAGS_prometheus_endpoint);
  auto prometheus_exporter =
      opentelemetry::exporter::metrics::PrometheusExporterFactory::Create(opts);
  auto meter_provider =
      std::make_shared<opentelemetry::sdk::metrics::MeterProvider>();

  // The default histogram boundaries are not granular enough for RPCs. Override
  // the "grpc.client.attempt.duration" view as recommended by
  // https://github.com/grpc/proposal/blob/master/A66-otel-stats.md.
  AddLatencyView(meter_provider.get(), "grpc.client.attempt.duration", "s");
  meter_provider->AddMetricReader(std::move(prometheus_exporter));
  auto status = grpc::OpenTelemetryPluginBuilder()
                    .SetMeterProvider(std::move(meter_provider))
                    .BuildAndRegisterGlobal();
  if (!status.ok()) {
    std::cerr << "Failed to register gRPC OpenTelemetry Plugin: "
              << status.ToString() << std::endl;
    return static_cast<int>(status.code());
  }

  // Continuously send RPCs.
  RunClient(absl::GetFlag(FLAGS_target));

  return 0;
}

Catatan: Pengekspor Prometheus sedang disiapkan di Penyedia Meteran OpenTelemetry. (Ada juga cara lain untuk mengekspor metrik. Codelab ini memilih pengekspor prometheus.) MeterProvider ini disediakan untuk plugin OpenTelemetry gRPC sebagai konfigurasi. Setelah plugin OpenTelemetry didaftarkan secara global, semua klien dan server gRPC akan diinstrumentasi dengan OpenTelemetry.

Langkah berikutnya adalah menambahkan plugin OpenTelemetry ke server. Buka codelabs/grpc-cpp-opentelemetry/start_here/greeter_callback_server.cc dan ubah tampilan main menjadi seperti ini:

int main(int argc, char** argv) {
  absl::ParseCommandLine(argc, argv);

  // Register a global gRPC OpenTelemetry plugin configured with a prometheus
  // exporter.
  opentelemetry::exporter::metrics::PrometheusExporterOptions opts;
  opts.url = absl::GetFlag(FLAGS_prometheus_endpoint);
  auto prometheus_exporter =
      opentelemetry::exporter::metrics::PrometheusExporterFactory::Create(opts);
  auto meter_provider =
      std::make_shared<opentelemetry::sdk::metrics::MeterProvider>();

  // The default histogram boundaries are not granular enough for RPCs. Override
  // the "grpc.server.call.duration" view as recommended by
  // https://github.com/grpc/proposal/blob/master/A66-otel-stats.md.
  AddLatencyView(meter_provider.get(), "grpc.server.call.duration", "s");
  meter_provider->AddMetricReader(std::move(prometheus_exporter));
  auto status = grpc::OpenTelemetryPluginBuilder()
                    .SetMeterProvider(std::move(meter_provider))
                    .BuildAndRegisterGlobal();
  if (!status.ok()) {
    std::cerr << "Failed to register gRPC OpenTelemetry Plugin: "
              << status.ToString() << std::endl;
    return static_cast<int>(status.code());
  }
  RunServer(absl::GetFlag(FLAGS_port));
  return 0;
}

File header dan dependensi build yang diperlukan telah ditambahkan untuk memudahkan.

#include "opentelemetry/exporters/prometheus/exporter_factory.h"
#include "opentelemetry/exporters/prometheus/exporter_options.h"
#include "opentelemetry/sdk/metrics/meter_provider.h"

#include <grpcpp/ext/otel_plugin.h>

Dependensi build juga sudah ditambahkan dalam file BUILD -

cc_binary(
    name = "greeter_callback_client",
    srcs = ["greeter_callback_client.cc"],
    defines = ["BAZEL_BUILD"],
    deps = [
        "//util:util",
        "@com_github_grpc_grpc//:grpc++",
        "@com_github_grpc_grpc//:grpcpp_otel_plugin",
        "@com_google_absl//absl/flags:flag",
        "@com_google_absl//absl/flags:parse",
        "@io_opentelemetry_cpp//exporters/prometheus:prometheus_exporter",
        "@io_opentelemetry_cpp//sdk/src/metrics",
    ],
)

4. Menjalankan contoh dan melihat metrik

Untuk menjalankan server, jalankan -

bazel run start_here:greeter_callback_server

Jika penyiapan berhasil, Anda akan melihat output berikut untuk server -

Server listening on 0.0.0.0:50051

Saat server berjalan, di terminal lain, jalankan klien -

bazel run start_here:greeter_callback_client

Operasi yang berhasil akan terlihat seperti -

Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world
Greeter received: Hello world

Karena kita telah menyiapkan plugin gRPC OpenTelemetry untuk mengekspor metrik menggunakan Prometheus. Metrik tersebut akan tersedia di localhost:9464 untuk server dan localhost:9465 untuk klien.

Untuk melihat metrik klien -

curl localhost:9465/metrics

Hasilnya akan dalam bentuk -

# HELP exposer_transferred_bytes_total Transferred bytes to metrics services
# TYPE exposer_transferred_bytes_total counter
exposer_transferred_bytes_total 0
# HELP exposer_scrapes_total Number of times metrics were scraped
# TYPE exposer_scrapes_total counter
exposer_scrapes_total 0
# HELP exposer_request_latencies Latencies of serving scrape requests, in microseconds
# TYPE exposer_request_latencies summary
exposer_request_latencies_count 0
exposer_request_latencies_sum 0
exposer_request_latencies{quantile="0.5"} Nan
exposer_request_latencies{quantile="0.9"} Nan
exposer_request_latencies{quantile="0.99"} Nan
# HELP target Target metadata
# TYPE target gauge
target_info{otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev",service_name="unknown_service",telemetry_sdk_version="1.13.0",telemetry_sdk_name="opentelemetry",telemetry_sdk_language="cpp"} 1 1721958543107
# HELP grpc_client_attempt_rcvd_total_compressed_message_size_bytes Compressed message bytes received per call attempt
# TYPE grpc_client_attempt_rcvd_total_compressed_message_size_bytes histogram
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_count{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev"} 96 1721958543107
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_sum{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev"} 1248 1721958543107
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev",le="0"} 0 1721958543107
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev",le="5"} 0 1721958543107
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev",le="10"} 0 1721958543107
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev",le="25"} 96 1721958543107
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev",le="50"} 96 1721958543107
grpc_client_attempt_rcvd_total_compressed_message_size_bytes_bucket{grpc_method="helloworld.Greeter/SayHello",grpc_status="OK",grpc_target="dns:///localhost:50051",otel_scope_name="grpc-c++",otel_scope_version="1.67.0-dev",le="75"} 96 1721958543107

Demikian pula, untuk metrik sisi server -

curl localhost:9464/metrics

5. Melihat metrik di Prometheus

Di sini, kita akan menyiapkan instance prometheus yang akan meng-scrape klien dan server contoh gRPC yang mengekspor metrik menggunakan prometheus.

Download rilis terbaru Prometheus untuk platform Anda, lalu ekstrak dan jalankan:

tar xvfz prometheus-*.tar.gz
cd prometheus-*

Buat file konfigurasi prometheus dengan -

cat > grpc_otel_cpp_prometheus.yml <<EOF
scrape_configs:
  - job_name: "prometheus"
    scrape_interval: 5s
    static_configs:
      - targets: ["localhost:9090"]
  - job_name: "grpc-otel-cpp"
    scrape_interval: 5s
    static_configs:
      - targets: ["localhost:9464", "localhost:9465"]
EOF

Mulai prometheus dengan konfigurasi baru -

./prometheus --config.file=grpc_otel_cpp_prometheus.yml

Tindakan ini akan mengonfigurasi metrik dari proses codelab klien dan server agar di-scrape setiap 5 detik.

Buka http://localhost:9090/graph untuk melihat metrik. Misalnya, kueri -

histogram_quantile(0.5, rate(grpc_client_attempt_duration_seconds_bucket[1m]))

akan menampilkan grafik dengan latensi upaya median menggunakan 1 menit sebagai jangka waktu untuk penghitungan kuantil.

Rasio kueri -

increase(grpc_client_attempt_duration_seconds_bucket[1m])

6. (Opsional) Latihan untuk Pengguna

Di dasbor Prometheus, Anda akan melihat bahwa QPS rendah. Lihat apakah Anda dapat mengidentifikasi beberapa kode mencurigakan dalam contoh yang membatasi QPS.

Untuk yang antusias, kode klien membatasi dirinya hanya untuk memiliki satu RPC yang tertunda pada saat tertentu. Hal ini dapat diubah sehingga klien mengirim lebih banyak RPC tanpa menunggu RPC sebelumnya selesai. (Solusi untuk hal ini belum diberikan.)