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 zum Instrumentieren Ihres Codes finden Sie unter Instrumentierung und Beobachtbarkeit.

Auf dieser Seite werden die folgenden Schritte beschrieben:

  • 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 zusätzliche Dokumentation und Beispiele finden Sie unter OpenTelemetry.

Hinweis

Aktivieren Sie die Cloud Trace API.

Erforderliche Rollen zum Aktivieren von APIs

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 zum Konfigurieren des Exports von Tracedaten die Methode google::cloud::otel::ConfigureBasicTracing(...) in Ihrer main()-Methode 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 von dem Aufruf von ConfigureBasicTracing(...) zurückgegebene Objekt außerhalb des Gültigkeitsbereichs liegt, wird das vorherige TracerProvider-Objekt wiederhergestellt, sofern vorhanden.

Stichprobenrate konfigurieren

Anwendungen können eine große Menge an Tracedaten generieren. Das folgende Beispiel zeigt, wie Sie die Stichprobenrate konfigurieren:

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

Es gibt möglicherweise 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 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 unter dem Schnellstart.

Konfigurieren Sie Ihre Plattform.

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 für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in Form eines Dienstkontos angeben. Für Ihre Plattform muss jedoch der Zugriffsbereich der Cloud Trace API aktiviert sein. Google Cloud

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 mithilfe der Google Cloud Console finden Sie unter Projekt konfigurieren. Google Cloud

  • 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 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 (ADC) bei der Suche nach den Anmeldedaten Ihrer Anwendung.

Sie können diese Anmeldedaten auf drei Arten angeben:

  • 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

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

Trace Explorer aufrufen

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 im Abschnitt zur Fehlerbehebung in der Referenz dokumentation.

Ressourcen