C++ e OpenTelemetry

Esta página destina-se a programadores de aplicações que pretendem recolher dados do Cloud Trace para aplicações C++ através do OpenTelemetry. O OpenTelemetry é uma framework de instrumentação independente do fornecedor que pode usar para recolher dados de rastreio e métricas. Para obter informações sobre como capacitar o seu código com instrumentos, consulte o artigo Capacitação com instrumentos e observabilidade.

Esta página explica os seguintes passos:

  • Instale os pacotes OpenTelemetry.
  • Configure a sua aplicação para exportar intervalos para o Cloud Trace.
  • Configure a sua plataforma.

Para ver informações sobre o lançamento, consulte o seguinte:

Para conteúdo de referência do OpenTelemetry, consulte o seguinte:

Para ver os detalhes mais recentes sobre o OpenTelemetry para C++, juntamente com documentação e exemplos adicionais, consulte OpenTelemetry.

Antes de começar

Enable the Cloud Trace API.

Enable the API

Instale os pacotes OpenTelemetry

Configure a exportação de intervalos para o Cloud Trace

Para configurar a exportação de dados de rastreio, chame o método google::cloud::otel::ConfigureBasicTracing(...) no seu método main():

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

  MyApplicationCode();
}

O campo project_id é o Google Cloud projeto onde quer armazenar os rastreios.

O método ConfigureBasicTracing(...) instancia um objeto TracerProvider que implementa um exportador do Cloud Trace. Se o objeto devolvido pela chamada a ConfigureBasicTracing(...) sair do âmbito, o objeto TracerProvider anterior é reposto, quando existir.

Configure a taxa de amostragem

As aplicações podem gerar um grande volume de dados de rastreio. O exemplo seguinte ilustra como configurar a taxa de amostragem:

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();
}

Exporte para o Cloud Trace com um TracerProvider personalizado

Pode ter exemplos de utilização que requerem um objeto TracerProvider personalizado. Por exemplo, se quiser usar vários exportadores em simultâneo, tem de criar um objeto TracerProvider personalizado. Nestes casos, pode usar o exportador do Cloud Trace diretamente:

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>());
}

Instrumente a sua própria aplicação

Para obter informações sobre como configurar a sua aplicação para capturar intervalos de rastreio, consulte o artigo Rastreio do OpenTelemetry. Esta página descreve como fazer o seguinte:

  • Crie um intervalo
  • Crie intervalos aninhados
  • Defina atributos de intervalo
  • Crie intervalos com eventos
  • Crie intervalos com links
// 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();
}

Aplicação de exemplo

Para uma aplicação de exemplo, consulte o início rápido.

Configure a sua plataforma

Pode usar o Cloud Trace no Google Cloud e noutras plataformas.

Em execução no dispositivo Google Cloud

Quando a sua aplicação está a ser executada no Google Cloud, não precisa de fornecer credenciais de autenticação sob a forma de uma conta de serviço à biblioteca de cliente. No entanto, tem de garantir que a sua plataforma tem o âmbito de acesso da API Cloud Trace ativado. Google Cloud

Para ver uma lista dos Google Cloud ambientes suportados, consulte a secção Suporte de ambientes.

Para as seguintes configurações, as predefinições do âmbito de acesso ativam a API Cloud Trace:

Se usar âmbitos de acesso personalizados, tem de garantir que o âmbito de acesso da API Cloud Trace está ativado:

  • Para informações sobre como configurar os âmbitos de acesso para o seu ambiente através da consola, consulte o artigo Configurar o seu projeto. Google Cloud Google Cloud

  • Para utilizadores do gcloud, especifique os âmbitos de acesso através da flag --scopes e inclua o âmbito de acesso da API Cloud Trace trace.append. Por exemplo, para criar um cluster do GKE com apenas a API Cloud Trace ativada, faça o seguinte:

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

Execução local e noutros locais

Se a sua aplicação estiver a ser executada fora do Google Cloud, tem de fornecer credenciais de autenticação sob a forma de uma conta de serviço à biblioteca de cliente. A conta de serviço tem de conter a função de agente do Cloud Trace. Para ver instruções, consulte o artigo Criar uma conta de serviço.

Google Cloud As bibliotecas cliente usam Credenciais padrão da aplicação (ADC) para encontrar as credenciais da sua aplicação.

Pode facultar estas credenciais de uma de três formas:

  • Execução gcloud auth application-default login

  • Coloque a conta de serviço num caminho predefinido para o seu sistema operativo. A lista seguinte apresenta os caminhos predefinidos para o Windows e o Linux:

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

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

  • Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para o caminho da sua conta de serviço:

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"

Ver rastreios

Na Google Cloud consola, aceda à página Explorador de rastreios:

Aceda ao Explorador de rastreios

Também pode encontrar esta página através da barra de pesquisa.

Resolução de problemas

Para obter informações sobre a resolução de problemas com o Cloud Trace, aceda à página de resolução de problemas.

Para depurar o exportador do Cloud Trace C++, consulte a secção Resolução de problemas da documentação de referência.

Recursos