‫C++‎ ו-OpenTelemetry

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

בדף הזה מפורטים השלבים הבאים:

  • מתקינים את חבילות OpenTelemetry.
  • מגדירים את האפליקציה לייצא טווחים ל-Cloud Trace.
  • מגדירים את הפלטפורמה.

מידע על הגרסה זמין במאמרים הבאים:

לעיון בתוכן עזר בנושא OpenTelemetry:

פרטים עדכניים על OpenTelemetry ל-C++, תיעוד נוסף ודוגמאות זמינים בכתובת OpenTelemetry.

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

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

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

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

להפעלת ה-API

התקנת חבילות OpenTelemetry

הגדרת ייצוא של טווחים ל-Cloud Trace

כדי להגדיר את הייצוא של נתוני מעקב, צריך להפעיל את השיטה google::cloud::otel::ConfigureBasicTracing(...) בשיטה main():

namespace gc = ::google::cloud;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  MyApplicationCode();
}

השדה project_id הוא Google Cloud הפרויקט שבו רוצים לאחסן את העקבות.

השיטה ConfigureBasicTracing(...) יוצרת מופע של אובייקט TracerProvider שמטמיע Cloud Trace exporter. אם האובייקט שמוחזר על ידי הקריאה ל-ConfigureBasicTracing(...) יוצא מההקשר, האובייקט הקודם TracerProvider מוחזר, אם הוא קיים.

הגדרת תדירות הדגימה

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

namespace gc = ::google::cloud;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto options = gc::Options{}.set<gc::otel::BasicTracingRateOption>(.001);
  auto configuration = gc::otel::ConfigureBasicTracing(project, options);

  MyApplicationCode();
}

ייצוא ל-Cloud Trace עם TracerProvider מותאם אישית

יכול להיות שיהיו לכם תרחישי שימוש שידרשו אובייקט TracerProvider מותאם אישית. לדוגמה, אם רוצים להשתמש בכמה כלי ייצוא בו-זמנית, צריך ליצור אובייקט TracerProvider בהתאמה אישית. במקרים כאלה, אפשר להשתמש ישירות בכלי לייצוא של Cloud Trace:

namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  // Use the Cloud Trace Exporter directly.
  auto project = gc::Project(std::move(project_id));
  auto exporter = gc::otel::MakeTraceExporter(project);

  // Advanced use cases may need to create their own tracer provider, e.g. to
  // export to Cloud Trace and another backend simultaneously. In this
  // example, we just tweak some OpenTelemetry settings that google-cloud-cpp
  // does not expose.
  opentelemetry::sdk::trace::BatchSpanProcessorOptions options;
  options.schedule_delay_millis = std::chrono::milliseconds(1000);
  auto processor =
      opentelemetry::sdk::trace::BatchSpanProcessorFactory::Create(
          std::move(exporter), options);

  // Create a tracer provider and set it as the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      std::shared_ptr<opentelemetry::trace::TracerProvider>(
          opentelemetry::sdk::trace::TracerProviderFactory::Create(
              std::move(processor))));

  MyApplicationCode();

  // Clear the global trace provider
  opentelemetry::trace::Provider::SetTracerProvider(
      opentelemetry::nostd::shared_ptr<
          opentelemetry::trace::TracerProvider>());
}

לבצע אינסטרומנטציה באפליקציה שלכם

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

  • יצירת טווח
  • יצירת טווחים מוטמעים
  • הגדרת מאפיינים של span
  • יצירת טווחי זמן עם אירועים
  • יצירת טווחים עם קישורים
// For more details on the OpenTelemetry code in this sample, see:
//     https://opentelemetry.io/docs/instrumentation/cpp/manual/
namespace gc = ::google::cloud;
using ::opentelemetry::trace::Scope;
[](std::string project_id) {
  auto project = gc::Project(std::move(project_id));
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  // Initialize the `Tracer`. This would typically be done once.
  auto provider = opentelemetry::trace::Provider::GetTracerProvider();
  auto tracer = provider->GetTracer("my-application");

  // If your application makes multiple client calls that are logically
  // connected, you may want to instrument your application.
  auto my_function = [tracer] {
    // Start an active span. The span is ended when the `Scope` object is
    // destroyed.
    auto scope = Scope(tracer->StartSpan("my-function-span"));

    // Any spans created by the client library will be children of
    // "my-function-span". i.e. In the distributed trace, the client calls are
    // sub-units of work of `my_function()`, and will be displayed as such in
    // Cloud Trace.
    Client client;
    client.CreateFoo();
    client.DeleteFoo();
  };

  // As an example, start a span to cover both calls to `my_function()`.
  auto scope = Scope(tracer->StartSpan("my-application-span"));
  my_function();
  my_function();
}

אפליקציה לדוגמה

אפשר לעיין במדריך למתחילים כדי לראות אפליקציה לדוגמה.

הגדרת הפלטפורמה

אפשר להשתמש ב-Cloud Trace ב- Google Cloud ובפלטפורמות אחרות.

הפעילות מתבצעת ב- Google Cloud

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

רשימת הסביבות הנתמכות Google Cloud זמינה במאמר תמיכה בסביבה.

בהגדרות הבאות, הגדרות ברירת המחדל של היקף הגישה מאפשרות את Cloud Trace API:

אם אתם משתמשים בהיקפי גישה בהתאמה אישית, אתם צריכים לוודא שהיקף הגישה של Cloud Trace API מופעל:

  • במאמר הגדרת Google Cloud פרויקט מוסבר איך מגדירים את היקפי הגישה לסביבה באמצעות מסוף Google Cloud .

  • משתמשי gcloud צריכים לציין את היקפי הגישה באמצעות הדגל --scopes ולכלול את היקף הגישה של Cloud Trace API‏ trace.append. לדוגמה, כדי ליצור אשכול GKE שמופעל בו רק Cloud Trace API, מבצעים את הפעולות הבאות:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

הפעלה מקומית ובמקומות אחרים

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

Google Cloud ספריות הלקוח משתמשות ב-Application Default Credentials ‏ (ADC) כדי למצוא את פרטי הכניסה של האפליקציה.

יש שלוש דרכים לספק את פרטי הכניסה האלה:

  • מריצים את gcloud auth application-default login

  • ממקמים את חשבון השירות בנתיב ברירת המחדל של מערכת ההפעלה. ברשימה הבאה מפורטות נתיבי ברירת המחדל ל-Windows ול-Linux:

    • ב-Windows:‏ %APPDATA%/gcloud/application_default_credentials.json‎

    • ‫Linux: ‏ $HOME/.config/gcloud/application_default_credentials.json

  • מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של חשבון השירות:

‫Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

‫PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

הצגת עקבות

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

כניסה אל Trace explorer

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

פתרון בעיות

מידע על פתרון בעיות ב-Cloud Trace זמין בדף פתרון הבעיות.

כדי לנפות באגים בייצוא C++‎ Cloud Trace, אפשר לעיין בקטע פתרון בעיות במשאבי העזרה.

משאבים