‫C++‎ ו-OpenTelemetry

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

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

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

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

לתוכן עזר בנושא OpenTelemetry, אפשר לעיין במקורות הבאים:

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

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

מפעילים את Cloud Trace API.

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

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

להפעלת ה-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 שבו רוצים לאחסן את העקבות.

ה-method‏ ConfigureBasicTracing(...) יוצרת מופע של אובייקט TracerProvider שמטמיע יצואן של Cloud Trace. אם האובייקט שמוחזר על ידי הקריאה ל-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, אפשר לעיין בקטע פתרון בעיות במשאבי העזרה.

משאבים