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

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

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

אותות זמינים

האותות המהימנים כוללים את נתוני הטלמטריה הבאים, בהתאם למוסכמות הסמנטיות של OpenTelemetry:

  • עקבות: עקבות ברמה נמוכה של HTTP/gRPC שמייצגים את בקשות הרשת שנוצרות על ידי ספריות הלקוח.
  • מדדים: מדדים של בקשות לקוח, מעקב אחר זמן האחזור ושיעורי הבקשות. המדד הראשי הוא gcp.client.request.duration.
  • יומנים: יומני שגיאות שאפשר לפעול לפיהם ברמה DEBUG, שמספקים פרטים על בקשות שנכשלו בשכבת התעבורה, גם אם בסופו של דבר נעשה ניסיון חוזר והבקשות הצליחו.

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

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

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

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

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

מעקב ומדדים

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

  • מעקב: מגדירים את הלקוח באמצעות OpenTelemetryTracingFactory.
  • מדדים: מגדירים את הלקוח באמצעות OpenTelemetryMetricsFactory.
  • גם וגם: אם רוצים להפעיל גם מעקב וגם מדדים, צריך להגדיר את הלקוח באמצעות CompositeTracerFactory שעוטף את שני המפעלים.

רישום ביומן

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

export GOOGLE_SDK_JAVA_LOGGING=true

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

כדי להשתמש בהעברת הקשר של Trace בספריות הלקוח של Java, צריך להפעיל את Trace באופן מפורש.

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

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

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

מעקב ומדדים

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

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

רישום ביומן

ספריות הלקוח של Java משתמשות במסגרות רישום סטנדרטיות כמו SLF4J ו-java.util.logging. כשהערך של GOOGLE_SDK_JAVA_LOGGING=true מוגדר, יומני שגיאות עם פעולות שאפשר לבצע מופקים ברמה DEBUG.

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

הוראות מפורטות להגדרת Logback או java.util.logging כדי להפיק JSON שתואם ל-Cloud Logging, כולל קורלציה של מעקב, זמינות במאמר הגדרת רישום מובנה ביומן ל-Java.