Instrumen aplikasi C++ dengan OpenTelemetry untuk melaporkan data trace - Application Real-Time Monitoring Service

Distributed tracing membantu Anda mengidentifikasi bottleneck latensi dan kegagalan di seluruh layanan mikro. Dengan menginstrumentasi aplikasi C++ menggunakan SDK OpenTelemetry C++, Anda dapat mengekspor data jejak ke Managed Service for OpenTelemetry melalui HTTP atau gRPC. Setelah terhubung, Konsol ARMS akan menampilkan topologi aplikasi, jejak, transaksi abnormal dan lambat, serta analisis SQL untuk aplikasi Anda.

Cara kerja

SDK OpenTelemetry C++ menggunakan tiga komponen inti untuk mengumpulkan dan mengekspor data jejak:

Component	Role
TracerProvider	Membuat dan mengelola tracer. Setiap tracer menghasilkan span yang merepresentasikan unit pekerjaan.
SpanProcessor	Menerima span yang telah selesai dan meneruskannya ke exporter. `SimpleSpanProcessor` mengekspor setiap span secara langsung dan cocok untuk demo. Untuk produksi, gunakan `BatchSpanProcessor` untuk throughput yang lebih baik.
OTLP exporter	Mengirim span ke backend melalui HTTP atau gRPC. Panduan ini menggunakan Managed Service for OpenTelemetry sebagai backend.

Prasyarat

Dapatkan endpoint dan token otentikasi

Masuk ke Konsol Managed Service for OpenTelemetry.
Pada panel navigasi kiri, klik Cluster Configurations, lalu klik tab Access point information.
Pada bilah navigasi atas, pilih wilayah. Di bagian Cluster Information, aktifkan Show Token.
Atur parameter Client ke OpenTelemetry.
Pada kolom Related Information, salin endpoint dan token yang sesuai dengan lingkungan jaringan Anda. Untuk gRPC, salin juga token otentikasi yang ditampilkan pada baris yang sama.
Deployment Endpoint to use
Di Alibaba Cloud (ECS, ACK, atau layanan Alibaba Cloud lainnya) VPC endpoint
Di luar Alibaba Cloud atau pengembangan lokal Public endpoint

Deployment	Endpoint to use
Di Alibaba Cloud (ECS, ACK, atau layanan Alibaba Cloud lainnya)	VPC endpoint
Di luar Alibaba Cloud atau pengembangan lokal	Public endpoint

Persyaratan lingkungan

C++ 11 atau versi yang lebih baru
Untuk informasi versi compiler C++ dan platform yang didukung, lihat versi yang didukung opentelemetry-cpp.

Kode contoh

Kode contoh lengkap tersedia di alibabacloud-observability/cpp-demo.

Persiapkan lingkungan

(Opsional) Jalankan kontainer Docker dengan rantai alat GCC:

   docker pull gcc                               # Debian-based image
   docker run -it --name otel-cpp-demo gcc bash

Instal dependensi sistem (protobuf, gRPC, dan alat build):

   apt-get update
   apt-get install sudo

   sudo apt-get install git cmake g++ libcurl4-openssl-dev
   # protobuf
   sudo apt-get install protobuf-compiler libprotobuf-dev
   # gRPC
   sudo apt-get install -y libgrpc++-dev libgrpc-dev protobuf-compiler-grpc

Build dan instal SDK OpenTelemetry C++

Klon repositori, build dengan dukungan exporter OTLP, dan instal ke /usr/local:

git clone --recurse-submodules https://github.com/open-telemetry/opentelemetry-cpp

cd opentelemetry-cpp
mkdir build && cd build
cmake -DBUILD_TESTING=OFF -DWITH_OTLP_GRPC=ON -DWITH_OTLP_HTTP=ON ..

cmake --build . --target all

# Install to /usr/local (recommended default path)
cmake --install .

# To install to a custom path instead, uncomment the following line:
# cmake --install . --prefix /opentelemetry-cpp-lib

Laporkan data jejak

Pilih protokol transportasi. Baik HTTP maupun gRPC dapat mengekspor span ke Managed Service for OpenTelemetry. Gunakan endpoint yang sesuai dari bagian Prasyarat.

Protocol	When to use	Authentication
HTTP	Pengaturan lebih sederhana, berfungsi melalui sebagian besar proxy dan firewall	URL endpoint berisi kredensial yang tertanam
gRPC	Overhead lebih rendah untuk data jejak ber-volume tinggi	Memerlukan token otentikasi terpisah

Laporkan data melalui HTTP

Buat direktori proyek:

   mkdir otel-http-export-demo
   cd otel-http-export-demo

Buat file CMakeLists.txt:

   cmake_minimum_required(VERSION 3.25.1)
   project(otel-http-export-demo)

   add_executable(otel-http-export-demo http_exporter.cc)

   find_package(opentelemetry-cpp CONFIG REQUIRED)
   find_package(protobuf)
   find_package(gRPC)
   find_package(CURL)
   find_package(nlohmann_json)

   include_directories("${OPENTELEMETRY_CPP_INCLUDE_DIRS}")

   target_link_libraries(
       otel-http-export-demo
       opentelemetry_trace
       opentelemetry_common
       opentelemetry_http_client_curl
       opentelemetry_exporter_otlp_http
       opentelemetry_exporter_otlp_grpc
       opentelemetry_exporter_otlp_http_client
       opentelemetry_otlp_recordable
       opentelemetry_resources
   )

Buat file http_exporter.cc. Ganti placeholder berikut dengan nilai aktual Anda:

Placeholder	Description	Example
`<your-service-name>`	Nama yang mengidentifikasi aplikasi Anda di Konsol ARMS	`my-cpp-service`
`<your-host-name>`	Hostname mesin yang menjalankan aplikasi	`prod-server-01`

   // Copyright The OpenTelemetry Authors
   // SPDX-License-Identifier: Apache-2.0

   #include "opentelemetry/exporters/otlp/otlp_http_exporter_factory.h"
   #include "opentelemetry/exporters/otlp/otlp_http_exporter_options.h"
   #include "opentelemetry/context/propagation/global_propagator.h"
   #include "opentelemetry/context/propagation/text_map_propagator.h"
   #include "opentelemetry/exporters/ostream/span_exporter_factory.h"
   #include "opentelemetry/nostd/shared_ptr.h"
   #include "opentelemetry/sdk/trace/simple_processor_factory.h"
   #include "opentelemetry/sdk/trace/tracer_context.h"
   #include "opentelemetry/sdk/trace/tracer_context_factory.h"
   #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
   #include "opentelemetry/trace/propagation/http_trace_context.h"
   #include "opentelemetry/trace/provider.h"
   #include "opentelemetry/ext/http/client/http_client_factory.h"
   #include "opentelemetry/sdk/resource/semantic_conventions.h"
   #include "opentelemetry/sdk/common/global_log_handler.h"

   #include <string>


   namespace trace     = opentelemetry::trace;
   namespace trace_sdk = opentelemetry::sdk::trace;
   namespace otlp      = opentelemetry::exporter::otlp;
   namespace internal_log = opentelemetry::sdk::common::internal_log;
   namespace resource = opentelemetry::sdk::resource;

   namespace nostd = opentelemetry::nostd;

   namespace
   {
       opentelemetry::exporter::otlp::OtlpHttpExporterOptions opts;
       void InitTracer()
       {
           // Create an OTLP/HTTP exporter that sends spans to the configured endpoint.
           auto exporter  = otlp::OtlpHttpExporterFactory::Create(opts);
           // SimpleSpanProcessor exports each span immediately. For production,
           // consider BatchSpanProcessor to reduce network overhead.
           auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));

           // Set resource attributes so ARMS can identify this application.
           resource::ResourceAttributes attributes = {
                   {resource::SemanticConventions::kServiceName, "<your-service-name>"},
                   {resource::SemanticConventions::kHostName, "<your-host-name>"}
           };
           auto resource = opentelemetry::sdk::resource::Resource::Create(attributes);

           std::shared_ptr<opentelemetry::trace::TracerProvider> provider =
                   trace_sdk::TracerProviderFactory::Create(std::move(processor), std::move(resource));

           // Register as the global tracer provider.
           trace::Provider::SetTracerProvider(provider);
       }

       void CleanupTracer()
       {
           std::shared_ptr<opentelemetry::trace::TracerProvider> none;
           trace::Provider::SetTracerProvider(none);
       }

       nostd::shared_ptr<trace::Tracer> get_tracer()
       {
           auto provider = trace::Provider::GetTracerProvider();
           return provider->GetTracer("library name to trace", OPENTELEMETRY_SDK_VERSION);
       }

       void f1()
       {
           auto scoped_span = trace::Scope(get_tracer()->StartSpan("f1"));
       }

       void f2()
       {
           auto scoped_span = trace::Scope(get_tracer()->StartSpan("f2"));

           f1();
           f1();
       }

       void foo_library()
       {
           auto scoped_span = trace::Scope(get_tracer()->StartSpan("library"));

           f2();
       }
   }  // namespace

   /*
     Usage:
     - example_otlp_http
     - example_otlp_http <URL>
     - example_otlp_http <URL> <DEBUG>
     - example_otlp_http <URL> <DEBUG> <BIN>
     <DEBUG> = yes|no, to turn console debug on or off
     <BIN> = bin, to export in binary format
   */
   int main(int argc, char *argv[])
   {
       if (argc > 1)
       {
           opts.url = argv[1];
           if (argc > 2)
           {
               std::string debug  = argv[2];
               opts.console_debug = debug != "" && debug != "0" && debug != "no";
           }

           if (argc > 3)
           {
               std::string binary_mode = argv[3];
               if (binary_mode.size() >= 3 && binary_mode.substr(0, 3) == "bin")
               {
                   opts.content_type = otlp::HttpRequestContentType::kBinary;
               }
           }
       }

       if (opts.console_debug)
       {
           internal_log::GlobalLogHandler::SetLogLevel(internal_log::LogLevel::Debug);
       }

       InitTracer();

       foo_library();

       CleanupTracer();
   }

Build proyek:

   mkdir build && cd build && cmake .. && make

Jalankan demo. Berikan endpoint HTTP dari bagian Prasyarat sebagai argumen pertama. Contoh: Untuk mengaktifkan logging debug dan memastikan span diekspor, berikan yes sebagai argumen kedua. Jika program keluar tanpa error, span telah diekspor. Lanjutkan ke Verifikasi data jejak untuk memastikan data tersebut muncul di konsol.
```
   ./otel-http-export-demo <http-endpoint>
```
```
   ./otel-http-export-demo http://tracing-analysis-dc-hz.aliyuncs.com/adapt_xxxxx_xxxxx/api/otlp/traces
```
```
   ./otel-http-export-demo <http-endpoint> yes
```

Laporkan data melalui gRPC

Buat direktori proyek:

   mkdir otel-grpc-export-demo
   cd otel-grpc-export-demo

Buat file CMakeLists.txt:

   cmake_minimum_required(VERSION 3.25.1)
   project(otel-grpc-export-demo)

   add_executable(otel-grpc-export-demo grpc_exporter.cc)

   find_package(opentelemetry-cpp CONFIG REQUIRED)
   find_package(protobuf)
   find_package(gRPC)
   find_package(CURL)
   find_package(nlohmann_json)

   include_directories("${OPENTELEMETRY_CPP_INCLUDE_DIRS}")

   target_link_libraries(
       otel-grpc-export-demo ${OPENTELEMETRY_CPP_LIBRARIES}
       opentelemetry_trace
       opentelemetry_common
       opentelemetry_http_client_curl
       opentelemetry_exporter_otlp_http
       opentelemetry_exporter_otlp_grpc
       opentelemetry_exporter_otlp_http_client
       opentelemetry_otlp_recordable
       opentelemetry_resources
   )

Buat file grpc_exporter.cc. Ganti placeholder berikut dengan nilai aktual Anda:

Placeholder	Description	Example
`<your-service-name>`	Nama yang mengidentifikasi aplikasi Anda di Konsol ARMS	`my-cpp-service`
`<your-host-name>`	Hostname mesin yang menjalankan aplikasi	`prod-server-01`

   // Copyright The OpenTelemetry Authors
   // SPDX-License-Identifier: Apache-2.0

   #include "opentelemetry/exporters/otlp/otlp_grpc_exporter_factory.h"
   #include "opentelemetry/exporters/otlp/otlp_grpc_exporter_options.h"
   #include "opentelemetry/context/propagation/global_propagator.h"
   #include "opentelemetry/context/propagation/text_map_propagator.h"
   #include "opentelemetry/exporters/ostream/span_exporter_factory.h"
   #include "opentelemetry/nostd/shared_ptr.h"
   #include "opentelemetry/sdk/trace/simple_processor_factory.h"
   #include "opentelemetry/sdk/trace/tracer_context.h"
   #include "opentelemetry/sdk/trace/tracer_context_factory.h"
   #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
   #include "opentelemetry/trace/propagation/http_trace_context.h"
   #include "opentelemetry/trace/provider.h"
   #include "opentelemetry/ext/http/client/http_client_factory.h"
   #include "opentelemetry/sdk/resource/semantic_conventions.h"
   #include "opentelemetry/sdk/common/global_log_handler.h"

   #include <string>


   namespace trace     = opentelemetry::trace;
   namespace trace_sdk = opentelemetry::sdk::trace;
   namespace otlp      = opentelemetry::exporter::otlp;
   namespace internal_log = opentelemetry::sdk::common::internal_log;
   namespace resource = opentelemetry::sdk::resource;

   namespace nostd = opentelemetry::nostd;

   namespace
   {
       opentelemetry::exporter::otlp::OtlpGrpcExporterOptions opts;
       void InitTracer()
       {
           // Create an OTLP/gRPC exporter that sends spans to the configured endpoint.
           auto exporter  = otlp::OtlpGrpcExporterFactory::Create(opts);
           // SimpleSpanProcessor exports each span immediately. For production,
           // consider BatchSpanProcessor to reduce network overhead.
           auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));

           // Set resource attributes so ARMS can identify this application.
           resource::ResourceAttributes attributes = {
                   {resource::SemanticConventions::kServiceName, "<your-service-name>"},
                   {resource::SemanticConventions::kHostName, "<your-host-name>"}
           };
           auto resource = opentelemetry::sdk::resource::Resource::Create(attributes);

           std::shared_ptr<opentelemetry::trace::TracerProvider> provider =
                   trace_sdk::TracerProviderFactory::Create(std::move(processor), std::move(resource));

           // Register as the global tracer provider.
           trace::Provider::SetTracerProvider(provider);
       }

       void CleanupTracer()
       {
           std::shared_ptr<opentelemetry::trace::TracerProvider> none;
           trace::Provider::SetTracerProvider(none);
       }

       nostd::shared_ptr<trace::Tracer> get_tracer()
       {
           auto provider = trace::Provider::GetTracerProvider();
           return provider->GetTracer("library name to trace", OPENTELEMETRY_SDK_VERSION);
       }

       void f1()
       {
           auto scoped_span = trace::Scope(get_tracer()->StartSpan("f1"));
       }

       void f2()
       {
           auto scoped_span = trace::Scope(get_tracer()->StartSpan("f2"));

           f1();
           f1();
       }

       void foo_library()
       {
           auto scoped_span = trace::Scope(get_tracer()->StartSpan("library"));

           f2();
       }
   }  // namespace

   /*
     Usage:
     - example_otlp_grpc
     - example_otlp_grpc <URL> <TOKEN>
   */
   int main(int argc, char *argv[])
   {
       if (argc > 1)
       {
           opts.endpoint = argv[1];
           if (argc > 2)
           {
               opts.metadata.insert(std::pair<std::string, std::string>("authentication",argv[2]));
           }

           if (argc > 3)
           {
               opts.use_ssl_credentials         = true;
               opts.ssl_credentials_cacert_path = argv[3];
           }
       }

       InitTracer();

       foo_library();

       CleanupTracer();
   }

Bangun proyek:

   mkdir build && cd build && cmake .. && make

Jalankan demo. Berikan endpoint gRPC dan token otentikasi dari bagian Prasyarat. Contoh: Jika program keluar tanpa error, span telah diekspor. Lanjutkan ke Verifikasi data jejak untuk memastikan data tersebut muncul di konsol.
```
   ./otel-grpc-export-demo <gRPC-endpoint> <token>
```
```
   ./otel-grpc-export-demo http://tracing-analysis-dc-hz.aliyuncs.com:8090 xxxxx_xxxxxx
```

Pemecahan masalah

Shared library tidak ditemukan

Jika Anda melihat error berikut saat menjalankan demo:

./otel-grpc-export-demo: error while loading shared libraries: libopentelemetry_proto_grpc.so: cannot open shared object file: No such file or directory

Tambahkan path instalasi SDK OpenTelemetry C++ ke path pencarian library:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib/

/usr/local/lib adalah path instalasi default. Jika Anda menginstal SDK ke path kustom, ganti sesuai kebutuhan.

Verifikasi data jejak

Masuk ke Konsol ARMS.
Pada panel navigasi kiri, pilih Application Monitoring > Applications.
Temukan nama aplikasi Anda dalam daftar dan klik untuk melihat data jejak, termasuk topologi, jejak individual, dan metrik performa.

Kolom ikon Language menunjukkan sumber data. Ikon berarti aplikasi terhubung ke Application Monitoring. Tanda hubung (-) berarti aplikasi terhubung ke Managed Service for OpenTelemetry.

Rekomendasi produksi

Kode demo dalam panduan ini menggunakan SimpleSpanProcessor, yang mengekspor setiap span secara sinkron dan memblokir thread pemanggil. Untuk beban kerja produksi:

Beralihlah ke BatchSpanProcessor untuk menyimpan buffer dan mengekspor span secara batch, sehingga mengurangi overhead jaringan dan dampak latensi pada aplikasi Anda.
Atur atribut resource (service.name, host.name, service.version) ke nilai yang bermakna agar Anda dapat memfilter dan mengelompokkan jejak di Konsol ARMS.
Untuk exporter gRPC, pertimbangkan untuk mengaktifkan SSL (opts.use_ssl_credentials = true) saat mengirim data jejak melalui internet publik.

Application Real-Time Monitoring Service:Gunakan OpenTelemetry untuk melaporkan data jejak aplikasi C++