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

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

סקירה כללית

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

יתרונות

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

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

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

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

בקטעים הבאים מוסבר בפירוט איך פועל איסוף המעקבים.

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

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

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

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

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

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

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

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

  • סקירה כללית של בקשה ב-Cloud Storage מקצה לקצה.

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

למידע נוסף על מעקבים וטווחים, קראו את המסמכים של OpenTelemetry בנושא מעקבים וטווחים.

תמחור

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

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

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

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

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

  3. מפעילים את Cloud Trace API, אם הוא עדיין לא מופעל.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    להפעלת ה-API

  4. מפעילים את Cloud Storage API.

    להפעלת ה-API

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

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

התפקיד המוגדר מראש הזה כולל את ההרשאה 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 ל-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 כדי לעקוב אחרי בקשות ה-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 Explorer כדי להציג את נתוני המעקב במסוף Google Cloud :

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

    כניסה לדף Trace Explorer

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

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

    בחלונית Trace details מוצגת טבלה של פרקי זמן למעקב.

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

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

    • ‫Logs & events: רשומות ביומן שמשויכות לטווח.

    • דוחות קריסות: דוחות קריסות שמשויכים ל-span.

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

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

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