שימוש בנתוני מעקב בצד הלקוח

בדף הזה מוסבר איך להפעיל מעקב בצד הלקוח באמצעות OpenTelemetry כשמשתמשים בספריות הלקוח של Cloud Storage כדי ליצור אינטראקציה עם Cloud Storage. אפשר לאסוף ולהציג נתוני מעקב באמצעות ספריות הלקוח הנתמכות הבאות של Cloud Storage:

סקירה כללית

הפעלת מעקב בספריות הלקוח של Cloud Storage מאפשרת לכם לעקוב אחרי הביצועים, לזהות בעיות של זמן אחזור ולבצע במהירות ניפוי באגים בבקשות של Cloud Storage. באמצעות מעקב אפשר לראות את הרצף של בקשה שהושלמה, ולקבל תצוגה מפורטת של האופן שבו הבקשה התקבלה, טופלה ונענתה על ידי Cloud Storage. כל מעקב מורכב מכמה טווחים, שהם רשומות מפורטות עם חותמת זמן של כל פונקציה או פעולה שהאפליקציה ביצעה במהלך הבקשה ל-Cloud Storage.

יתרונות

איסוף נתוני מעקב והפצתם מספק לאפליקציה את היתרונות הבאים:

  • שיפור הנראות של הביצועים: נתוני המעקב נוצרים כמעט בזמן אמת כש-Cloud Storage משלים כל בקשה שאתם שולחים, כך שאתם יכולים לזהות במהירות צווארי בקבוק בביצועים ולגלות בעיות של זמן אחזור.

  • טיפול בשגיאות: אפשר לזהות בדיוק איפה מתעוררות בעיות, להאיץ את ניתוח שורש הבעיה ולקצר את זמן ההשבתה באמצעות המידע על כל בקשה ל-Cloud Storage שמופיע במעקב.

איך פועלים מעקבים בצד הלקוח

בקטעים הבאים מוסבר בפירוט איך איסוף נתוני ה-trace מתבצע.

איך איסוף נתוני מעקב פועל עם OpenTelemetry

ספריות הלקוח של Cloud Storage תומכות באיסוף נתוני מעקב באמצעות OpenTelemetry SDK כדי להגדיר את הרכיבים הבאים שנדרשים לאיסוף ולהפצה של נתוני מעקב:

  • ספק Trace: ספק ה-Trace משמש את ספריות הלקוח של Cloud Storage, והוא אחראי ליצירה ולניהול של מערכת המעקב, כולל יצירה וניהול של מעקבים וטווחים באפליקציה.

  • ‫Trace exporter: מודול זה משמש את OpenTelemetry SDK, והוא אחראי לשליחת נתוני מעקב לפלטפורמת קצה עורפית (backend) של יכולת צפייה, כמו Cloud Trace, שבה אפשר לנתח ולהציג נתוני מעקב. מידע נוסף על כלי לייצוא של נתוני מעקב

איך פועלים כלי ייצוא של נתוני מעקב

הגדרת מעקב באמצעות OpenTelemetry SDK כוללת בחירה של קצה עורפי (backend) של יכולת צפייה (observability) לייצוא הנתונים, שבו הם מנותחים, מאוחסנים ומוצגים. אפשר לייצא את נתוני העקבות לכל מערכת עורפית (backend) של כלי ניטור לבחירתכם, אבל מומלץ להשתמש ב-Cloud Trace, שאפשר לגשת אליו באמצעות מסוף Google Cloud והוא מספק שילוב עם שירותים אחרים של Google Cloud .

אחרי שמגדירים ומפעילים את ספק הנתונים של Trace ואת כלי הייצוא של Trace, אפשר לראות את נתוני ה-Trace כמעט בזמן אמת, כשמערכות Trace ו-Span נוצרות לכל בקשה של Cloud Storage.

באמצעות הכלי Cloud Trace explorer בGoogle Cloud מסוף, אפשר לראות כל מעקב שמכיל את הפרטים הבאים:

  • תצוגה ברמה גבוהה של בקשה ל-Cloud Storage מקצה לקצה.

  • מספר יחידות לוגיות למעקב, כשכל אחת מהן מתעדת פעולה יחידה עם חותמת זמן בבקשת Cloud Storage שבוצעה.

מידע נוסף על עקבות ויחידות לוגיות למעקב זמין במאמרי העזרה של OpenTelemetry בנושא עקבות ויחידות לוגיות למעקב.

תמחור

הנתונים של כלי המעקב כרוכים בתשלום. החיובים מבוססים על מספר טווחי המעקב שנקלטים ונבדקים על ידי Cloud Trace. מידע נוסף על טווחים של מעקב שאפשר לחייב עליהם ודוגמאות לתמחור זמין במאמר עלויות של Cloud Trace.

לפני שמתחילים

כדי לאסוף נתוני מעקב על השימוש ב-API של Cloud Storage, צריך לבצע את השלבים הבאים:

  1. מתקינים את ספריית הלקוח של Cloud Storage.

  2. מגדירים אימות.

  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. מפעילים את Cloud Storage API.

    להפעלת ה-API

התפקידים הנדרשים

כדי לקבל את ההרשאה שנדרשת לכתיבת נתונים של מעקב ל-Cloud Trace, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Cloud Trace Agent (roles/cloudtrace.agent) בפרויקט שבו הלקוח משתמש.

התפקיד המוגדר מראש הזה כולל את ההרשאה cloudtrace.traces.patch, שנדרשת כדי לכתוב נתונים של מעקב ל-Cloud Trace.

יכול להיות שתוכלו לקבל את ההרשאות האלה גם באמצעות תפקידים מוגדרים מראש, או שתוכלו ליצור תפקידים בהתאמה אישית כדי להעניק הרשאות ספציפיות. הוראות להקצאת תפקידים בפרויקטים מופיעות במאמר הקצאה או ביטול של תפקיד. למידע נוסף על התפקיד של Cloud Trace Agent, אפשר לעיין במשאבי העזרה בנושא ניהול זהויות והרשאות גישה (IAM).

הגדרת מעקב באפליקציה

כדי להגדיר מעקב ולהתחיל לאסוף נתוני מעקב באמצעות ספריית הלקוח של Cloud Storage, פועלים לפי ההוראות הבאות:

C++‎

  1. מתקינים את הגרסאות הבאות:

    • ספריית הלקוח של C++‎ בגרסה v2.16.0 ואילך

    • ‫C++‎ מגרסה 14 ואילך

  2. כדי להפעיל את אינסטרומנטציית המעקב של OpenTelemetry בספריית הלקוח C++, צריך לעדכן את ההגדרות של מערכת ה-build ב-CMake או ב-Bazel.

  3. יצירת מופע של לקוח Cloud Storage עם מעקב OpenTelemetry מופעל. 

    #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. מתקינים את הגרסאות הבאות של ספריית הלקוח Cloud Storage Java:

    • com.google.cloud:google-cloud-storage:2.47.0 או מאוחר יותר

    • com.google.cloud:libraries-bom:26.53.0 או מאוחר יותר

  2. מתקינים את Cloud Trace exporter for OpenTelemetry. אפשר גם להשתמש בכל כלי ייצוא שתבחרו.

  3. מתקינים את הכלי להפצת נתונים של Cloud Trace.

  4. יצירת מופע של לקוח Cloud Storage עם מעקב OpenTelemetry מופעל.

    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. מתקינים את ספריית הלקוח של Cloud Storage Python:

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

  2. מתקינים את כלי הייצוא ואת כלי ההפצה של Cloud Trace. אפשר גם להשתמש בכל כלי ייצוא שרוצים.

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

  3. מתקינים את OpenTelemetry requests instrumentation כדי לעקוב אחרי בקשות ה-HTTP הבסיסיות.

    pip install opentelemetry-instrumentation-requests

  4. מגדירים את משתנה הסביבה כדי להפעיל מעקב באופן סלקטיבי עבור לקוח האחסון של Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. מגדירים את כלי הייצוא של נתוני המעקב ואת ספק נתוני המעקב. 

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

הצגת העקבות

כדי להציג את נתוני העקבות במסוף, משתמשים בכלי לבדיקת עקבות ב-Cloud Trace: Google Cloud

  1. נכנסים לדף Trace explorer במסוף Google Cloud :

    כניסה אל Trace explorer

    אפשר גם להשתמש בסרגל החיפוש כדי למצוא את הדף הזה.

  2. בדף Trace explorer, לוחצים על trace ספציפי בתרשים הפיזור כדי לראות את פרטי ה-trace.

    בחלונית Trace details מוצגת טבלה של טווחים של מעקב.

  3. אופציונלי: לוחצים על שורה של יחידה לוגית למעקב כדי לראות מידע מפורט על יחידה לוגית למעקב ספציפית, כמו המידע הבא:

    • מאפיינים: צמדי מפתח/ערך שמספקים מידע נוסף על הטווח.

    • רישומים ואירועים: רשומות ביומן שמשויכות ליחידה לוגית למעקב.

    • מעקבי ערימה: מעקבי ערימה שמשויכים לטווח.

    • מטא-נתונים וקישורים: קישורים לשירותים אחרים של Google Cloud Google שמשויכים לטווח.

מידע נוסף על השימוש בכלי לבדיקת מעקב ב-Cloud Trace זמין במאמר חיפוש מעקבים ובדיקתם.

המאמרים הבאים