Menggunakan rekaman aktivitas sisi klien

Halaman ini menjelaskan cara mengaktifkan rekaman aktivitas sisi klien dengan OpenTelemetry saat Anda menggunakan library klien Cloud Storage untuk berinteraksi dengan Cloud Storage. Anda dapat mengumpulkan dan melihat data rekaman aktivitas menggunakan library klien Cloud Storage yang didukung berikut:

Ringkasan

Dengan mengaktifkan rekaman aktivitas di library klien Cloud Storage, Anda dapat memantau performa, menemukan masalah latensi, dan melakukan proses debug dengan cepat untuk permintaan Cloud Storage. Rekaman aktivitas memungkinkan Anda melihat urutan permintaan yang telah selesai, sehingga memberikan tampilan mendetail tentang cara Cloud Storage menerima, mengelola, dan merespons permintaan. Satu rekaman aktivitas terdiri dari beberapa span, yang merupakan catatan mendetail dengan stempel waktu dari setiap fungsi atau operasi yang dilakukan aplikasi Anda selama permintaan Cloud Storage.

Manfaat

Mengumpulkan dan menyebarkan data rekaman aktivitas memberikan manfaat berikut untuk aplikasi Anda:

  • Visibilitas performa yang ditingkatkan: karena data rekaman aktivitas dibuat secara hampir real-time saat Cloud Storage menyelesaikan setiap permintaan yang Anda buat, Anda dapat dengan cepat mengidentifikasi bottleneck dalam performa dan mendeteksi masalah latensi.

  • Penanganan error: Anda dapat menemukan tempat masalah muncul, mempercepat analisis akar masalah dan mengurangi waktu non-aktif menggunakan informasi tentang setiap permintaan Cloud Storage yang disediakan dalam rekaman aktivitas.

Cara kerja rekaman aktivitas sisi klien

Bagian berikut memberikan tampilan mendetail tentang cara kerja pengumpulan rekaman aktivitas.

Cara kerja pengumpulan rekaman aktivitas dengan OpenTelemetry

Library klien Cloud Storage mendukung pengumpulan data rekaman aktivitas menggunakan OpenTelemetry SDK untuk menyiapkan komponen berikut yang diperlukan untuk mengumpulkan dan menyebarkan data rekaman aktivitas:

  • Penyedia rekaman aktivitas: digunakan oleh library klien Cloud Storage, penyedia rekaman aktivitas bertanggung jawab untuk membuat dan mengelola sistem pelacakan, termasuk membuat dan mengelola rekaman aktivitas dan span di aplikasi Anda.

  • Pengekspor rekaman aktivitas: digunakan oleh OpenTelemetry SDK, pengekspor rekaman aktivitas bertanggung jawab untuk mengirim data rekaman aktivitas ke platform observabilitas backend seperti Cloud Trace, tempat Anda dapat menganalisis dan memvisualisasikan data rekaman aktivitas. Untuk mempelajari pengekspor rekaman aktivitas lebih lanjut, lihat Cara kerja pengekspor rekaman aktivitas.

Cara kerja pengekspor rekaman aktivitas

Mengonfigurasi rekaman aktivitas menggunakan OpenTelemetry SDK mencakup pemilihan backend observabilitas untuk mengekspor data Anda ke tempat data tersebut dianalisis, disimpan, dan divisualisasikan. Meskipun Anda dapat mengekspor data rekaman aktivitas ke backend observabilitas pilihan Anda, sebaiknya gunakan Cloud Trace, yang dapat diakses menggunakan konsol dan menyediakan integrasi dengan layanan lainnya. Google Cloud Google Cloud

Setelah penyedia rekaman aktivitas dan pengekspor rekaman aktivitas dikonfigurasi dan diaktifkan, Anda dapat melihat data rekaman aktivitas secara hampir real-time saat rekaman aktivitas dan span dibuat untuk setiap permintaan Cloud Storage.

Dengan menggunakan Cloud Trace Explorer di Google Cloud konsol, Anda dapat melihat setiap rekaman aktivitas yang berisi hal berikut:

  • Tampilan tingkat tinggi permintaan Cloud Storage dari ujung ke ujung.

  • Beberapa span, dengan setiap span menangkap satu operasi dengan stempel waktu dalam permintaan Cloud Storage yang dilakukan.

Untuk membaca lebih lanjut tentang rekaman aktivitas dan span, lihat dokumentasi OpenTelemetry tentang rekaman aktivitas dan span.

Harga

Data rekaman aktivitas dikenai biaya. Biaya dihitung berdasarkan jumlah span rekaman aktivitas yang diserap dan dipindai oleh Cloud Trace. Untuk mempelajari lebih lanjut span rekaman aktivitas yang dikenai biaya dan contoh harga, lihat Biaya Cloud Trace.

Sebelum memulai

Sebelum dapat mengumpulkan rekaman aktivitas untuk penggunaan Cloud Storage API, Anda harus menyelesaikan langkah-langkah berikut:

  1. Menginstal library klien Cloud Storage.

  2. Menyiapkan autentikasi.

  3. Mengaktifkan Cloud Trace API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Mengaktifkan API

  4. Aktifkan Cloud Storage API.

    Mengaktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna menulis rekaman aktivitas ke Cloud Trace, minta administrator Anda untuk memberi Anda peran IAM Cloud Trace Agent (roles/cloudtrace.agent) di project yang digunakan oleh klien.

Peran bawaan ini berisi izin cloudtrace.traces.patch , yang diperlukan untuk menulis rekaman aktivitas ke Cloud Trace.

Anda mungkin juga bisa mendapatkan izin ini dengan peran bawaan, atau Anda dapat membuat peran khusus untuk memberikan izin tertentu. Untuk mengetahui petunjuk tentang cara memberikan peran pada project, lihat Memberikan atau mencabut peran. Untuk mengetahui informasi selengkapnya tentang peran Cloud Trace Agent, lihat dokumentasi Identity and Access Management (IAM).

Mengonfigurasi pelacakan untuk aplikasi Anda

Gunakan petunjuk berikut untuk mengonfigurasi pelacakan dan mulai mengumpulkan data rekaman aktivitas menggunakan library klien Cloud Storage:

C++

  1. Instal versi berikut:

    • Library klien C++ versi v2.16.0 atau yang lebih baru

    • C++ versi 14 atau yang lebih baru

  2. Untuk mengaktifkan instrumentasi pelacakan OpenTelemetry di library klien C++, perbarui konfigurasi sistem build Anda untuk CMake atau Bazel.

  3. Buat instance klien Cloud Storage dengan rekaman aktivitas OpenTelemetry diaktifkan. 

    #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. Instal versi library klien Java Cloud Storage berikut:

    • com.google.cloud:google-cloud-storage:2.47.0 atau yang lebih baru

    • com.google.cloud:libraries-bom:26.53.0 atau yang lebih baru

  2. Instal pengekspor Cloud Trace untuk OpenTelemetry. Anda juga dapat menggunakan pengekspor pilihan Anda.

  3. Instal propagator Cloud Trace.

  4. Buat instance klien Cloud Storage dengan rekaman aktivitas OpenTelemetry diaktifkan.

    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. Instal library klien Python Cloud Storage:

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

  2. Instal pengekspor dan propagator Cloud Trace. Anda juga dapat menggunakan pengekspor pilihan Anda.

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

  3. Instal instrumentasi permintaan OpenTelemetry untuk melacak permintaan HTTP yang mendasarinya.

    pip install opentelemetry-instrumentation-requests

  4. Tetapkan variabel lingkungan untuk memilih ikut pelacakan untuk klien penyimpanan Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Konfigurasikan pengekspor rekaman aktivitas dan penyedia rekaman aktivitas. 

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

Melihat rekaman aktivitas Anda

Gunakan Cloud Trace Explorer untuk melihat data rekaman aktivitas Anda di Google Cloud konsol:

  1. Di Google Cloud konsol, buka halaman Trace explorer:

    Buka Trace explorer

    Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

  2. Di halaman Trace explorer, klik rekaman aktivitas tertentu dalam diagram pencar untuk melihat detail rekaman aktivitas.

    Panel Trace details menampilkan tabel span rekaman aktivitas.

  3. Opsional: klik baris span untuk melihat informasi mendetail tentang span tertentu seperti informasi berikut:

    • Atribut: key-value pair yang memberikan informasi tambahan tentang span.

    • Log &peristiwa: entri log yang terkait dengan span.

    • Stack trace: stack trace yang terkait dengan span.

    • Metadata & Link: link ke layanan lain yang Google Cloud terkait dengan span.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Cloud Trace Explorer, lihat Menemukan dan menjelajahi rekaman aktivitas.

Langkah berikutnya