C++ e OpenTelemetry

Questa pagina è destinata agli sviluppatori di applicazioni che vogliono raccogliere dati di Cloud Trace per le applicazioni C++ utilizzando OpenTelemetry. OpenTelemetry è un framework di strumentazione indipendente dal fornitore che puoi utilizzare per raccogliere dati di traccia e metriche. Per informazioni sulla strumentazione del codice, consulta Strumentazione e osservabilità.

Questa pagina ti guida attraverso i seguenti passaggi:

  • Installa i pacchetti OpenTelemetry.
  • Configura l'applicazione per esportare gli intervalli in Cloud Trace.
  • Configura la piattaforma.

Per informazioni sulla release, consulta le seguenti risorse:

Per i contenuti di riferimento di OpenTelemetry, consulta le seguenti risorse:

Per gli ultimi dettagli su OpenTelemetry per C++, nonché per ulteriore documentazione ed esempi, consulta OpenTelemetry.

Prima di iniziare

Abilita l'Cloud Trace API.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Installare i pacchetti OpenTelemetry

Configurare l'esportazione degli intervalli in Cloud Trace

Per configurare l'esportazione dei dati di traccia, chiama il metodo google::cloud::otel::ConfigureBasicTracing(...) nel metodo main():

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

  MyApplicationCode();
}

Il campo project_id è il Google Cloud progetto in cui vuoi archiviare le tracce.

Il metodo ConfigureBasicTracing(...) crea un'istanza di un oggetto TracerProvider che implementa un esportatore Cloud Trace. Se l'oggetto restituito dalla chiamata a ConfigureBasicTracing(...) esce dall'ambito, viene ripristinato l'oggetto TracerProvider precedente, se esistente.

Configurare la frequenza di campionamento

Le applicazioni potrebbero generare un volume elevato di dati di traccia. L'esempio seguente illustra come configurare la frequenza di campionamento:

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

Esportare in Cloud Trace con un TracerProvider personalizzato

Potresti avere casi d'uso che richiedono un oggetto TracerProvider personalizzato. Ad esempio, se vuoi utilizzare più esportatori contemporaneamente, devi creare un oggetto TracerProvider personalizzato. In questi casi, puoi utilizzare direttamente l'esportatore Cloud Trace:

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

Strumentare la propria applicazione

Per informazioni su come configurare l'applicazione per acquisire gli intervalli di traccia, consulta Tracciamento OpenTelemetry. Questa pagina descrive come eseguire tutte le seguenti operazioni:

  • Creare un intervallo
  • Creare intervalli nidificati
  • Impostare gli attributi dell'intervallo
  • Creare intervalli con eventi
  • Creare intervalli con link
// 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();
}

Applicazione di esempio

Per un'applicazione di esempio, consulta la guida rapida.

Configurare la piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

Esecuzione su Google Cloud

Quando l'applicazione è in esecuzione su Google Cloud, non devi fornire le credenziali di autenticazione alla libreria client sotto forma di account di servizio. Tuttavia, devi assicurarti che la tua Google Cloud piattaforma abbia l' ambito di accesso all'API Cloud Trace abilitato.

Per un elenco degli ambienti supportati Google Cloud , consulta Supporto dell'ambiente.

Per le seguenti configurazioni, le impostazioni predefinite dell'ambito di accesso abilitano l'Cloud Trace API:

Se utilizzi ambiti di accesso personalizzati, devi assicurarti che l'ambito di accesso all'API Cloud Trace sia abilitato:

  • Per informazioni su come configurare gli ambiti di accesso per il tuo ambiente utilizzando la Google Cloud console, consulta Configurare il Google Cloud progetto.

  • Per gli utenti di gcloud, specifica gli ambiti di accesso utilizzando il flag --scopes e includi l'ambito di accesso all'Cloud Trace API trace.append. Ad esempio, per creare un cluster GKE con la sola Cloud Trace API abilitata, procedi nel seguente modo:

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

Esecuzione in locale e altrove

Se l'applicazione è in esecuzione al di fuori di Google Cloud, devi fornire le credenziali di autenticazione alla libreria client sotto forma di account di servizio. Il account di servizio deve contenere il ruolo Agente Cloud Trace. Per le istruzioni, consulta Creare un account di servizio.

Google Cloud Le librerie client utilizzano Credenziali predefinite dell'applicazione (ADC) per trovare le credenziali dell'applicazione.

Puoi fornire queste credenziali in tre modi:

  • Esegui gcloud auth application-default login

  • Inserisci il account di servizio in un percorso predefinito per il tuo sistema operativo. Di seguito sono riportati i percorsi predefiniti per Windows e Linux:

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

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

  • Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del account di servizio:

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"

Visualizzare tracce

Nella Google Cloud console, vai alla Esplora tracce pagina:

Vai a Esplora tracce

Puoi trovare questa pagina anche utilizzando la barra di ricerca.

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi relativi a Cloud Trace, vai alla pagina Risoluzione dei problemi.

Per eseguire il debug dell'esportatore Cloud Trace C++, consulta la sezione Risoluzione dei problemi della documentazione di riferimento.

Risorse