Instrument and report C++ application data by using the OpenTelemetry client - Application Real-Time Monitoring Service

El rastreo distribuido le permite identificar cuellos de botella de latencia y fallos en sus microservices. Al instrumentar su aplicación C++ con el SDK de OpenTelemetry para C++, puede exportar datos de rastreo a Managed Service for OpenTelemetry mediante HTTP o gRPC. Una vez establecida la conexión, la consola de ARMS muestra la topología de la aplicación, los rastreos, las transacciones anómalas y lentas, así como el análisis SQL correspondiente.

Funcionamiento

El SDK de OpenTelemetry para C++ utiliza tres componentes principales para recopilar y exportar datos de rastreo:

Componente	Función
TracerProvider	Crea y gestiona los trazadores. Cada trazador genera spans que representan unidades de trabajo.
SpanProcessor	Recibe los spans completados y los reenvía a un exportador. `SimpleSpanProcessor` exporta cada span de inmediato, por lo que es adecuado para demostraciones. Para entornos de producción, utilice `BatchSpanProcessor` para obtener un mejor throughput.
Exportador OTLP	Envía spans a un backend mediante HTTP o gRPC. Esta guía utiliza Managed Service for OpenTelemetry como backend.

Requisitos previos

Obtención del endpoint y token de autenticación

Inicie sesión en la consola de Managed Service for OpenTelemetry.
En el panel de navegación izquierdo, haga clic en Cluster Configurations y luego seleccione la pestaña Access point information.
En la barra de navegación superior, seleccione una región. En la sección Cluster Information, active la opción Show Token.
Establezca el parámetro Client en OpenTelemetry.
En la columna Related Information, copie el endpoint y el token que correspondan a su entorno de red. Para gRPC, copie también el token de autenticación que se muestra en la misma fila.

Despliegue

Endpoint recomendado

En Alibaba Cloud (ECS, ACK u otros servicios de Alibaba Cloud)

Endpoint de VPC

Fuera de Alibaba Cloud o desarrollo local

Endpoint público

Requisitos del entorno

C++ 11 o posterior
Para consultar las versiones compatibles de compiladores de C++ y plataformas, revise Versiones compatibles de opentelemetry-cpp

Código de ejemplo

El código de ejemplo completo está disponible en alibabacloud-observability/cpp-demo.

Preparación del entorno

(Opcional) Inicie un contenedor Docker con la cadena de herramientas de GCC:

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

Instale las dependencias del sistema (protobuf, gRPC y herramientas de compilación):

   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

Compilación e instalación del SDK de OpenTelemetry para C++

Clone el repositorio, compile con soporte para el exportador OTLP e instale en /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

Reporte de datos de rastreo

Elija un protocolo de transporte. Tanto HTTP como gRPC permiten exportar spans a Managed Service for OpenTelemetry. Utilice el endpoint correspondiente indicado en la sección de Requisitos previos.

Protocolo	Cuándo utilizarlo	Autenticación
HTTP	Configuración más sencilla; funciona con la mayoría de proxies y firewalls	La URL del endpoint contiene credenciales integradas
gRPC	Menor sobrecarga para grandes volúmenes de datos de rastreo	Requiere un token de autenticación independiente

Reporte de datos mediante HTTP

Cree un directorio para el proyecto:

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

Cree un archivo 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
   )

Cree un archivo http_exporter.cc. Reemplace los siguientes marcadores de posición con sus valores reales:

Marcador de posición	Descripción	Ejemplo
`<your-service-name>`	Nombre que identifica a su aplicación en la consola de ARMS	`my-cpp-service`
`<your-host-name>`	Nombre de host de la máquina que ejecuta la aplicación	`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();
   }

Compile el proyecto:

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

Ejecute la demostración. Pase el endpoint HTTP obtenido en la sección de Requisitos previos como primer argumento. Ejemplo: Para habilitar el registro de depuración y confirmar que los spans se exportan correctamente, pase yes como segundo argumento. Si el programa finaliza sin errores, significa que los spans se exportaron. Continúe con la sección Verificación de datos de rastreo para confirmar su aparición en la consola.
```
   ./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
```

Reporte de datos mediante gRPC

Cree un directorio para el proyecto:

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

Cree un archivo 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
   )

Cree un archivo grpc_exporter.cc. Reemplace los siguientes marcadores de posición con sus valores reales:

Marcador de posición	Descripción	Ejemplo
`<your-service-name>`	Nombre que identifica a su aplicación en la consola de ARMS	`my-cpp-service`
`<your-host-name>`	Nombre de host de la máquina que ejecuta la aplicación	`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();
   }

Compile el proyecto:

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

Ejecute la demostración. Pase el endpoint de gRPC y el token de autenticación obtenidos en la sección de Requisitos previos. Ejemplo: Si el programa finaliza sin errores, significa que los spans se exportaron. Continúe con la sección Verificación de datos de rastreo para confirmar su aparición en la consola.
```
   ./otel-grpc-export-demo <gRPC-endpoint> <token>
```
```
   ./otel-grpc-export-demo http://tracing-analysis-dc-hz.aliyuncs.com:8090 xxxxx_xxxxxx
```

Solución de problemas

Biblioteca compartida no encontrada

Si observa el siguiente error al ejecutar la demostración:

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

Agregue la ruta de instalación del SDK de OpenTelemetry para C++ a la ruta de búsqueda de bibliotecas:

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

La ruta /usr/local/lib es la ubicación de instalación predeterminada. Si instaló el SDK en una ruta personalizada, ajústela según corresponda.

Verificación de datos de rastreo

Inicie sesión en la consola de ARMS.
En el panel de navegación izquierdo, seleccione Application Monitoring > Applications.
Localice el nombre de su aplicación en la lista y haga clic en él para consultar los datos de rastreo, incluida la topología, los rastreos individuales y las métricas de rendimiento.

El icono en la columna Language indica el origen de los datos. El icono significa que la aplicación está conectada a Application Monitoring. Un guion ( - ) indica que está conectada a Managed Service for OpenTelemetry.

Recomendaciones para producción

El código de demostración de esta guía utiliza SimpleSpanProcessor, el cual exporta cada span de forma síncrona y bloquea el hilo de ejecución llamante. Para cargas de trabajo en producción:

Cambie a BatchSpanProcessor para almacenar en búfer y exportar spans por lotes; esto reduce la sobrecarga de red y el impacto en la latencia de su aplicación.
Configure atributos de recurso (service.name, host.name, service.version) con valores significativos para poder filtrar y agrupar rastreos en la consola de ARMS.
Para el exportador de gRPC, considere habilitar SSL (opts.use_ssl_credentials = true) cuando envíe datos de rastreo a través de internet público.

Application Real-Time Monitoring Service:Use OpenTelemetry to report trace data of C++ applications