C++ und OpenTelemetry

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

Auf dieser Seite werden Sie durch die folgenden Schritte geführt:

  • 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 unter:

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

Hinweis

Aktivieren Sie die Cloud Trace API, falls sie noch nicht aktiviert ist.

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

API aktivieren

OpenTelemetry-Pakete installieren

Export von Spans nach Cloud Trace konfigurieren

Rufen Sie die Methode google::cloud::otel::ConfigureBasicTracing(...) in Ihrer Methode main() auf, um den Export von Tracedaten zu konfigurieren:

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 nicht mehr im Gültigkeitsbereich ist, wird das vorherige TracerProvider-Objekt wiederhergestellt, sofern es vorhanden ist.

Stichprobenrate konfigurieren

Anwendungen können große Mengen an Tracedaten generieren. Das folgende Beispiel zeigt, wie die Samplingrate 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 einem benutzerdefinierten TracerProvider nach Cloud Trace exportieren

Möglicherweise haben Sie Anwendungsfälle, für die ein benutzerdefiniertes TracerProvider-Objekt erforderlich ist. 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 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);

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

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 Kurzanleitung.

Plattform konfigurieren

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

Wird ausgeführt auf Google Cloud

Wenn Ihre Anwendung auf Google Cloudausgeführt wird, müssen Sie der Clientbibliothek keine Authentifizierungsanmeldedaten in Form eines Dienstkontos bereitstellen. Sie müssen jedoch dafür sorgen, dass für Ihre Google Cloud Plattform der Cloud Trace API-Zugriffsbereich aktiviert ist.

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, müssen Sie dafür sorgen, dass der Cloud Trace API-Zugriffsbereich aktiviert ist:

  • 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 Cloudausgeführt wird, müssen Sie der Clientbibliothek Authentifizierungsanmeldedaten in Form eines Dienstkontos bereitstellen. Das Dienstkonto muss die Cloud Trace-Agent-Rolle enthalten. Eine Anleitung dazu finden Sie unter Dienstkonto erstellen.

Google Cloud Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), um die Anmeldedaten Ihrer Anwendung zu finden.

Sie können diese Anmeldedaten auf drei Arten angeben:

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

  • Speichern 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

Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

Zum Trace Explorer

Sie können diese Seite auch über die Suchleiste finden.

Fehlerbehebung

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

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

Ressourcen