מידע עזר על יכולת הצפייה במיקרו-שירותים (microservices)

נתוני הגדרות

בטבלה הבאה מוגדרים נתוני התצורה שנמצאים במשתני הסביבה.

שדות Spec
project_id מחרוזת

המזהה של הפרויקט שאליו נשלחים נתוני יכולת הצפייה. אם השדה ריק, התוסף gRPC observability ינסה לאחזר את מזהה הפרויקט ממשתני הסביבה או מפרטי ברירת המחדל.

אם הפונקציות לא נמצאות, הן מחזירות שגיאה.
cloud_logging אובייקט

האפשרויות לרישום ביומן מסווגות בטבלה הזו.
אם הערך לא מופיע, הרישום ביומן מושבת.
cloud_logging.client_rpc_events[] רשימה

רשימה של client_rpc_events הגדרות, שמייצגות את ההגדרה של קריאות לשירות מרוחק (RPC) יוצאות מהקובץ הבינארי.

ההגדרות של client_rpc_events נבדקות לפי הסדר שבו הן מופיעות בטקסט, ונעשה שימוש בהגדרה הראשונה שתואמת. אם בקשת RPC לא תואמת לרשומה, המערכת תמשיך לרשומה הבאה ברשימה.
cloud_logging.client_rpc_events[].methods[] רשימה [מחרוזת]

רשימה של מזהי שיטות.

כברירת מחדל, הרשימה ריקה ולא תואמת לאף שיטה.

הערך של השיטה הוא בפורמט [service]/[method].‫

‫* מתקבל כתו כללי לחיפוש עבור:
  • שם ה-method. אם הערך הוא [service]/*, הוא תואם לכל השיטות בשירות שצוין.
  • הערך המלא של השדה שתואם לכל [service]/[method]. הפרמטר לא נתמך אם הערך של client_rpc_events[].exclude הוא true.
  • אי אפשר להשתמש בתו הכללי * בשם השירות באופן עצמאי, */[method] לא נתמך.

אם מציינים את שם השירות, הוא חייב להיות שם השירות המוגדר במלואו, כולל שם החבילה.

דוגמאות:
  • ‫goo.Foo/Bar בוחר רק את השיטה Bar מהשירות goo.Foo, כאן goo הוא שם החבילה.
  • ‫goo.Foo/* בוחר את כל השיטות מהשירות goo.Foo
  • ‫* בוחר את כל השיטות מכל השירותים.
cloud_logging.client_rpc_events[].exclude ‫Bool

האם צריך להחריג את השיטות שמסומנות ב-client_rpc_events[].methods[] מהרישום ביומן.

ערך ברירת המחדל הוא false, כלומר השיטות שמסומנות על ידי התג client_rpc_events[].methods[] נכללות ברשומה ביומן.

אם הערך הוא true, אי אפשר להשתמש בתו הכללי לחיפוש (*) כערך מלא ב-client_rpc_events[].methods[].
cloud_logging.client_rpc_events[].max_metadata_bytes ‫Int

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

ערך ברירת המחדל הוא 0, כלומר לא מתבצעת רישום של מטא-נתונים.
cloud_logging.client_rpc_events[].max_message_bytes ‫Int

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

ערך ברירת המחדל הוא 0, כלומר לא מתבצע רישום של מטען ייעודי (payload) של הודעות.
cloud_logging.server_rpc_events[] רשימה

רשימה של הגדרות server_rpc_events, שמייצגת את ההגדרה של קריאות לשירות מרוחק (RPC) נכנסות לקובץ הבינארי.

ההגדרות של server_rpc_events נבדקות לפי הסדר שבו הן מופיעות בטקסט, ונעשה שימוש בהגדרה הראשונה שתואמת. אם אין התאמה בין בקשת RPC לבין רשומה, המערכת ממשיכה לרשומה הבאה ברשימה.
cloud_logging.server_rpc_events[].methods[] רשימה [מחרוזת]

רשימה של מחרוזות שאפשר לבחור באמצעותן קבוצה של שיטות.

כברירת מחדל, הרשימה ריקה ולא תואמת לאף שיטה.

הערך של השיטה הוא בפורמט [service]/[method].‫

‫* מתקבל כתו כללי לחיפוש עבור:
  • שם ה-method. אם הערך הוא [service]/*, הוא תואם לכל השיטות בשירות שצוין.
  • הערך המלא של השיטה שתואם לכל [service]/[method]. היא לא אפשרית כאשר server_rpc_events[].exclude מתקיים.
  • אי אפשר להשתמש בתו הכללי * בשם השירות באופן עצמאי, */[method] לא נתמך.

אם מציינים את שם השירות, הוא חייב להיות שם השירות המוגדר במלואו, כולל שם החבילה.

דוגמאות:
  • ‫goo.Foo/Bar בוחר רק את השיטה Bar מהשירות goo.Foo, כאשר goo הוא שם החבילה.
  • ‫goo.Foo/* בוחר את כל השיטות מהשירות goo.Foo
  • ‫* בוחר את כל השיטות מכל השירותים.
cloud_logging.server_rpc_events[].exclude ‫Bool

האם צריך להחריג את השיטות שמסומנות ב-server_rpc_events[].methods[] מהרישום ביומן.

ערך ברירת המחדל הוא false, כלומר השיטות שמסומנות על ידי התג server_rpc_events[].methods[] נרשמות ביומן.

אם הערך הוא true, אי אפשר להשתמש בתו הכללי (*) כערך מלא באף רשומה של server_rpc_events[].methods[].
cloud_logging.server_rpc_events[].max_metadata_bytes ‫Int

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

ערך ברירת המחדל הוא 0, כלומר לא מתבצעת רישום של מטא-נתונים.
cloud_logging.server_rpc_events[].max_message_bytes ‫Int

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

ערך ברירת המחדל הוא 0, כלומר לא מתבצע רישום של מטען ייעודי (payload) של הודעות.
cloud_monitoring Object

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

לדוגמה, אם לא מציינים אפשרויות אחרות, קטע הגדרה ריק מאפשר מעקב.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace אובייקט

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

לדוגמה, קטע הגדרה ריק מאפשר מעקב עם אפשרויות ברירת מחדל של הגדרות.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


כשהמעקב מופעל, גם אם שיעור הדגימה הוא 0, ההחלטה לדגום מעקב מסוים מועברת.
cloud_trace.sampling_rate מספר

ההגדרה הגלובלית ששולטת בהסתברות למעקב אחר RPC. לדוגמה:
  • הערך 0.05 מציין שיש סיכוי של 5% למעקב אחר RPC.
  • הערך 1.0 מציין שכל שיחה מתועדת.
  • הערך 0 אומר לא להתחיל מעקבים חדשים.

ערך ברירת המחדל של sampling_rate הוא 0.

התוסף מתחשב בהחלטה לגבי הדגימה שמתקבלת מהמקור. אם בוחרים ב-RPC לדגימה במעלה הזרם, התוסף אוסף טווחים ומעלה את הנתונים אל העורף, ללא קשר להגדרת קצב הדגימה של התוסף.
labels אובייקט

אובייקט JSON שמכיל קבוצה של צמדי מפתח/ערך. המפתח והערך הם מחרוזות.

התוויות מוחלות על Cloud Logging,‏ Cloud Monitoring ו-Cloud Trace ביחד.

הגדרות מעקב

בקטע הזה מפורט מידע על מעקב.

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

כדי שהמעקב בין שירותים יפעל, בעל השירות צריך לתמוך בהעברה של הקשר של המעקב שהתקבל מהשירות במעלה הזרם (או שהתחיל בעצמו) לשירות במורד הזרם. הקשר של המעקב מועבר בין השירותים באמצעות מטא-נתונים של gRPC. חשוב לוודא שהפעלתם את ממשקי Cloud Monitoring,‏ Cloud Logging,‏ Cloud Trace ואת ממשקי ה-API של המיקרו-שירותים, כדי שהשירותים בהגדרה הזו יוכלו לדווח על נתוני הטלמטריה שלהם לשירות המתאים.

בלי תמיכה בהפצה, שירותים במורד הזרם לא יכולים ליצור טווחים למעקב. השינוי לא ישפיע על טווחי תאריכים קיימים. תוספי המיקרו-שירותים (microservices) לתצפית תומכים בפורמט הבינארי של OpenCensus לקידוד ולהצפנת הקשר של המעקב.

תגי Span

הפורמט של שם הטווח הוא:

סוג ערך לדוגמה Usage
טווח RPC [Sent|Recv].helloworld.Greeter.SayHello שם הטווח הוא השם המלא של השיטה, שמחובר באמצעות נקודות, ללא קו נטוי בתחילת השם.
לשמות של Span מתווסף הקידומת Sent. עבור Span של לקוח RPC ו-Recv. עבור Span של שרת RPC לפני שם השיטה המלא.
משך הניסיון Attempt.helloworld.Greeter.SayHello צירוף הקידומת Attempt. לפני השם המלא של השיטה

תוויות של טווחים

השילובים מספקים תוויות שונות של טווחים.

במקרה של טווחים של ניסיונות, מצורפים שני מאפיינים נוספים שקשורים לניסיון חוזר (תוויות של טווחים):

תווית ערך לדוגמה שימוש
previous-rpc-attempts 0 מספר הניסיונות החוזרים לפני ה-RPC הזה.
transparent-retry True/False האם ה-RPC הזה מופעל על ידי ניסיון חוזר שקוף.

הגדרות של המדדים

המדדים הבאים זמינים ומוצגים בלוח בקרה בשם Microservices (gRPC) Monitoring (מעקב אחרי מיקרו-שירותים (gRPC)) עבור תרחישי שימוש נפוצים.

אלה מדדים מצד הלקוח של gRPC:

שם המדד תיאור סוג, יחידה תוויות
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs מספר הניסיונות של RPCs של לקוחות שהתחילו, כולל אלה שלא הושלמו. מצטבר, Int64, ‏ 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs המספר של קריאות ה-RPC של הלקוח שהושלמו, לדוגמה, כשמתקבלת תגובה מהשרת או נשלחת תגובה מהשרת. מצטבר, Int64, ‏ 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency הזמן הכולל שנדרש להשלמת ניסיון RPC, כולל הזמן שנדרש לבחירת ערוץ משנה. מצטבר, התפלגות, אלפיות השנייה grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency הזמן הכולל שלוקח לספריית gRPC להשלים RPC מנקודת המבט של האפליקציה. מצטבר, התפלגות, אלפיות השנייה grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc מספר הבייטים הכולל (דחוסים, לא מוצפנים) שנשלחו בכל הודעות הבקשה לכל ניסיון RPC. מצטבר, התפלגות, לפי grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc המספר הכולל של בייטים (דחוסים, לא מוצפנים) שהתקבלו בכל הודעות התגובה לכל ניסיון RPC. מצטבר, התפלגות, לפי grpc_client_method, grpc_client_status

אלה המדדים שזמינים בצד השרת של gRPC:

שם המדד תיאור סוג, יחידה תוויות
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
המספר של קריאות ה-RPC שהתקבלו בשרת, כולל קריאות RPC שלא הושלמו.		 מצטבר, Int64, ‏ 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
המספר הכולל של קריאות RPC שהושלמו, למשל, כששרת שולח תגובה.		 מצטבר, Int64, ‏ 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
מספר הבייטים הכולל (לא דחוסים ולא מוצפנים) שנשלחו בכל הודעות התגובה לכל RPC.		 מצטבר, התפלגות, לפי grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
המספר הכולל של בייטים (לא דחוסים ולא מוצפנים) שהתקבלו בכל הודעות הבקשה לכל RPC.		 מצטבר, התפלגות, לפי grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
הזמן הכולל שנדרש ל-RPC מנקודת המבט של העברת הנתונים מהשרת (HTTP2 / inproc / cronet).		 מצטבר, התפלגות, אלפיות השנייה grpc_server_method

כל התפלגות בטבלה שלמעלה מכילה היסטוגרמה עם קטגוריות באופן הבא:

  • הגודל בבייטים: 0, ‏ 1024, ‏ 2048, ‏ 4096, ‏ 16384, ‏ 65536, ‏ 262144, ‏ 1048576, ‏ 4194304,‏ 16777216, ‏ 67108864, ‏ 268435456, ‏ 1073741824, ‏ 4294967296

  • זמן האחזור באלפיות השנייה: 0, 0.01, 0.05, 0.1, 0.3, 0.6, 0.8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000

תיאור התג:

  • ‫grpc_client_method: שם השיטה המלא של gRPC, כולל החבילה, השירות והשיטה, לדוגמה, google.bigtable.v2.Bigtable/CheckAndMutateRow
  • ‫grpc_client_status: קוד סטטוס של שרת gRPC שהתקבל, לדוגמה, OK, CANCELLED, DEADLINE_EXCEEDED
  • ‫grpc_server_method: השם המלא של שיטת gRPC, כולל החבילה, השירות והשיטה, לדוגמה, com.exampleapi.v4.BookshelfService/Checkout
  • ‫grpc_server_status: קוד הסטטוס של שרת gRPC שהוחזר, לדוגמה OK,‏ CANCELLED,‏ DEADLINE_EXCEEDED

הגדרות של רשומות ביומן

יומני הנראות של המיקרו-שירותים מועלים ל-Cloud Logging באמצעות שם היומן (PROJECT_ID הוא ה-placeholder למחרוזת שמייצגת את הפרויקט):

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

הנה ייצוג JSON של רשומת היומן שנוצרה:

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

בטבלה הבאה מתוארים השדות ברשומה ביומן:

שדות Spec
רשות מחרוזת

אפשר להשתמש בתהליך יחיד כדי להפעיל כמה שרתים וירטואליים עם זהויות שונות.‫

הסמכות היא השם של זהות שרת כזו. בדרך כלל זה חלק מה-URI בצורה של host או host:port.
callId מחרוזת

מזהה באופן ייחודי קריאה [ללקוח/לשרת] שהיא UUID. כל שיחה יכולה לכלול כמה רשומות ביומן. לכולם יש את אותו callId.
סוג מחרוזת

סוג האירוע ביומן.

סוגי האירועים הם:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
כלי לרישום ביומן מחרוזת

סוג הכלי לרישום אירועים.

סוגי יומני האירועים הם:
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName מחרוזת

השם של השירות.
methodName מחרוזת

השם של ה-method של ה-RPC.
אפליקציה להשוואה אובייקט

פרטי כתובת של עמית. בצד הלקוח, ה-peer נרשם ביומן באירועים של כותרת השרת ובאירועים של הטריילר. בצד השרת, ה-peer תמיד נרשם ביומן באירוע של כותרת הלקוח.
peer.type מחרוזת

סוג הכתובת, אם היא IPv4,‏ IPv6 או UNIX.
peer.address מחרוזת

תוכן הכתובת.
peer.ip_port Int

מספר היציאה של הכתובת. האפשרות הזו זמינה רק לכתובות IPv4 ו-IPv6.
מטען ייעודי (payload) אובייקט

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

  • באירועי הודעות, מטען הייעודי הוא הנתונים בפועל שמועברים כהודעות לקוח/שרת, ואורך ההודעה.
  • באירועים של כותרות, המטען הייעודי (payload) כולל את שם הכותרת והערך שלה.
  • באירועי טריילר, מטען הייעודי (payload) כולל פרטי סטטוס יחד עם מטא-נתונים של הטריילר (אם יש כאלה).
  • באירועי header בצד הלקוח, אם מוגדר פסק זמן, המטען הייעודי (payload) כולל גם את פסק הזמן.
payload.timeout מחרוזת

מחרוזת שמייצגת את google.protobuf.Duration, כמו "1.2 s".

הערך של הזמן הקצוב לתפוגת RPC.
payload.metadata ‫Mapping[String, String]

משמש לאירוע כותרת או לאירוע טריילר.
payload.message מחרוזת (בייטים)

המטען הייעודי של ההודעה.
payload.messageLength Int

גודל ההודעה, בלי קשר לשאלה אם ההודעה המלאה מתועדת (לדוגמה, יכול להיות שהיא קוצצה או הושמטה).
payload.statusCode מחרוזת

קוד הסטטוס של gRPC.
payload.statusMessage מחרוזת

הודעת הסטטוס של gRPC.
payload.statusDetails מחרוזת

הערך של מפתח המטא-נתונים grpc-status-details-bin, אם יש כזה. ההודעה תמיד מקודדת google.rpc.Status
payloadTruncated ‫Bool

הערך הוא True אם ההודעה או שדה המטא-נתונים נחתכו או הושמטו בגלל אפשרויות ההגדרה.
sequenceId ‫Int

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

תוויות משאבים

תוויות משאבים מזהות את המקור שמייצר נתוני יכולת צפייה. כל תווית משאב היא צמד מפתח/ערך, כאשר המפתחות הם ערכים מוגדרים מראש שספציפיים לסביבת המקור (לדוגמה, GKE או Compute Engine).

בפריסות של GKE, התוויות של המשאבים מאוכלסות כברירת מחדל, למעט שם הקונטיינר ושם מרחב השמות. אפשר לאכלס את הערכים החסרים באמצעות Downward API.

אלה המפתחות של משתני הסביבה:

  • CONTAINER_NAME
  • NAMESPACE

לדוגמה, הקטע env בדוגמה הבאה כולל שתי תוויות משאבים:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

תוויות מותאמות אישית

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

אפשר לספק תוויות בהתאמה אישית בהגדרה על ידי ציון רשימה של צמדי מפתח-ערך עבור labels. ההטמעה קוראת את ההגדרה ויוצרת תווית נפרדת לכל צמד מפתח/ערך, ואז מצרפת את התווית לנתוני יכולת הצפייה. לדוגמה:

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

כל רשומה ביומן מכילה את התוויות הנוספות הבאות:

{
   "DATACENTER": "SAN_JOSE_DC"
   "APP_ID": "24512"
}

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