C++ dan OpenTelemetry

Halaman ini ditujukan untuk developer aplikasi yang ingin mengumpulkan data Cloud Trace untuk aplikasi C++ menggunakan OpenTelemetry. OpenTelemetry adalah framework instrumentasi netral vendor yang dapat Anda gunakan untuk mengumpulkan data metrik dan trace. Untuk mengetahui informasi tentang cara menginstrumentasikan kode, lihat Instrumentasi dan observabilitas.

Halaman ini memandu Anda melalui langkah-langkah berikut:

  • Menginstal paket OpenTelemetry.
  • Mengonfigurasi aplikasi Anda untuk mengekspor span ke Cloud Trace.
  • Mengonfigurasi platform Anda.

Untuk mengetahui informasi rilis, lihat hal berikut:

Untuk konten referensi OpenTelemetry, lihat hal berikut:

Untuk mengetahui detail terbaru tentang OpenTelemetry untuk C++, beserta dokumentasi dan contoh tambahan, lihat OpenTelemetry.

Sebelum memulai

Aktifkan Cloud Trace API.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

Mengaktifkan API

Menginstal paket OpenTelemetry

Mengonfigurasi ekspor span ke Cloud Trace

Untuk mengonfigurasi ekspor data trace, panggil metode google::cloud::otel::ConfigureBasicTracing(...) dalam metode main() Anda:

namespace gc = ::google::cloud;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  MyApplicationCode();
}

Kolom project_id adalah Google Cloud project tempat Anda ingin menyimpan trace.

Metode ConfigureBasicTracing(...) membuat instance objek TracerProvider yang mengimplementasikan pengekspor Cloud Trace. Jika objek yang ditampilkan oleh panggilan ke ConfigureBasicTracing(...) berada di luar cakupan, objek TracerProvider sebelumnya akan dipulihkan, jika ada.

Mengonfigurasi rasio sampel

Aplikasi dapat menghasilkan volume data trace yang besar. Contoh berikut mengilustrasikan cara mengonfigurasi rasio pengambilan sampel:

namespace gc = ::google::cloud;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto options = gc::Options{}.set<gc::otel::BasicTracingRateOption>(.001);
  auto configuration = gc::otel::ConfigureBasicTracing(project, options);

  MyApplicationCode();
}

Mengekspor ke Cloud Trace dengan TracerProvider kustom

Anda mungkin memiliki kasus penggunaan yang memerlukan objek TracerProvider kustom. Misalnya, jika ingin menggunakan beberapa pengekspor secara bersamaan, Anda harus membuat objek TracerProvider kustom. Dalam kasus ini, Anda dapat menggunakan pengekspor Cloud Trace secara langsung:

namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  // Use the Cloud Trace Exporter directly.
  auto project = gc::Project(std::move(project_id));
  auto exporter = gc::otel::MakeTraceExporter(project);

  // Advanced use cases may need to create their own tracer provider, e.g. to
  // export to Cloud Trace and another backend simultaneously. In this
  // example, we just tweak some OpenTelemetry settings that google-cloud-cpp
  // does not expose.
  opentelemetry::sdk::trace::BatchSpanProcessorOptions options;
  options.schedule_delay_millis = std::chrono::milliseconds(1000);
  auto processor =
      opentelemetry::sdk::trace::BatchSpanProcessorFactory::Create(
          std::move(exporter), options);

  // Create a tracer provider and set it as the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      std::shared_ptr<opentelemetry::trace::TracerProvider>(
          opentelemetry::sdk::trace::TracerProviderFactory::Create(
              std::move(processor))));

  MyApplicationCode();

  // Clear the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      opentelemetry::nostd::shared_ptr<
          opentelemetry::trace::TracerProvider>());
}

Menginstrumentasikan aplikasi Anda sendiri

Untuk mengetahui informasi tentang cara mengonfigurasi aplikasi Anda untuk mengambil trace span, lihat OpenTelemetry Tracing. Halaman ini menjelaskan cara melakukan semua hal berikut:

  • Membuat span
  • Membuat span bertingkat
  • Menetapkan atribut span
  • Membuat span dengan peristiwa
  • Membuat span dengan link
// For more details on the OpenTelemetry code in this sample, see:
//     https://opentelemetry.io/docs/instrumentation/cpp/manual/
namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  // Initialize the `Tracer`. This would typically be done once.
  auto provider = opentelemetry::trace::Provider::GetTracerProvider();
  auto tracer = provider->GetTracer("my-application");

  // If your application makes multiple client calls that are logically
  // connected, you may want to instrument your application.
  auto my_function = [tracer] {
    // Start an active span. The span is ended when the `Scope` object is
    // destroyed.
    auto scope = Scope(tracer->StartSpan("my-function-span"));

    // Any spans created by the client library will be children of
    // "my-function-span". i.e. In the distributed trace, the client calls are
    // sub-units of work of `my_function()`, and will be displayed as such in
    // Cloud Trace.
    Client client;
    client.CreateFoo();
    client.DeleteFoo();
  };

  // As an example, start a span to cover both calls to `my_function()`.
  auto scope = Scope(tracer->StartSpan("my-application-span"));
  my_function();
  my_function();
}

Contoh aplikasi

Untuk contoh aplikasi, lihat panduan memulai.

Mengonfigurasi platform Anda

Anda dapat menggunakan Cloud Trace di Google Cloud dan platform lainnya.

Menjalankan di Google Cloud

Saat aplikasi Anda berjalan di Google Cloud, Anda tidak perlu memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Namun, Anda harus memastikan bahwa platform Google Cloud Anda memiliki cakupan akses Cloud Trace API yang diaktifkan.

Untuk mengetahui daftar lingkungan yang didukung Google Cloud , lihat Dukungan lingkungan.

Untuk konfigurasi berikut, setelan cakupan akses default mengaktifkan Cloud Trace API:

Jika Anda menggunakan cakupan akses kustom, Anda harus memastikan bahwa cakupan akses Cloud Trace API diaktifkan:

  • Untuk mengetahui informasi tentang cara mengonfigurasi cakupan akses untuk lingkungan Anda menggunakan Google Cloud konsol, lihat Mengonfigurasi project Google Cloud Anda.

  • Untuk pengguna gcloud, tentukan cakupan akses menggunakan flag --scopes dan sertakan cakupan akses Cloud Trace API trace.append. Misalnya, untuk membuat cluster GKE dengan hanya Cloud Trace API yang diaktifkan, lakukan hal berikut:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Menjalankan secara lokal dan di tempat lain

Jika aplikasi Anda berjalan di luar Google Cloud, Anda harus memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Akun layanan harus berisi peran agen Cloud Trace. Untuk mengetahui petunjuknya, lihat Membuat akun layanan.

Google Cloud library klien menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial aplikasi Anda.

Anda dapat memberikan kredensial ini dengan salah satu dari tiga cara:

  • Jalankan gcloud auth application-default login

  • Tempatkan akun layanan di jalur default untuk sistem operasi Anda. Berikut adalah jalur default untuk Windows dan Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur akun layanan Anda:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Melihat trace

Di Google Cloud konsol, buka halaman Trace explorer:

Buka Trace explorer

Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

Pemecahan masalah

Untuk mengetahui informasi tentang cara memecahkan masalah Cloud Trace, buka halaman Pemecahan masalah.

Untuk men-debug pengekspor Cloud Trace C++, lihat bagian Pemecahan masalah pada dokumentasi referensi.

Resource