C++ und OpenTelemetry

Diese Seite richtet sich an Anwendungsentwickler, die Cloud Trace-Daten für C++-Anwendungen mithilfe von OpenTelemetry erfassen möchten. OpenTelemetry ist ein anbieterneutrales Instrumentierungs-Framework, mit dem Sie Trace- und Messwertdaten erfassen können. Informationen zum Instrumentieren des Codes finden Sie unter Instrumentierung und Beobachtbarkeit.

  • Installieren Sie die OpenTelemetry-Pakete.
  • Anwendung für den Export von Spans nach Cloud Trace konfigurieren
  • Konfigurieren Sie Ihre Plattform.

Releaseinformationen finden Sie hier:

Referenzinhalte zu OpenTelemetry finden Sie hier:

Aktuelle Informationen zu OpenTelemetry für C++ sowie weitere Dokumentation und Beispiele finden Sie unter OpenTelemetry.

Hinweise

  1. Wählen Sie im Navigationsbereich der Google Cloud Console APIs und Dienste aus, klicken Sie auf APIs und Dienste aktivieren und aktivieren Sie dann die Cloud Trace API:

    Zu den Einstellungen für die Cloud Trace API

  2. Wenn API aktiviert angezeigt wird, ist die API bereits aktiviert. Falls nicht, klicken Sie auf die Schaltfläche Aktivieren.

OpenTelemetry-Pakete installieren

Export von Spans nach Cloud Trace konfigurieren

Rufen Sie zum Konfigurieren des Exports von Trace-Daten die Methode google::cloud::otel::ConfigureBasicTracing(...) in der Methode main() auf:

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

  MyApplicationCode();
}

Das Feld project_id ist das Google Cloud-Projekt, in dem Sie die Traces speichern möchten.

Die Methode ConfigureBasicTracing(...) instanziiert ein TracerProvider-Objekt, das einen Cloud Trace-Exporter implementiert. Wenn das vom Aufruf von ConfigureBasicTracing(...) zurückgegebene Objekt außerhalb des Bereichs liegt, wird das vorherige TracerProvider-Objekt wiederhergestellt, sofern vorhanden.

Abtastrate konfigurieren

Anwendungen können große Mengen an Trace-Daten generieren. Das folgende Beispiel zeigt, wie die Abtastrate konfiguriert wird:

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

Mit einer benutzerdefinierten TracerProvider in Cloud Trace exportieren

Möglicherweise gibt es Anwendungsfälle, die ein benutzerdefiniertes TracerProvider-Objekt erfordern. Wenn Sie beispielsweise mehrere Exporter gleichzeitig verwenden möchten, müssen Sie ein benutzerdefiniertes TracerProvider-Objekt erstellen. In diesen Fällen können Sie den Cloud Trace-Exporter wie unten gezeigt direkt verwenden:

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);
  auto provider = opentelemetry::sdk::trace::TracerProviderFactory::Create(
      std::move(processor));

  // Set the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(std::move(provider));

  MyApplicationCode();

  // Clear the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      opentelemetry::nostd::shared_ptr<
          opentelemetry::trace::TracerProvider>());
}

Eigene Anwendung instrumentieren

Wie Sie Ihre Anwendung für die Erfassung von Trace-Spans konfigurieren, erfahren Sie unter OpenTelemetry-Tracing. Auf dieser Seite wird beschrieben, wie Sie die folgenden Schritte ausführen:

  • Span erstellen
  • Verschachtelte Spans erstellen
  • Span-Attribute festlegen
  • Spans mit Ereignissen erstellen
  • Spans mit Links erstellen
// 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();
}

Beispielanwendung

Eine Beispielanwendung finden Sie in der quickstart.

Plattform konfigurieren

Sie können Cloud Trace in Google Cloud und auf anderen Plattformen verwenden.

In Google Cloud ausführen

Wenn Ihre Anwendung in Google Cloud ausgeführt wird, müssen Sie für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in der Clientbibliothek angeben. Für die Google Cloud Platform muss jedoch der Zugriffsbereich der Cloud Trace API aktiviert sein.

Eine Liste der unterstützten Google Cloud-Umgebungen finden Sie unter Umgebungsunterstützung.

Für die folgenden Konfigurationen wird die Cloud Trace API über die Standardeinstellungen für den Zugriffsbereich aktiviert:

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein:

  • Informationen zum Konfigurieren der Zugriffsbereiche für Ihre Umgebung mit der Google Cloud Console finden Sie unter Google Cloud-Projekt konfigurieren.

  • Geben Sie für gcloud-Nutzer mithilfe des Flags --scopes Zugriffsbereiche an und beziehen Sie den Zugriffsbereich der Cloud Trace API trace.append ein. So erstellen Sie beispielsweise einen GKE-Cluster, für den nur die Cloud Trace API aktiviert ist:

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

Lokal und extern ausführen

Wenn Ihre Anwendung außerhalb von Google Cloud ausgeführt wird, müssen Sie Anmeldedaten zur Authentifizierung in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Rolle "Cloud Trace-Agent" enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Google Cloud-Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen für die Suche nach den Anmeldedaten Ihrer Anwendung.

Sie haben drei Möglichkeiten, diese Anmeldedaten anzugeben:

  • Führen Sie gcloud auth application-default login aus

  • Platzieren Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem. Im Folgenden sind die Standardpfade für Windows und Linux aufgeführt:

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

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

  • Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad zu Ihrem Dienstkonto fest:

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"

Traces ansehen

Wählen Sie im Navigationsbereich der Google Cloud Console Trace und dann Trace Explorer aus:

Zum Trace Explorer

Fehlerbehebung

Informationen zur Fehlerbehebung bei Cloud Trace finden Sie auf der Seite Fehlerbehebung.

Informationen zum Debuggen des C++ Cloud Trace-Exporters finden Sie im Abschnitt Fehlerbehebung der Referenzdokumentation.

Ressourcen