C++ e OpenTelemetry

Esta página é destinada a desenvolvedores de aplicativos que querem coletar dados do Cloud Trace para aplicativos em C++ usando o OpenTelemetry. O OpenTelemetry é um framework de instrumentação independente de fornecedor que pode ser usado para coletar dados de trace e métricas. Para mais informações sobre como instrumentar seu código, consulte Instrumentação e observabilidade.

Esta página orienta você nas seguintes etapas:

  • Instale os pacotes do OpenTelemetry.
  • Configure seu aplicativo para exportar períodos para o Cloud Trace.
  • Configure sua plataforma.

Para ver informações sobre a versão, consulte:

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

Para conferir os detalhes mais recentes sobre o OpenTelemetry para C++, além de mais documentação e exemplos, consulte OpenTelemetry.

Antes de começar

Ative a API Cloud Trace, se ainda não tiver feito isso.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Instalar os pacotes do OpenTelemetry

Configurar a exportação de períodos para o Cloud Trace

Para configurar a exportação de dados de rastreamento, chame o método google::cloud::otel::ConfigureBasicTracing(...) no 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 projeto Google Cloud em que você quer armazenar os rastreamentos.

O método ConfigureBasicTracing(...) instancia um objeto TracerProvider que implementa um exportador do Cloud Trace. Se o objeto retornado pela chamada para ConfigureBasicTracing(...) sair do escopo, o objeto TracerProvider anterior será restabelecido, se existir.

Configurar taxa de amostragem

Os aplicativos podem gerar um grande volume de dados de rastreamento. O exemplo a seguir 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();
}

Exportar para o Cloud Trace com um TracerProvider personalizado

Talvez você tenha casos de uso que exijam um objeto TracerProvider personalizado. Por exemplo, se você quiser usar vários exportadores ao mesmo tempo, crie um objeto TracerProvider personalizado. Nesses casos, você 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>());
}

Instrumentar seu próprio aplicativo

Para ver informações sobre como configurar seu aplicativo para capturar períodos de rastreamento, consulte Rastreamento do OpenTelemetry. Esta página descreve como fazer o seguinte:

  • Criar um período
  • Criar períodos aninhados
  • Definir atributos de período
  • Criar períodos com eventos
  • Criar períodos 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();
}

Exemplo de aplicativo

Para um aplicativo de exemplo, consulte o guia de início rápido.

Configurar sua plataforma

É possível usar o Cloud Trace no Google Cloud e em outras plataformas.

Executando em Google Cloud

Quando o aplicativo está sendo executado em Google Cloud, não é necessário fornecer credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. No entanto, é necessário garantir que sua plataforma Google Cloud tenha o escopo de acesso da API Cloud Trace ativado.

Para uma lista de ambientes Google Cloud compatíveis, consulte Suporte a ambientes.

Para as seguintes configurações, as definições de escopo de acesso padrão ativam a API Cloud Trace:

Se você usa escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado:

  • Para informações sobre como configurar os escopos de acesso do seu ambiente usando o console do Google Cloud , consulte Configurar seu Google Cloud projeto.

  • Para usuários do gcloud, especifique os escopos de acesso usando a sinalização --scopes e inclua o escopo 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 em outro lugar

Se o aplicativo estiver sendo executado fora do Google Cloud, será necessário fornecer credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. A conta de serviço precisa ter o papel de agente do Cloud Trace. Para instruções, consulte Como criar uma conta de serviço.

As bibliotecas de cliente doGoogle Cloud usam Application Default Credentials (ADC) para encontrar as credenciais do aplicativo.

Você pode fornecer essas credenciais de três maneiras:

  • Executar gcloud auth application-default login

  • Coloque a conta de serviço em um caminho padrão para seu sistema operacional. Confira abaixo os caminhos padrão para Windows e 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 traces

No console Google Cloud , acesse a página Explorador de traces:

Acessar o Explorador de traces

Também é possível encontrar essa página usando a barra de pesquisa.

Solução de problemas

Para informações sobre como solucionar problemas com o Cloud Trace, acesse a página de solução de problemas.

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

Recursos