C++ et OpenTelemetry

Cette page est destinée aux développeurs d'applications qui souhaitent collecter des données Cloud Trace pour les applications C++ à l'aide d'OpenTelemetry. OpenTelemetry est un framework d'instrumentation neutre vis-à-vis des fournisseurs que vous pouvez utiliser pour collecter des données de trace et de métrique. Pour en savoir plus sur l'instrumentation de votre code, consultez la section Instrumentation et observabilité.

Cette page vous guide tout au long des étapes suivantes :

  • Installez les packages OpenTelementry.
  • Configurez votre application pour exporter les délais vers Cloud Trace.
  • Configurez votre plate-forme.

Pour en savoir plus sur les versions, consultez les articles suivants :

Pour obtenir du contenu de référence sur OpenTelemetry, consultez les éléments suivants :

Pour obtenir les dernières informations sur OpenTelemetry pour C++, ainsi que de la documentation supplémentaire et des exemples, consultez la section OpenTelemetry.

Avant de commencer

Activez l'API Cloud Trace.

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

Activer l'API

Installer les packages OpenTelementry

Configurer l'exportation des délais vers Cloud Trace

Pour configurer l'exportation des données de trace, appelez la méthode google::cloud::otel::ConfigureBasicTracing(...) dans votre méthode main() :

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

  MyApplicationCode();
}

Le champ project_id correspond au Google Cloud projet dans lequel vous souhaitez stocker les traces.

La méthode ConfigureBasicTracing(...) instancie un TracerProvider objet qui implémente un exportateur Cloud Trace. Si l'objet renvoyé par l'appel à ConfigureBasicTracing(...) n'est plus dans le champ d'application, l'objet TracerProvider précédent est rétabli, s'il existe.

Configurer le taux d'échantillonnage

Les applications peuvent générer un volume important de données de trace. L'exemple suivant illustre comment configurer le taux d'échantillonnage :

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

Exporter vers Cloud Trace avec un TracerProvider personnalisé

Vous pouvez avoir des cas d'utilisation qui nécessitent un objet TracerProvider personnalisé. Par exemple, si vous souhaitez utiliser plusieurs exportateurs en même temps, vous devez créer un objet TracerProvider personnalisé. Dans ce cas, vous pouvez utiliser directement l'exportateur 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>());
}

Instrumenter votre propre application

Pour en savoir plus sur la configuration de votre application pour capturer des délais de trace, consultez la page Traçage OpenTelemetry. Cette page explique comment effectuer les opérations suivantes :

  • Créer un délai
  • Créer des délais imbriqués
  • Définir des attributs de délai
  • Créer des délais avec des événements
  • Créer des délais avec des liens
// 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();
}

Exemple d'application

Pour obtenir un exemple d'application, consultez le guide de démarrage rapide.

Configurer votre plate-forme

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.

Exécution sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Cependant, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre Google Cloud plate-forme.

Pour obtenir la liste desenvironnements compatibles, consultez la page Environnements compatibles. Google Cloud

Pour les configurations suivantes, les paramètres de niveau d'accès par défaut activent l'API Cloud Trace :

Si vous utilisez des niveaux d'accès personnalisés, assurez-vous que le niveau d'accès de l'API Cloud Trace est activé :

  • Pour en savoir plus sur la configuration des niveaux d'accès pour votre environnement à l'aide de la Google Cloud console, consultez la section Configurer votre Google Cloud projet.

  • Pour les utilisateurs gcloud, spécifiez les niveaux d'accès à l'aide de l'indicateur --scopes et incluez le niveau d'accès à l'API Cloud Trace trace.append. Par exemple, pour créer un cluster GKE avec uniquement l'API Cloud Trace activée, procédez comme suit :

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

Exécuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir les identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit contenir le rôle d'agent Cloud Trace. Pour savoir comment faire, consultez la page Créer un compte de service.

Les bibliothèques clientes utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application.Google Cloud

Vous pouvez fournir ces identifiants de trois manières :

  • Exécutez gcloud auth application-default login.

  • Placez le compte de service dans un chemin d'accès par défaut pour votre système d'exploitation. Vous trouverez ci-dessous la liste des chemins d'accès par défaut pour Windows et Linux :

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

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

  • Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès à votre compte de service :

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"

Afficher les traces

Dans la Google Cloud console, accédez à la Explorateur Trace page :

Accéder à Explorateur Trace

Vous pouvez également accéder à cette page à l'aide de la barre de recherche.

Dépannage

Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.

Pour déboguer l'exportateur Cloud Trace C++, consultez la section Dépannage de la documentation de référence.

Ressources