Clientseitige Traces verwenden

Auf dieser Seite wird beschrieben, wie Sie clientseitige Protokolle mit OpenTelemetry aktivieren, wenn Sie die Cloud Storage-Clientbibliotheken verwenden, um mit Cloud Storage zu interagieren. Sie können mit den folgenden unterstützten Cloud Storage-Clientbibliotheken Trace-Daten erfassen und ansehen:

Übersicht

Wenn Sie Protokolle in den Cloud Storage-Clientbibliotheken aktivieren, können Sie die Leistung überwachen, Latenzprobleme ermitteln und Cloud Storage-Anfragen schnell debuggen. Anhand von Protokollen können Sie die Abfolge einer abgeschlossenen Anfrage sehen und erhalten eine detaillierte Übersicht darüber, wie die Anfrage von Cloud Storage empfangen, verwaltet und beantwortet wurde. Ein einzelner Trace besteht aus mehreren Spans, also detaillierten, getaggten Einträgen zu jeder Funktion oder jedem Vorgang, den Ihre Anwendung während der Cloud Storage-Anfrage ausgeführt hat.

Vorteile

Das Erfassen und Weitergeben von Trace-Daten bietet Ihrer Anwendung folgende Vorteile:

  • Verbesserte Leistungstransparenz: Da Ablaufdaten in nahezu Echtzeit generiert werden, wenn Cloud Storage jede von Ihnen gestellte Anfrage abschließt, können Sie Leistungsengpässe und Latenzprobleme schnell erkennen.

  • Fehlerbehandlung: Anhand der Informationen zu jeder Cloud Storage-Anfrage, die in einem Trace enthalten sind, können Sie ermitteln, wo Probleme auftreten. So lässt sich die Analyse der Ursache beschleunigen und die Ausfallzeit reduzieren.

Funktionsweise von clientseitigen Traces

In den folgenden Abschnitten wird die Funktionsweise der Trace-Erfassung ausführlich erläutert.

So funktioniert die Trace-Erfassung mit OpenTelemetry

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

  • Trace-Anbieter: Der Trace-Anbieter wird von den Cloud Storage-Clientbibliotheken verwendet und ist für das Erstellen und Verwalten 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 für das Senden von Trace-Daten an eine Backend-Plattform für die Beobachtbarkeit wie Cloud Trace verantwortlich, in der Sie Trace-Daten analysieren und visualisieren können. Weitere Informationen zum Trace-Exporter finden Sie unter Funktionsweise von Trace-Exportern.

Funktionsweise von Trace-Exporten

Wenn Sie Traces mit dem OpenTelemetry SDK konfigurieren, müssen Sie ein Observability-Backend auswählen, in das Ihre Daten exportiert werden, um dort analysiert, gespeichert und visualisiert zu werden. Sie können Ihre Trace-Daten in ein beliebiges Observability-Backend Ihrer Wahl exportieren. Wir empfehlen jedoch Cloud Trace, auf das über die Google Cloud Console zugegriffen werden kann und das eine Integration mit anderen Google Cloud Diensten bietet.

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

Mit dem Cloud Trace-Explorer in der Google Cloud Console können Sie sich jeden Trace ansehen, der Folgendes enthält:

  • Ein grober Überblick über eine Cloud Storage-Anfrage

  • Mehrere Zeitspannen, von denen jede einen einzelnen Vorgang mit Zeitstempel innerhalb der durchgeführten Cloud Storage-Anfrage erfasst.

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

Preise

Für die Analyse von Trace-Daten fallen Gebühren an. Die Kosten richten sich nach der Anzahl der von Cloud Trace aufgenommenen und gescannten Trace-Spans. Weitere Informationen zu abrechenbaren Trace-Bereichen und Preisbeispielen finden Sie unter Cloud Trace-Kosten.

Hinweis

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

  1. Installieren Sie die Cloud Storage-Clientbibliothek.

  2. Richten Sie die Authentifizierung ein.

  3. Enable the Cloud Trace API.

    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 Kunden verwendete Projekt zu gewähren, 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 Protokollen 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 „Cloud Trace-Agent“ finden Sie in der Dokumentation zur Identitäts- und Zugriffsverwaltung (IAM).

Tracing für Ihre Anwendung konfigurieren

Führen Sie die folgenden Schritte aus, um die Tracing-Funktion zu konfigurieren und mit der Cloud Storage-Clientbibliothek Tracing-Daten zu erfassen:

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 Exporteur 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-Python-Clientbibliothek:

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

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

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

  3. Installieren Sie die OpenTelemetry-Anfrage-Instrumentierung, um die zugrunde liegenden HTTP-Anfragen zu erfassen.

    pip install opentelemetry-instrumentation-requests

  4. Legen Sie die Umgebungsvariable so fest, dass die Ablaufverfolgung für den Python-Speicherclient selektiv aktiviert wird:

    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

Mit dem Cloud Trace Explorer können Sie Ihre Trace-Daten in der Google Cloud Console aufrufen:

  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 Zeile mit einer Spanne, um Details zu einer bestimmten Spanne aufzurufen, z. B. die folgenden Informationen:

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

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

    • Stack-Traces: Stack-Traces, die mit der Spanne verknüpft sind.

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

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

Nächste Schritte