מיפוי של רשומת יומן OTLP לרשומה ביומן

במאמר הזה מוסבר איך Google Cloud Observability קובע את השדות של LogEntry מתוך רשומת יומן OTLP, כשהרשומה הזו נשלחת אל Google Cloud באמצעות Telemetry API.

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

המבנה הכללי של נתוני יומן בפורמט OTLP

כששולחים נתוני יומן ל- Google Cloud באמצעות Telemetry API, הנתונים האלה צריכים להיות בפורמט שתואם ל-OTLP. המבנה הכללי של הנתונים האלה מוצג כאן:

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "logRecords": [...]
        }
      ]
    }
]

שימו לב ש-OpenTelemetry מאגדת יומנים נפרדים, שכל אחד מהם מיוצג על ידי מבנה logRecord, עם מידע על המקור של היומנים האלה, שמיוצג על ידי מבנה resource.

כש-Google Cloud Observability מקבל אובייקט resourceLogs, הוא יוצר LogEntry אחד לכל logRecord. בניגוד ל-OTLP שבו מידע על המקור מצורף לקבוצה של יומנים נפרדים, כל מבנה LogEntry מכיל מידע על המקור של היומן ועל היומן עצמו.

מידע נוסף על המבנה של נתוני יומן בפורמט OTLP זמין ב-OpenTelemetry logs.proto.

איך מוגדרים השדות של LogEntry

מערכת Google Cloud Observability משתמשת בכללים הבאים כדי לקבוע את הערכים של השדות LogEntry:

השדה LogEntry (שמות מהפניה ל-HTTP)	איך המערכת קובעת את ערך השדה
logName	המערכת משתמשת בערך של השדה event_name ב-OTLP LogRecord. אם השדה הזה לא קיים או לא מוגדר, המערכת משתמשת ברשימה הבאה של מאפייני רשומת יומן OpenTelemetry כדי לקבוע את שם היומן, לפי סדר העדיפות: log.name gcp.log.name log_name gcp.log_name logging.googleapis.com/logName service.name gcp.service.name service_name gcp.service_name event.name gcp.event.name event_name gcp.event_name שמות היומנים צריכים להיות בפורמט שמתאים לכתובות URL, אחרת הם מקודדים בפורמט URL במהלך ההטמעה.
resource	המערכת משתמשת במידע שמוגדר בשדה resource או מסיקה את המשאב. פרטים נוספים זמינים במאמר בנושא מיפוי מאפייני OTLP לסוג משאב.
timestamp	המערכת משתמשת ברשימה הבאה של שדות ברשומת יומן OpenTelemetry, לפי סדר עדיפויות, כדי לקבוע את timestamp: ‫time_unix_nano כשהערך שונה מאפס. ‫observed_time_unix_nano כשהערך שונה מאפס. השעה שבה הרשומה ביומן נקלטה. תקופת השמירה של קטגוריה ביומן שבה הנתונים מאוחסנים קובעת את חותמת הזמן הכי ישנה שאפשר להטמיע. מידע נוסף זמין במאמר בנושא מכסות ב-Cloud Logging.
receiveTimestamp	השעה שמוגדרת היא השעה שבה המידע על LogEntry נקלט.
severity	המערכת ממפה את רמת החומרה של OpenTelemetry ברשומה ביומן לרמת חומרה ב-Cloud Logging. פרטים נוספים מופיעים במאמר בנושא השדה 'חומרה'.
httpRequest	המערכת ממפה את המאפיינים gcp.http_request ברשומה של היומן לשדות המקבילים LogEntry. המערכת מקבלת את המאפיינים האלה כמאפיינים מובְנים או כמחרוזת JSON. מידע נוסף זמין במאמר בנושא השדה HttpRequest.
labels	המערכת מגדירה את השדה הזה באמצעות ערכי המאפיינים של רשומת היומן. מידע נוסף זמין במאמר בנושא שדה התוויות.
trace	המערכת מגדירה את השדה הזה לערך מהשדה traceId ברשומה של היומן. הערך חייב להיות מחרוזת הקסדצימלית חוקית באורך 32 תווים, אחרת הרשומה תידחה.
spanId	המערכת מגדירה את השדה הזה לערך מהשדה spanId ברשומה של היומן. הערך חייב להיות מחרוזת הקסדצימלית תקינה באורך 16 תווים, אחרת הרשומה תידחה.
traceSampled	המערכת מגדירה את השדה הזה על סמך הביט הכי פחות משמעותי מהשדה flags ברשומה של היומן. אם הביט הכי פחות משמעותי שווה ל-1, השדה הזה מוגדר ל-true. אחרת, הוא לא מוגדר.
sourceLocation	המערכת מגדירה את השדה הזה לערכים ממאפייני הקוד של רשומת היומן. מידע נוסף זמין במאמר בנושא השדה SourceLocation.
split	לא מוגדר.
apphub apphubDestination apphubSource	לא מוגדר.
otel	בשדות בנתוני יומן OTLP שאין להם שדה מקביל ב-LogEntry, המערכת ממירה את סוגי הנתונים ואז מוסיפה את הנתונים המומרים לשדה otel. מידע נוסף זמין במאמר בנושא שדה Otel.
operation	המערכת ממפה את המאפיינים gcp.operation ברשומה של היומן לשדות המקבילים LogEntry. מידע נוסף זמין במאמר בנושא שדה הפעולה.
Payload	המערכת מגדירה את מטען הייעודי (payload) על ידי המרה של גוף רשומת היומן לסוג מטען ייעודי מתאים. מידע נוסף זמין במאמר בנושא שדה מטען.

שדה HttpRequest

‫Google Cloud Observability ממפה מאפייני OTLP שחלים על בקשות HTTP לשדות LogEntry. בקטעים הבאים מוסבר איך המערכת ממפה מאפיינים שטוחים ומאפיינים מקוננים.

מאפיינים שטוחים

בטבלה הבאה מוסבר איך Google Cloud Observability ממפה מאפיינים שטוחים שחלים על בקשות HTTP לשדות LogEntry. לדוגמה, הערך מהמאפיין http.request.method: "GET", מוגדר כערך של השדה httpRequest.requestMethod ברשומה ביומן:

OpenTelemetry LogRecord.attribute צמד מפתח/ערך.	הערך שמאוחסן בשדה הבא LogEntry (שמות מהפניה ל-HTTP)	סוג הפריט שאושר
http.request.method	httpRequest.requestMethod	מחרוזת
url.full http.url	httpRequest.requestUrl	מחרוזת
http.request.body.size	httpRequest.requestSize	מחרוזת, מספר שלם
http.response.status_code	httpRequest.status	מחרוזת, מספר שלם
http.response.body.size	httpRequest.responseSize	מחרוזת, מספר שלם
user_agent.original http.user_agent	httpRequest.userAgent	מחרוזת
client.address	remoteIp	מחרוזת
server.address	serverIp	מחרוזת
referrer	httpRequest.referer	מחרוזת
latency	httpRequest.latency	מחרוזת, מספר שלם
cacheLookup	httpRequest.cacheLookup	bool
cacheHit	httpRequest.cacheHit	bool
cacheValidatedWithOriginServer	httpRequest.cacheValidatedWithOriginServer	bool
cacheFillBytes	httpRequest.cacheFillBytes	מחרוזת, מספר שלם
network.protocol.version protocol	httpRequest.protocol	מחרוזת

מאפיינים מוטמעים

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

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

הפורמט של השדה gcp.http_request יכול להיות מאפיינים מובְנים ומקוננים או מחרוזת JSON של מאפיינים מובְנים.

log_record {
  attributes: {
    gcp.http_request: "{\"requestMethod\": \"GET\", \"requestUrl\": \"some-URL\"}"
  }
}

בטבלה, מאפייני המשנה מוצגים באמצעות סוגריים מסולסלים. לדוגמה, gcp.http_request {requestMethod} אומר שהמאפיין gcp.http_request מכיל את המאפיין requestMethod. הערך מהמאפיין הפנימי ביותר מוקצה לערך של שדה רשומת היומן:

OpenTelemetry LogRecord.attribute צמד מפתח/ערך.	הערך שמאוחסן בשדה הבא LogEntry (שמות מהפניה ל-HTTP)	סוג הפריט שאושר
gcp.http_request {requestMethod} http_request {requestMethod}	httpRequest.requestMethod	מחרוזת
gcp.http_request {requestUrl} http_request {requestUrl}	httpRequest.requestUrl	מחרוזת
gcp.http_request {requestSize} http_request {requestSize}	httpRequest.requestSize	מחרוזת, מספר שלם
gcp.http_request {status} http_request {status}	httpRequest.status	מחרוזת, מספר שלם
gcp.http_request {responseSize} http_request {responseSize}	httpRequest.responseSize	מחרוזת, מספר שלם
gcp.http_request {userAgent} http_request {userAgent}	httpRequest.userAgent	מחרוזת
gcp.http_request {remoteIp} http_request {remoteIp}	httpRequest.remoteIp	מחרוזת
gcp.http_request {serverIp} http_request {serverIp}	httpRequest.serverIp	מחרוזת
gcp.http_request {referer} http_request {referrer}	httpRequest.referer	מחרוזת
gcp.http_request {latency} http_request {latency}	httpRequest.latency	מחרוזת, מספר שלם
gcp.http_request {cacheLookup} http_request {cacheLookup}	httpRequest.cacheLookup	bool
gcp.http_request {cacheHit} http_request {cacheHit}	httpRequest.cacheHit	bool
gcp.http_request { cacheValidatedWithOriginServer} http_request { cacheValidatedWithOriginServer}	httpRequest.cacheValidatedWithOriginServer	bool
gcp.http_request {cacheFillBytes} http_request {cacheFillBytes}	httpRequest.cacheFillBytes	מחרוזת, מספר שלם
gcp.http_request {protocol} http_request {protocol}	httpRequest.protocol	מחרוזת

שדה התוויות

כדי לקבוע אילו תוויות לצרף לרשומה ביומן, המערכת מבצעת את הפעולות הבאות:

1. היא מסירה מרשומת היומן של OTLP את כל המאפיינים שמופו לשדות LogEntry ספציפיים.

   לדוגמה, נניח שיש מאפיינים שמצורפים לרשומת יומן:

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
       "code.file.path": "my-file.cc",
       "code.function.name: "my-func",
       "code.line.number": 123,
       "gcp.http_request": {
           "requestMethod": "GET",
           "requestUrl": "my-URL",
     },
   }
   

   אחרי שמסירים שדות שממופים לשדות ספציפיים של LogEntry, השדות הבאים נשארים:

   attributes: {
       "log_array_attr: ["value1", "value2"],
       "log_json_attr": {"json_key": "json_value"}
       "log-string-attr": "string",
   }
   

2. אם מאפיין מכיל מערך או רכיבי JSON, המערכת ממירה את הערך למחרוזת.

   לדוגמה, בדוגמה הבאה אפשר לראות איך המאפיין LogEntry מייצג את המאפיינים הקודמים:

   labels: {
       "log_array_attr": "[\"value1\",\"value2\"]",
       "log_json_attr": "{\"json_key\":\"json_value\"}",
       "log-string-attr": "string",
   }
   

   עומק הקינון המקסימלי של מאפיינים הוא חמש. כל תוכן עם קינון עמוק יותר נחתך.

שדה פעולה

ב-Google Cloud Observability ממופים מאפייני OTLP שרלוונטיים לפעולה לשדה operation של LogEntry. בקטעים הבאים מוסבר איך המערכת ממפה את מאפייני המשנה.

המאפיין gcp.operation חייב להכיל סוגי מפתח-ערך. אין תמיכה בשמות של מאפיינים שטוחים. בדוגמה הבאה מוצגת רשומה ביומן שלמאפיין gcp.operation שלה יש ארבעה צמדי מפתח/ערך:

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

בטבלה הבאה מוסבר איך Google Cloud Observability ממפה את gcp.operation ל-LogEntry:

OpenTelemetry LogRecord.attribute.operation צמד מפתח/ערך.	הערך מאוחסן בשדה הפעולה LogEntry הבא	סוג הפריט שאושר
id	id	מחרוזת
producer	httpRequest.requestUrl	מחרוזת
first	first	bool
last	last	bool

שדה Otel

בשדות בנתוני יומן OTLP שאין להם שדה מקביל ב- LogEntry, המערכת ממירה את סוגי הנתונים ואז מוסיפה את הנתונים המומרים לשדה otel. לדוגמה, בשדה otel מאוחסנים מאפיינים מהשדות resource, scope ו-entity.

המערכת משתמשת בכללים הבאים כדי להמיר את סוגי הנתונים של OpenTelemetry לסוגי protobuf Value:

סוג OpenTelemetry	סוג protobuf
string	string
boolean	bool
integer	double
float	double
Array	ListValues
KeyValueList	Struct

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

שדה מטען ייעודי (payload)

הערה: הגודל המקסימלי של LogEntry הוא ‎256 KiB. המגבלה הזו היא משוערת ומבוססת על גדלי נתונים פנימיים. במקרה הצורך, המערכת חותכת את השדה payload.

סוג הנתונים של השדה OTLP logRecord.body קובע את המבנה של מטען הייעודי (payload) LogEntry:

• string: המערכת מעתיקה את המחרוזת לשדה LogEntry.textPayload.

• ‫Array: המערכת יוצרת מחרוזת של רכיבי המערך תוך שמירה על שורות חדשות. אחר כך המערכת מעתיקה את המחרוזת לשדה LogEntry.textPayload.

• ‫KeyValueList: המערכת ממירה את הזוגות האלה ל-JSON ואז מאכלסת את השדה LogEntry.jsonPayload, עם ההגבלות הבאות:

  • כשרישום OTLP מכיל מפתחות מאפיינים כפולים, המערכת שומרת את המפתח הראשון ומשליכה מאפיינים עם מפתחות כפולים.
  • אם עומק ההיררכיה של זוג JSON גדול מחמש, המערכת חותכת את התוכן לעומק של חמש.

שדה מידת החומרה

בקטע הזה מוסבר איך Google Cloud Observability ממפה את שדות החומרה של OpenTelemetry לרמות החומרה של Cloud Logging. ב-OpenTelemetry מוגדרים מספר חוּמרה וטקסט חוּמרה. המספרים שמגדירים את רמת החומרה מופיעים בתוך התג logs.proto.

‫Google Cloud Observability קובע את רמת החומרה של הרישום ביומן מתוך מספר רמת החומרה של OpenTelemetry, אם הוא מוגדר. אחרת, נעשה שימוש בטקסט של רמת החומרה. אם אף אחת מההגדרות לא מוגדרת, רמת החומרה של הרישום מוגדרת ל-DEFAULT.

מספר חומרת הבעיה ב-OpenTelemetry Enum (value)	טקסט חומרת הבעיה ב-OpenTelemetry (הבדיקות לא תלויות-רישיות)	רמת החומרה ב-Cloud Logging Enum (value)
SEVERITY_NUMBER_UNSPECIFIED (0)	הערך 'default' לא מוגדר	DEFAULT (0)
SEVERITY_NUMBER_TRACE (1) SEVERITY_NUMBER_TRACE2 (2) SEVERITY_NUMBER_TRACE3 (3) SEVERITY_NUMBER_TRACE4 (4)	‫"trace" ‫"trace2" ‫"trace3" ‫"trace4"	DEBUG (100)
SEVERITY_NUMBER_DEBUG (5) SEVERITY_NUMBER_DEBUG2 (6) SEVERITY_NUMBER_DEBUG3 (7) SEVERITY_NUMBER_DEBUG4 (8)	‫"debug" "debug2" "debug3" "debug4"	DEBUG (100)
SEVERITY_NUMBER_INFO (9) SEVERITY_NUMBER_INFO2 (10)	‪"info" "info2"	INFO (200)
SEVERITY_NUMBER_INFO3 (11) SEVERITY_NUMBER_INFO4 (12)	‪"notice" "info3" "info4"	‫NOTICE (300)
SEVERITY_NUMBER_WARN (13) SEVERITY_NUMBER_WARN2 (14) SEVERITY_NUMBER_WARN3 (15) SEVERITY_NUMBER_WARN4 (16)	‫"warning" "warn" "warn2" "warn3" "warn4"	‫WARNING (400)
SEVERITY_NUMBER_ERROR (17) SEVERITY_NUMBER_ERROR2 (18) SEVERITY_NUMBER_ERROR3 (19) SEVERITY_NUMBER_ERROR4 (20)	‫"error" "error2" "error3" "error4"	ERROR (500)
SEVERITY_NUMBER_FATAL (21) SEVERITY_NUMBER_FATAL2 (22)	‫"critical" ‫"fatal" ‫"fatal2"	CRITICAL (600)
SEVERITY_NUMBER_FATAL3 (23)	‪"alert" "fatal3"	ALERT (700)
SEVERITY_NUMBER_FATAL4 (24)	‪"emergency" "fatal4"	EMERGENCY (800)

השדה SourceLocation

‫Google Cloud Observability ממפה את הקוד של OTLP ישירות לשדות LogEntry. המיפוי הזה אפשרי כי התכונות האלה של OpenTelemetry זהות מבחינה סמנטית למושגים של Cloud Logging.

OpenTelemetry LogRecord.attribute צמד מפתח/ערך.	הערך שמאוחסן בשדה הבא LogEntry (שמות מהפניה ל-HTTP)	סוג הפריט שאושר
code.file.path: Value	sourceLocation.file	מחרוזת
code.function.name: Value	sourceLocation.function	מחרוזת
code.function.number: Value	sourceLocation.line	מחרוזת, מספר שלם

מגבלות

בקטע הזה מתוארות מגבלות. בנוסף, מוסבר בה איך Google Cloud Observability מטפל בסוגים מסוימים של נתונים.

מגבלות

תיאור	ערך	הערות
מספר היומנים המקסימלי לכל בקשת OTLP	8192	המספר המקסימלי של logRecords במבנה OTLP resourceLogs. מגבלה.
הגודל המקסימלי של כל בקשה	‫5 MiB	מגבלה.
הגודל המקסימלי של LogEntry שנוצר מרשומה ביומן OTLP	‫256 KiB	במקרה הצורך, Cloud Logging חותך או משליך נתונים מרשומה ביומן OTLP. מגבלה.
האורך המקסימלי של מפתח מאפיין	‫512 B	מפתחות של תוויות גדולות מדי מקוצרים כשממירים את רשומת היומן של OTLP ל-LogEntry. מגבלה.
אורך מקסימלי של ערך מאפיין	‫64 KiB	ערכי תוויות גדולים מדי כשרשומת היומן של OTLP מומרת ל-LogEntry. מגבלה.
העומק המקסימלי של קינון מאפיינים	5	מאפיינים שחורגים מהמגבלה הזו מקוצרים כשממירים את רשומת היומן של OTLP ל-LogEntry.
מספר הבייטים המקסימלי של נתוני יומן שמועברים לדקה	‫2.4 GB באזורים הבאים: asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1. ‫300 MB לכל שאר האזורים.	מכסה.

התנהגות

• אם מוגדרים גם מספר החומרה וגם טקסט החומרה של OpenTelemetry, המערכת משתמשת במספר החומרה כדי לקבוע את רמת החומרה של Cloud Logging. אם רשומת OTLP לא מכילה פרטי חומרה, רמת החומרה ב-Cloud Logging מוגדרת ל-DEFAULT.

• כששיא OTLP מכיל מפתחות מאפיינים כפולים, המערכת שומרת את המפתח הראשון ומשליכה את המאפיינים עם המפתחות הכפולים.

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

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

הגדרת Google Cloud Observability לשימוש במיפויים של כלי הייצוא

‫Google Cloud Observability וה Google Cloud exporter ל-Cloud Logging משתמשים בכללים שונים כדי ליצור אובייקטים של LogEntry מנתוני יומן בפורמט OTLP. לדוגמה, Google Cloud Observability מאכלס את השדה otel, אבל האקספורטרים לא.

אם רוצים ש-Google Cloud Observability ישתמש באותם כללי מיפוי כמו כלי הייצוא, צריך לבצע את השינויים הבאים באפליקציות ששולחות רשומות של יומני OTLP אל Telemetry API:

1. מוסיפים את המאפיין gcp.use_legacy_mapping למשאב שנכלל בבקשה. מידע נוסף מופיע במאמר בנושא הוספה או מחיקה של מאפיינים.

   כשמגדירים את המאפיין הזה, קורים הדברים הבאים:

   1. השדה otel לא מאוכלס.

   2. מאפיינים שמתחילים ב-gcp נפסלים, למעט המקרים הבאים:

      • gcp.log.name
      • gcp.insert_id

      שני המאפיינים הקודמים ממופים לשדות LogEntry.

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

2. מוסיפים מעבדים לאוסף OTLP HTTP שקובעים את התוויות הבאות של היומן:

   • ‫instrumentation_scope: מוגדר ל-instrumentation_scope.name.
   • ‫instrumentation_version: מוגדר ל-instrumentation_scope.version.
   • ‫service.name: מוגדר ל-resource.attributes["service.name"].
   • ‫service.namespace: מוגדר ל-resource.attributes["service.namespace"].
   • ‫service.instance.id: מוגדר לערך resource.attributes["service.instance.id"].

   דוגמה מופיעה במאמר מעבר לייצוא OTLP: מעבדים.