C++ e OpenTelemetry

Questa pagina è rivolta agli sviluppatori di applicazioni che vogliono raccolta di dati di Cloud Trace per applicazioni C++ mediante OpenTelemetry. Il valore di OpenTelemetry è un framework di strumentazione indipendente dal fornitore che puoi usare per raccogliere e metriche. Per informazioni sulla strumentazione del codice, consulta Strumentazione e osservabilità.

Questa pagina ti guida nei seguenti passaggi:

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

Per informazioni sulla release, consulta quanto segue:

Per i contenuti di riferimento di OpenTelemetry, consulta quanto segue:

Per i dettagli più recenti su OpenTelemetry per C++, insieme a documentazione ed esempi aggiuntivi, vedi OpenTelemetry.

Prima di iniziare

Enable the Cloud Trace API.

Enable the API

Installare i pacchetti OpenTelemetry

Configura l'esportazione di intervalli in Cloud Trace

Per configurare l'esportazione dei dati di traccia, richiama il metodo Metodo google::cloud::otel::ConfigureBasicTracing(...) in 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 progetto Google Cloud in cui vuoi archiviare le tracce audio.

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

Configura la frequenza di campionamento

Le applicazioni potrebbero generare un grande volume di dati di traccia. Le seguenti L'esempio 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();
}

Esporta in Cloud Trace con un'entità TracerProvider personalizzata

I casi d'uso potrebbero richiedere un oggetto TracerProvider personalizzato. Ad esempio, se vuoi utilizzare più esportatori contemporaneamente, devi creare un oggetto TracerProvider personalizzato. In questi casi, puoi utilizzare Esportatore Cloud Trace direttamente:

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

Instrumenta la tua applicazione

Per informazioni su come configurare l'applicazione per acquisire gli span di traccia, consulta Monitoraggio delle tracce OpenTelemetry. In questa pagina viene descritto come effettuare tutte le seguenti operazioni:

  • Creare un intervallo
  • Crea intervalli nidificati
  • Imposta 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.

Configura la tua piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e su altre piattaforme.

In esecuzione su Google Cloud

Quando la tua applicazione è in esecuzione su Google Cloud, non è necessario fornire credenziali di autenticazione sotto forma di account di servizio alla libreria client. Tuttavia, devi assicurarti che la tua piattaforma Google Cloud ha Ambito di accesso all'API Cloud Trace in un bucket in cui è abilitato il controllo delle versioni.

Per un elenco degli ambienti Google Cloud supportati, consulta Assistenza per l'ambiente.

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

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

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

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

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

Esecuzione locale e altrove

Se la tua applicazione è in esecuzione al di fuori di Google Cloud, devi fornire le credenziali di autenticazione sotto forma di account di servizio alla libreria client. L'account di servizio deve contenere Ruolo di agente Cloud Trace. Per le istruzioni, vedi Creare un account di servizio.

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

Puoi fornire queste credenziali in tre modi:

  • Esegui gcloud auth application-default login

  • Posiziona l'account di servizio in un percorso predefinito per il sistema operativo. Di seguito sono elencati 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 su il percorso del tuo 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"

Visualizza tracce

Nella console Google Cloud, vai alla pagina Esplora tracce.

Vai a Trace Explorer

Puoi trovare questa pagina anche utilizzando la barra di ricerca.

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi relativi a Cloud Trace, vai alle Pagina Risoluzione dei problemi.

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

Risorse