Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

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 Trace-Daten 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 lokalisieren und schnell Fehlerbehebungen für Cloud Storage-Anfragen durchführen. Mit Traces können Sie die Abfolge einer abgeschlossenen Anfrage sehen und erhalten eine detaillierte Ansicht, wie die Anfrage von Cloud Storage empfangen, verwaltet und beantwortet wurde. Ein einzelner Trace besteht aus mehreren Spans. Dies sind detaillierte, mit Zeitstempeln versehene Datensätze 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:

Verbesserte Leistungstransparenz: Da Trace-Daten nahezu in Echtzeit generiert werden, während Cloud Storage jede Ihrer Anfragen abschließt, können Sie Leistungsengpässe und Latenzprobleme schnell erkennen.
Fehlerbehandlung: Sie können genau feststellen, wo Probleme auftreten, die Ursachenanalyse beschleunigen und Ausfallzeiten reduzieren. Dazu verwenden Sie die Informationen zu jeder Cloud Storage-Anfrage, die in einem Trace bereitgestellt werden.

Funktionsweise von clientseitigen Traces

In den folgenden Abschnitten wird die Trace-Erfassung im Detail beschrieben.

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: Wird von den Cloud Storage-Clientbibliotheken verwendet. Der Trace-Anbieter ist für das Erstellen und Verwalten des Tracing-Systems verantwortlich, einschließlich des Generierens und Verwaltens 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-Beobachtbarkeitsplattform wie Cloud Trace verantwortlich, auf der Sie Trace-Daten analysieren und visualisieren können. Weitere Informationen zum Trace-Exporter finden Sie unter Funktionsweise von Trace-Exportern.

Funktionsweise von Trace-Exportern

Beim Konfigurieren von Traces mit dem OpenTelemetry SDK müssen Sie ein Beobachtbarkeits-Backend auswählen, in das Ihre Daten exportiert werden, um sie dort zu analysieren, zu speichern und zu visualisieren. Sie können Ihre Trace-Daten in ein beliebiges Beobachtbarkeits-Backend Ihrer Wahl exportieren. Wir empfehlen jedoch die Verwendung von Cloud Trace, auf das Sie über die Google Cloud Console zugreifen können und das eine Einbindung in andere Google Cloud -Dienste bietet.

Sobald der Trace-Anbieter 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 Console können Sie sich jeden Trace ansehen, der Folgendes enthält:

Eine allgemeine Übersicht über eine Cloud Storage-Anfrage von Anfang bis Ende.
Mehrere Spans, wobei jeder Span 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

Trace-Daten sind kostenpflichtig. Die Gebühren richten sich nach der Anzahl der Trace-Spans, die von Cloud Trace aufgenommen und gescannt werden. Weitere Informationen zu kostenpflichtigen Trace-Spans und Preisbeispielen finden Sie unter Cloud Trace-Kosten.

Hinweis

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

Installieren Sie die Cloud Storage-Clientbibliothek.
Richten Sie die Authentifizierung ein.
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 Inhaberrolle (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
Aktivieren Sie die Cloud Storage API.

API aktivieren

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud Trace-Agent (roles/cloudtrace.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 „Cloud Trace-Agent“ finden Sie in der Dokumentation zu Identity and Access Management (IAM).

Tracing für Ihre Anwendung konfigurieren

Gehen Sie so vor, um das Tracing zu konfigurieren und mit der Cloud Storage-Clientbibliothek Trace-Daten zu erfassen:

C++

Installieren Sie die folgenden Versionen:
- C++-Clientbibliothek Version 2.16.0 oder höher
- C++-Version 14 oder höher
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.

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

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
Installieren Sie den Cloud Trace-Exporter für OpenTelemetry. Sie können auch einen beliebigen anderen Exporter verwenden.
Installieren Sie den Cloud Trace-Propagator.

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

Installieren Sie die Cloud Storage-Python-Clientbibliothek:
```
pip install google-cloud-storage[tracing]>=2.18.0
```
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
```
Installieren Sie die OpenTelemetry-Anfrageinstrumentierung, um die zugrunde liegenden HTTP-Anfragen zu verfolgen.
```
pip install opentelemetry-instrumentation-requests
```
Legen Sie die Umgebungsvariable fest, um das Tracing für den Python-Speicherclient selektiv zu aktivieren:
```
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
```

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))

Rust

Fügen Sie die Cloud Storage Rust-Clientbibliothek sowie die Crates tracing und OpenTelemetry zur Manifestdatei Cargo.toml hinzu:

cargo add google-cloud-storage opentelemetry opentelemetry_sdk opentelemetry-otlp tracing tracing-opentelemetry tracing-subscriber

Konfigurieren Sie eine OpenTelemetry-SdkTracerProvider-Struktur mit einem OTLP-Exporter (z. B. zum Senden von Spans an einen OpenTelemetry Collector oder die Telemetry API), registrieren Sie einen tracing-Abonnenten und erstellen Sie einen Storage-Client mit aktivierter .with_tracing()-Methode:

use google_cloud_storage::client::Storage;
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt;

pub async fn sample(bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "enable-otel-tracing.txt";

    // Create an OTLP exporter to send spans to an OpenTelemetry Collector
    // running on localhost (the default).
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .build();
    let tracer = provider.tracer("storage-quickstart");

    // Create a tracing layer and register the subscriber for the current scope.
    // In an application's `main`, use `tracing::subscriber::set_global_default` instead.
    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);
    let subscriber = Registry::default().with(telemetry);
    let _guard = tracing::subscriber::set_default(subscriber);

    // Build a Storage client with client-side tracing enabled.
    let client = Storage::builder().with_tracing().build().await?;

    let object = client
        .write_object(
            format!("projects/_/buckets/{bucket_id}"),
            NAME,
            "Hello, world!",
        )
        .set_if_generation_match(0)
        .send_unbuffered()
        .await?;
    println!("Uploaded object {} to bucket {bucket_id}.", object.name);

    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket_id}"), NAME)
        .send()
        .await?;
    let mut contents = Vec::new();
    while let Some(chunk) = reader.next().await.transpose()? {
        contents.extend_from_slice(&chunk);
    }
    println!(
        "Downloaded {} bytes from object {NAME} in bucket {bucket_id}.",
        contents.len()
    );

    Ok(())
}

Traces ansehen

Verwenden Sie den Cloud Trace-Explorer, um Ihre Trace-Daten in der Google Cloud Console aufzurufen:

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.
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.
Optional: Klicken Sie auf eine Span-Zeile, um detaillierte Informationen zu einem bestimmten Span aufzurufen, z. B.:
- Attribute: Schlüssel/Wert-Paare, die zusätzliche Informationen zum Span enthalten.
- Logs und Ereignisse: Logeinträge, die mit dem Span verknüpft sind.
- Stacktraces: Stacktraces, die mit dem Span verknüpft sind.
- Metadaten und Links: Links zu anderen Google Cloud -Diensten, die mit dem Span verknüpft sind.

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