Clientseitige Traces verwenden

Auf dieser Seite wird beschrieben, wie Sie clientseitige Traces mit OpenTelemetry aktivieren, wenn Sie die Cloud Storage-Clientbibliotheken für die Interaktion mit Cloud Storage verwenden. Sie können Tracedaten mit den folgenden unterstützten Cloud Storage-Clientbibliotheken erfassen und ansehen:

Übersicht

Wenn Sie Traces in den Cloud Storage-Clientbibliotheken aktivieren, können Sie die Leistung überwachen, Latenzprobleme identifizieren und Cloud Storage-Anfragen schnell debuggen. Mit Traces können Sie die Abfolge einer abgeschlossenen Anfrage sehen und erhalten so eine detaillierte Ansicht davon, wie die Anfrage von Cloud Storage empfangen, verarbeitet und beantwortet wurde. Ein einzelner Trace besteht aus mehreren Spans. Das sind detaillierte, mit Zeitstempeln versehene Aufzeichnungen jeder Funktion oder jedes Vorgangs, die Ihre Anwendung während der Cloud Storage-Anfrage ausgeführt hat.

Vorteile

Das Erfassen und Weitergeben von Trace-Daten bietet folgende Vorteile für Ihre Anwendung:

  • Bessere Leistungstransparenz: Da Tracedaten nahezu in Echtzeit generiert werden, wenn Cloud Storage jede Ihrer Anfragen bearbeitet, können Sie Leistungsprobleme schnell erkennen und Latenzprobleme ermitteln.

  • Fehlerbehandlung: Sie können genau feststellen, wo Probleme auftreten, und so die Ursachenanalyse beschleunigen und Ausfallzeiten reduzieren. Dazu nutzen Sie die Informationen zu jeder Cloud Storage-Anfrage, die in einem Trace enthalten sind.

Funktionsweise clientseitiger Traces

In den folgenden Abschnitten wird detailliert beschrieben, wie die Erfassung von Traces funktioniert.

So funktioniert die Erfassung von Traces mit OpenTelemetry

Die Cloud Storage-Clientbibliotheken unterstützen die Erfassung von Tracedaten mit dem OpenTelemetry SDK, um die folgenden Komponenten einzurichten, die zum Erfassen und Weitergeben von Tracedaten erforderlich sind:

  • Trace-Anbieter: Der Trace-Anbieter wird von den Cloud Storage-Clientbibliotheken verwendet und ist für die Erstellung und Verwaltung des Tracing-Systems verantwortlich, einschließlich der Generierung und Verwaltung von Traces und Spans in Ihrer Anwendung.

  • Trace-Exporter: Der Trace-Exporter wird vom OpenTelemetry SDK verwendet und ist dafür verantwortlich, Trace-Daten an eine Backend-Plattform für die Beobachtbarkeit wie Cloud Trace zu senden, wo Sie Trace-Daten analysieren und visualisieren können. Weitere Informationen zum Trace-Exporter finden Sie unter Funktionsweise von Trace-Exportern.

So funktionieren Trace-Exporte

Wenn Sie Traces mit dem OpenTelemetry SDK konfigurieren, müssen Sie ein Observability-Backend auswählen, in das Ihre Daten exportiert werden. Dort werden sie analysiert, gespeichert und visualisiert. Sie können Ihre Trace-Daten in ein beliebiges Observability-Backend Ihrer Wahl exportieren. Wir empfehlen jedoch die Verwendung von Cloud Trace, auf das über die Google Cloud Console zugegriffen werden kann und das in andere Google Cloud Dienste integriert ist.

Sobald der Trace-Provider und der Trace-Exporter konfiguriert und aktiviert sind, können Sie Trace-Daten nahezu in Echtzeit ansehen, da für jede Cloud Storage-Anfrage Traces und Spans generiert werden.

Mit dem Cloud Trace-Explorer in derGoogle Cloud -Konsole können Sie jeden Trace aufrufen, der Folgendes enthält:

  • Ein grober Überblick über eine Cloud Storage-Anfrage von Anfang bis Ende.

  • Mehrere Spannen, wobei jede Spanne einen einzelnen Vorgang mit Zeitstempel innerhalb der ausgeführten Cloud Storage-Anfrage erfasst.

Weitere Informationen zu Traces und Spans finden Sie in der OpenTelemetry-Dokumentation zu Traces und Spans.

Preise

Die Nutzung von Trace-Daten ist kostenpflichtig. Die Kosten basieren auf der Anzahl der Trace-Spans, die von Cloud Trace aufgenommen und gescannt werden. Weitere Informationen zu abrechenbaren Trace-Spans und Preisbeispielen finden Sie unter Cloud Trace-Kosten.

Hinweise

Bevor Sie Traces für Ihre Cloud Storage API-Nutzung erfassen können, müssen Sie die folgenden Schritte ausführen:

  1. Cloud Storage-Clientbibliothek installieren

  2. Richten Sie die Authentifizierung ein.

  3. Enable the Cloud Trace API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  4. Aktivieren Sie die Cloud Storage API.

    API aktivieren

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Trace Agent (roles/coudtrace.agent) für das vom Client verwendete Projekt zuzuweisen, um die Berechtigung zu erhalten, die Sie zum Schreiben von Traces in Cloud Trace benötigen.

Diese vordefinierte Rolle enthält die Berechtigung cloudtrace.traces.patch, die zum Schreiben von Traces in Cloud Trace erforderlich ist.

Sie können diese Berechtigungen auch mit vordefinierten Rollen erhalten oder benutzerdefinierte Rollen erstellen, um bestimmte Berechtigungen zu gewähren. Eine Anleitung zum Zuweisen von Rollen für Projekte finden Sie unter Rolle zuweisen oder widerrufen. Weitere Informationen zur Rolle des Cloud Trace-Agents finden Sie in der Dokumentation zur Identitäts- und Zugriffsverwaltung (IAM).

Tracing für Ihre Anwendung konfigurieren

Folgen Sie der Anleitung unten, um das Tracing zu konfigurieren und mit der Cloud Storage-Clientbibliothek Tracedaten zu erfassen:

C++

  1. Installieren Sie die folgenden Versionen:

    • C++-Clientbibliothek Version 2.16.0 oder höher

    • C++-Version 14 oder höher

  2. Wenn Sie die OpenTelemetry-Tracing-Instrumentierung in der C++-Clientbibliothek aktivieren möchten, aktualisieren Sie die Konfiguration Ihres Build-Systems für CMake oder Bazel.

  3. Erstellen Sie eine Instanz des Cloud Storage-Clients mit aktivierten OpenTelemetry-Traces. 

    #include "google/cloud/opentelemetry/configure_basic_tracing.h"
#include "google/cloud/storage/client.h"
#include "google/cloud/opentelemetry_options.h"
#include <iostream>

int main(int argc, char* argv[]) {
  if (argc != 3) {
    std::cerr << "Usage: " << argv[0] << " <bucket-name> <project-id>\n";
    return 1;
  }
  std::string const bucket_name = argv[1];
  std::string const project_id = argv[2];

  // Create aliases to make the code easier to read.
  namespace gc = ::google::cloud;
  namespace gcs = ::google::cloud::storage;

  // Instantiate a basic tracing configuration which exports traces to Cloud
  // Trace. By default, spans are sent in batches and always sampled.
  auto project = gc::Project(project_id);
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  // Create a client with OpenTelemetry tracing enabled.
  auto options = gc::Options{}.set<gc::OpenTelemetryTracingOption>(true);
  auto client = gcs::Client(options);

  auto writer = client.WriteObject(bucket_name, "quickstart.txt");
  writer << "Hello World!";
  writer.Close();
  if (!writer.metadata()) {
    std::cerr << "Error creating object: " << writer.metadata().status()
              << "\n";
    return 1;
  }
  std::cout << "Successfully created object: " << *writer.metadata() << "\n";

  auto reader = client.ReadObject(bucket_name, "quickstart.txt");
  if (!reader) {
    std::cerr << "Error reading object: " << reader.status() << "\n";
    return 1;
  }

  std::string contents{std::istreambuf_iterator<char>{reader}, {}};
  std::cout << contents << "\n";

  // The basic tracing configuration object goes out of scope. The collected
  // spans are flushed to Cloud Trace.

  return 0;
}

Java

  1. Installieren Sie die folgenden Versionen der Cloud Storage-Java-Clientbibliothek:

    • Ab com.google.cloud:google-cloud-storage:2.47.0

    • Ab com.google.cloud:libraries-bom:26.53.0

  2. Installieren Sie den Cloud Trace-Exporter für OpenTelemetry. Sie können auch einen beliebigen anderen Exporter verwenden.

  3. Installieren Sie den Cloud Trace-Propagator.

  4. Erstellen Sie eine Instanz des Cloud Storage-Clients mit aktivierten OpenTelemetry-Traces.

    public class QuickstartOpenTelemetrySample {
  public static void main(String... args) throws Exception {
    SpanExporter spanExporter = TraceExporter.createWithDefaultConfiguration();
    TextMapPropagator propagators =
        TextMapPropagator.composite(
            W3CTraceContextPropagator.getInstance(),
            new XCloudTraceContextPropagator(/* oneway= */ true));

    OpenTelemetrySdk openTelemetry =
        OpenTelemetrySdk.builder()
            .setPropagators(ContextPropagators.create(propagators))
            .setTracerProvider(
                SdkTracerProvider.builder()
                    // Sample Rate is set to alwaysOn
                    // It is recommended to sample based on a ratio for standard use ie.
                    // .setSampler(Sampler.traceIdRatioBased(0.2)) // sample only 20% of trace ids
                    .setSampler(Sampler.alwaysOn())
                    .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
                    .build())
            .build();
    StorageOptions options = StorageOptions.newBuilder().setOpenTelemetry(openTelemetry).build();
    Storage storage = options.getService();
    System.out.println("Created an instance of storage with OpenTelemetry configured");
  }
}

Python

  1. Installieren Sie die Cloud Storage-Clientbibliothek für Python:

    pip install google-cloud-storage[tracing]>=2.18.0

  2. Installieren Sie den Cloud Trace-Exporter und -Propagator. Sie können auch einen beliebigen anderen Exporter verwenden.

    pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp

  3. Installieren Sie die OpenTelemetry-Instrumentierung für Anfragen, um die zugrunde liegenden HTTP-Anfragen zu verfolgen.

    pip install opentelemetry-instrumentation-requests

  4. Legen Sie die Umgebungsvariable fest, um das Tracing für den Python-Speicherclient selektiv zu aktivieren:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Konfigurieren Sie den Trace-Exporter und den Trace-Anbieter. 

    
from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.resourcedetector.gcp_resource_detector import (
    GoogleCloudResourceDetector,
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.sampling import ALWAYS_ON
# Optional: Enable traces emitted from the requests HTTP library.
from opentelemetry.instrumentation.requests import RequestsInstrumentor

from google.cloud import storage

# The ID of your GCS bucket
# bucket_name = "your-bucket-name"
# The ID of your GCS object
# blob_name = "your-object-name"
# The contents to upload to the file
# data = "The quick brown fox jumps over the lazy dog."

# In this sample, we use Google Cloud Trace to export the OpenTelemetry
# traces: https://cloud.google.com/trace/docs/setup/python-ot
# Choose and configure the exporter for your environment.

tracer_provider = TracerProvider(
    # Sampling is set to ALWAYS_ON.
    # It is recommended to sample based on a ratio to control trace ingestion volume,
    # for instance, sampler=TraceIdRatioBased(0.2)
    sampler=ALWAYS_ON,
    resource=GoogleCloudResourceDetector().detect(),
)

# Export to Google Cloud Trace.
tracer_provider.add_span_processor(BatchSpanProcessor(CloudTraceSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# Optional: Enable traces emitted from the requests HTTP library.
RequestsInstrumentor().instrument(tracer_provider=tracer_provider)

# Get the tracer and create a new root span.
tracer = tracer_provider.get_tracer("My App")
with tracer.start_as_current_span("trace-quickstart"):
    # Instantiate a storage client and perform a write and read workload.
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)
    blob.upload_from_string(data)
    print(f"{blob_name} uploaded to {bucket_name}.")

    blob.download_as_bytes()
    print("Downloaded storage object {} from bucket {}.".format(blob_name, bucket_name))

Traces ansehen

So rufen Sie Ihre Trace-Daten im Google Cloud Explorer auf:

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

  2. Klicken Sie auf der Seite Trace-Explorer im Streudiagramm auf einen bestimmten Trace, um die Trace-Details aufzurufen.

    Im Bereich Trace-Details wird eine Tabelle mit Trace-Spans angezeigt.

  3. Optional: Klicken Sie auf eine Spannenzeile, um detaillierte Informationen zu einer bestimmten Spanne aufzurufen, z. B.:

    • Attribute: Schlüssel/Wert-Paare, die zusätzliche Informationen zum Bereich enthalten.

    • Logs und Ereignisse: Logeinträge, die mit dem Zeitraum verknüpft sind.

    • Stacktraces: Stacktraces, die mit dem Bereich verknüpft sind.

    • Metadaten und Links: Links zu anderen Google Cloud Diensten, die mit dem Zeitraum verknüpft sind.

Weitere Informationen zur Verwendung von Cloud Trace-Explorer finden Sie unter Traces suchen und untersuchen.

Nächste Schritte