Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

הפעלה של אותות טלמטריה בספריות לקוח של Rust

Google Cloud מספק ניטור, רישום ביומן וניתוח עוצמתיים לאפליקציות Rust.

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

אותות זמינים

ספריות הלקוח של Rust מוגדרות ליצירת האותות הבאים:

INFO טווחים לכל בקשת לקוח לוגית. בדרך כלל, יחידה לוגית למעקב כזה מתקבלת מהפעלת method יחידה במבנה הלקוח (לדוגמה, קריאה של access_secret_version בלקוח SecretManagerService).
מדד היסטוגרמה שמודד את הזמן שחלף עבור כל בקשת לקוח לוגית. המדד הראשי הוא gcp.client.request.duration.
WARN יומנים לכל בקשת לקוח לוגית שנכשלת.
‫INFO spans לכל ניסיון RPC ברמה נמוכה. בדרך כלל, שיטה אחת במבנה הלקוח מקבלת יחידה לוגית למעקב כזה, אבל יכול להיות שיהיו יותר אם הספרייה תצטרך לנסות שוב את ה-RPC.
DEBUG יומני רישום לכל ניסיון ברמה נמוכה שנכשל.

הטווחים והיומנים האלה פועלים לפי מוסכמות סמנטיות של OpenTelemetry עםGoogle Cloud מאפיינים נוספים. הטווחים והיומנים צריכים להתאים לניטור של סביבת ייצור.

האותות כוללים מאפיינים סטנדרטיים של OpenTelemetry (לדוגמה, http.response.status_code ו-rpc.system.name) ומאפיינים מותאמים אישית ספציפיים ל- Google Cloud, שעשויים לכלול את המאפיינים הבאים ומאפיינים דומים:

‫gcp.client.service: שם השירות (לדוגמה, pubsub או storage).
‫gcp.client.repo: מאגר ספריית הלקוח (לדוגמה, googleapis/google-cloud-rust).
‫gcp.client.version: גרסת ספריית הלקוח.
‫gcp.client.artifact: הנתיב הספציפי של המודול (לדוגמה, google-cloud-secretmanager).
‫gcp.resource.destination.id: המזהה של המשאב שעליו מתבצעת הפעולה.
gcp.errors.domain: דומיין השגיאה ליומני שגיאות שניתן לפעול לפיהם.
‫gcp.errors.metadata.<key>: מפתחות נוספים של מטא-נתונים של שגיאות לבקשות שנכשלו (שטוחים).

רשימה מלאה של מאפיינים סטנדרטיים זמינה במוסכמות סמנטיות של OpenTelemetry HTTP ו-gRPC.

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

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

הטווחים האלה DEBUG משתמשים בתיבת הכלים של ספריית הלקוח ואחריה ::tracing כיעד שלהם (לדוגמה, google_cloud_secretmanager_v1::tracing) ובשם השיטה כשם הטווח (לדוגמה, access_secret_version). אפשר להשתמש בשם, ביעד או בשניהם כדי להגדיר את המסננים.

הפעלת טלמטריה

כדי להגן על מידע אישי רגיש, אותות הטלמטריה מושבתים כברירת מחדל.

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

כדי להגדיר את הלקוח, אפשר להגדיר את משתנה הסביבה הבא:

export GOOGLE_CLOUD_RUST_LOGGING=true

לחלופין, אפשר להפעיל את המעקב באופן מפורש באמצעות תכנות כשיוצרים את הלקוח, באמצעות השיטה .with_tracing() בכלי ליצירת לקוחות:

use google_cloud_secretmanager_v1::client::SecretManagerService;

let client = SecretManagerService::builder()
    .with_tracing()
    .build()
    .await?;

הפצת הקשר של מעקב

ספריות הלקוח של Rust מעבירות באופן אוטומטי הקשרים פעילים של מעקב אלGoogle Cloud שירותים, גם אם יצירת מעקב לא מופעלת באופן מפורש באמצעות .with_tracing().

משתמשים בתיבות tracing-opentelemetry או opentelemetry כדי לספק הקשר למעקב אחר ספריות הלקוח.

ייצוא נתוני טלמטריה

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

סקיצה

כדי לייצא את הטווחים tracingשנוצרו על ידי ספריות הלקוח אל Google Cloud OpenTelemetry, צריך להגדיר Subscriber באפליקציה צינור להעברת נתונים אל כלי לייצוא נתונים של OpenTelemetry (לדוגמה, OTLP).

משתמשים בתיבות tracing-opentelemetry ו-opentelemetry-otlp כדי להגדיר את יצואן הנתונים:

use google_cloud_secretmanager_v1::client::SecretManagerService;
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt;

pub async fn sample() -> anyhow::Result<()> {
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .build();
    let tracer = provider.tracer("example");

    // Create a tracing layer that sends data to an OpenTelemetry Collector running on localhost.
    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);

    // Register the subscriber globally
    let subscriber = Registry::default().with(telemetry);
    tracing::subscriber::set_global_default(subscriber)?;

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

מדדים

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

לפרטים נוספים על איסוף וייצוא של נתוני OpenTelemetry אל Cloud Monitoring או Cloud Trace, אפשר לעיין במאמר בחירת גישה למדידה.

רישום ביומן

ספריות הלקוח של Rust משתמשות בתיבת הכלים tracing כדי ליצור יומני שגיאות שניתן לפעול לפיהם ברמות WARN ו-DEBUG. היומנים המיוצאים יכללו מזהי מעקב ומזהי טווח כדי להבטיח קורלציה חלקה עם המעקבים שלכם, בתנאי שתשתמשו במעצב מתאים.

כדי להעביר את היומנים המובנים האלה ל-Cloud Logging, צריך להגדיר מנוי למעקב כדי לעצב אירועים כ-JSON ולפלט לפלט רגיל (stdout). אם אתם פורסים לסביבה כמו Google Kubernetes Engine או Cloud Run, הסוכנים המובנים סורקים את היומנים האלה באופן אוטומטי.

בדוגמה הבאה מוגדר מנוי ללכידה ולהעברה רק של יומנים ברמה WARN.

use google_cloud_secretmanager_v1::client::SecretManagerService;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

pub async fn sample() -> anyhow::Result<()> {
    // Enable all `WARN` logs to include failed client requests in all client libraries.
    let filter = tracing_subscriber::EnvFilter::new("warn");

    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer().json())
        .init();

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

הוראות מפורטות להגדרת נתוני קורלציה של עקבות OpenTelemetry (כמו logging.googleapis.com/trace) במעצב JSON מופיעות במאמר סקירה כללית של דוגמאות למכשור מבוסס-אוסף.

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