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

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

ה-exporters ל-Cloud Logging ממירים נתוני יומנים בפורמט OTLP לאובייקטים של LogEntry. Google Cloud לאחר מכן הם שולחים את הנתונים האלה לפרויקט שלכם ב- 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 זמין בlogs.proto של OpenTelemetry.

איך מוגדרים השדות של 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. מידע נוסף זמין במאמר בנושא השדה 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 {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, המערכת ממירה את סוגי הנתונים ואז מוסיפה את הנתונים המומרים לשדה LogEntry.otel לדוגמה, בשדה otel מאוחסנים מאפיינים מהשדות resource, scope ו-entity.

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

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

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

שדה מטען ייעודי (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, המיפוי של Code ב-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 collector כדי להגדיר את התוויות הבאות של היומן:

    • ‫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: מעבדים.