Instrument and report C++ application data by using the OpenTelemetry client - Managed Service for OpenTelemetry: Central de Documentação do Alibaba Cloud

Como funciona

O SDK do OpenTelemetry C++ utiliza três componentes principais para coletar e exportar dados de rastreamento:

Componente	Função
TracerProvider	Cria e gerencia tracers. Cada tracer produz spans que representam unidades de trabalho.
SpanProcessor	Recebe spans concluídos e os encaminha para um exporter. O `SimpleSpanProcessor` exporta cada span imediatamente, sendo adequado para demonstrações. Em produção, utilize o `BatchSpanProcessor` para obter melhor throughput.
OTLP exporter	Envia spans para um backend via HTTP ou gRPC. Este guia utiliza o Managed Service for OpenTelemetry como backend.

Pré-requisitos

Obter o endpoint e o token de autenticação

Faça login no console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations e, em seguida, na aba Access point information.
Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.
Defina o parâmetro Client como OpenTelemetry.

Na coluna Related Information, copie o endpoint e o token correspondentes ao seu ambiente de rede. Para gRPC, copie também o token de autenticação exibido na mesma linha.

Implantação	Endpoint a ser usado
No Alibaba Cloud (ECS, ACK ou outros serviços do Alibaba Cloud)	Endpoint de VPC
Fora do Alibaba Cloud ou desenvolvimento local	Endpoint público

Access point information

Requisitos de ambiente

C++ 11 ou superior
Para versões de compiladores C++ e plataformas compatíveis, consulte versões compatíveis do opentelemetry-cpp

Código de exemplo

O código de exemplo completo está disponível em alibabacloud-observability/cpp-demo.

Preparar o ambiente

(Opcional) Inicie um container Docker com a toolchain GCC:

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

Instale as dependências do sistema (protobuf, gRPC e ferramentas de 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

Compilar e instalar o SDK do OpenTelemetry C++

Clone o repositório, compile com suporte ao OTLP exporter e instale em /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

Relatar dados de rastreamento

Escolha um protocolo de transporte. Tanto HTTP quanto gRPC exportam spans para o Managed Service for OpenTelemetry. Utilize o endpoint correspondente indicado na seção Pré-requisitos.

Protocolo	Quando usar	Autenticação
HTTP	Configuração mais simples; funciona na maioria dos proxies e firewalls	A URL do endpoint contém credenciais incorporadas
gRPC	Menor sobrecarga para grandes volumes de dados de rastreamento	Requer um token de autenticação separado

Relatar dados via HTTP

Crie um diretório para o projeto:

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

Crie um arquivo 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
   )

Crie um arquivo http_exporter.cc. Substitua os placeholders abaixo pelos valores reais:

Placeholder	Descrição	Exemplo
`<your-service-name>`	Nome que identifica sua aplicação no console do ARMS	`my-cpp-service`
`<your-host-name>`	Hostname da máquina que executa a aplicação	`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 o projeto:

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

Execute a demonstração. Passe o endpoint HTTP obtido na seção Pré-requisitos como primeiro argumento. Exemplo: Para ativar logs de depuração e confirmar a exportação dos spans, passe yes como segundo argumento. Se o programa terminar sem erros, os spans foram exportados. Prossiga para Verificar dados de rastreamento e confirme se eles aparecem no console.
```
   ./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
```

Relatar dados via gRPC

Crie um diretório para o projeto:

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

Crie um arquivo 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
   )

Crie um arquivo grpc_exporter.cc. Substitua os placeholders abaixo pelos valores reais:

Placeholder	Descrição	Exemplo
`<your-service-name>`	Nome que identifica sua aplicação no console do ARMS	`my-cpp-service`
`<your-host-name>`	Hostname da máquina que executa a aplicação	`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 o projeto:

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

Execute a demonstração. Informe o endpoint gRPC e o token de autenticação obtidos na seção Pré-requisitos. Exemplo: Se o programa terminar sem erros, os spans foram exportados. Prossiga para Verificar dados de rastreamento e confirme se eles aparecem no console.
```
   ./otel-grpc-export-demo <gRPC-endpoint> <token>
```
```
   ./otel-grpc-export-demo http://tracing-analysis-dc-hz.aliyuncs.com:8090 xxxxx_xxxxxx
```

Solução de problemas

Biblioteca compartilhada não encontrada

Se o erro abaixo aparecer ao executar a demonstração:

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

Adicione o caminho de instalação do SDK do OpenTelemetry C++ ao caminho de busca de bibliotecas:

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

O caminho /usr/local/lib é o padrão de instalação. Caso tenha instalado o SDK em um caminho personalizado, faça a substituição adequada.

Verificar dados de rastreamento

Faça login no console do ARMS.
No painel de navegação à esquerda, escolha Application Monitoring > Applications.
Localize o nome da sua aplicação na lista e clique nele para visualizar os dados de rastreamento, incluindo topologia, traces individuais e métricas de desempenho.

O ícone na coluna Language indica a origem dos dados. O ícone significa que a aplicação está conectada ao Application Monitoring. Um hífen ( - ) indica conexão com o Managed Service for OpenTelemetry.

Recomendações para produção

O código de demonstração deste guia usa o SimpleSpanProcessor, que exporta cada span de forma síncrona e bloqueia a thread chamadora. Para cargas de trabalho em produção:

Mude para o BatchSpanProcessor para armazenar em buffer e exportar spans em lotes, reduzindo a sobrecarga de rede e o impacto na latência da aplicação.
Defina atributos de recurso (service.name, host.name, service.version) com valores significativos para permitir filtragem e agrupamento de traces no console do ARMS.
Para o exporter gRPC, considere ativar SSL (opts.use_ssl_credentials = true) ao enviar dados de rastreamento pela internet pública.

Managed Service for OpenTelemetry:Use OpenTelemetry to report trace data of C++ applications