שפת השאילתה לרישום ביומן

במאמר הזה מוסבר על שפת השאילתות של Logging, שמשמשת לשליחת שאילתות ולסינון נתונים ב-Cloud Logging.

מידע מפורט על העיצוב של שפת השאילתות של Logging זמין במפרטים רשמיים של Google API לסינון.

דוגמאות לשאילתות נפוצות שבהן אפשר להשתמש מופיעות במאמר דוגמאות לשאילתות באמצעות Logs Explorer.

סקירה כללית

אתם יכולים להשתמש בשפת השאילתות של Logging ב-Logs Explorer בGoogle Cloud מסוף, ב-Logging API או בממשק שורת הפקודה. אפשר להשתמש בשפת השאילתות של Logging כדי לשלוח שאילתות לנתונים ולכתוב מסננים כדי ליצור מאגרי נתונים ומדדים שמבוססים על יומנים.

שאילתה היא ביטוי בוליאני שמציין קבוצת משנה של כל רשומות היומן במשאב שנבחר Google Cloud , כמו פרויקט Google Cloud או תיקייה.

אפשר ליצור שאילתות על סמך LogEntry השדה המאונדקס באמצעות האופרטורים הלוגיים AND ו-OR. בדוגמאות הבאות נעשה שימוש בשדה resource.type, והדקדוק של שפת השאילתות של רישום ביומן נראה כך:

הגבלה פשוטה: resource.type = "k8s_cluster"
הגבלה מצטברת: resource.type = "k8s_cluster" AND severity = "ERROR"

הערה: כששאילתה מכילה כמה הצהרות, אפשר לציין איך ההצהרות האלה מצורפות או להסתמך על Cloud Logging שמוסיף באופן מרומז את ההגבלה המצטרפת, AND, בין ההצהרות. לדוגמה, נניח שתיבת דו-שיח של שאילתה או מסנן מכילה שתי הצהרות, resource.type = "gce_instance" ו-severity >= "ERROR". השאילתה בפועל היא resource.type = "gce_instance" AND severity >= "ERROR". ‫Cloud Logging תומך בהגבלות דיסג'נקטיביות, OR, ובהגבלות קוניונקטיביות, AND. כשמשתמשים בהצהרות OR, מומלץ לקבץ את הסעיפים באמצעות סוגריים.
הגבלה דיסג'נקטיבית: resource.type = "k8s_cluster" OR resource.type = "gce_instance"
- אפשרות נוספת: resource.type = ("k8s_cluster" OR "gce_instance")
ביטוי מורכב של קשרים לוגיים מסוג AND או OR: resource.type = "k8s_cluster" AND (severity = "ERROR" OR "error")

דוגמה לשאילתה:

resource.type = "gce_instance" AND
severity >= "ERROR" AND
NOT textPayload:robot

השאילתה הזו מתאימה לרשומות ביומן מ-Compute Engine עם ערכי חומרה של לפחות ERROR, ושדה textPayload שלהן לא מכיל את המחרוזת robot בשום מקום. השוואות של מחרוזות הן לא תלויות-רישיות. השמות resource, ‏severity ו-textPayload מוגדרים בסוג LogEntry.

סימון תחביר

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

שימו לב לנקודות הבאות:

אורך השאילתה לא יכול לחרוג מ-20,000 תווים.
שפת השאילתות של Logging לא תלויה באותיות רישיות, למעט ביטויים רגולריים ואופרטורים לוגיים, כמו AND ו-OR. צריך להשתמש באותיות רישיות באופרטורים לוגיים.

סיכום התחביר

אפשר לחשוב על התחביר של שפת השאילתות של Logging במונחים של שאילתות והשוואות.

שאילתה היא מחרוזת שמכילה ביטוי:

expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }

ההשוואה יכולה להיות ערך יחיד או ביטוי בוליאני:

"The cat in the hat"
resource.type = "k8s_cluster"

השורה הראשונה היא דוגמה להשוואה של ערך יחיד. הסוגים האלה של השוואות הם הגבלות גלובליות. כל שדה ברשומה ביומן מושווה לערך באמצעות האופרטור has באופן מרומז. בדוגמה הזו, אם שדה כלשהו ב-LogEntry, או המטען הייעודי (payload) שלו, מכיל את הביטוי The cat in the hat, ההשוואה תצליח.

השורה השנייה היא דוגמה להשוואה שהיא ביטוי בוליאני מהצורה [FIELD_NAME] [OP] [VALUE]. השוואה כוללת שלושה רכיבים:

‫[FIELD_NAME] הוא שדה ברשומה ביומן. לדוגמה, resource.type.
‫[OP] הוא אופרטור השוואה. לדוגמה, =.
‫[VALUE] הוא מספר, מחרוזת, פונקציה או ביטוי בסוגריים. לדוגמה, "k8s_cluster". במקום ערכי null ב-JSON, משתמשים ב-NULL_VALUE.

אופרטורים בוליאניים

האופרטורים הבוליאניים AND ו-OR הם אופרטורים של מעגל קצר. לאופרטור NOT יש את העדיפות הכי גבוהה, ואחריו OR ו-AND, לפי הסדר הזה. לדוגמה, שני הביטויים הבאים שקולים:

"a" OR NOT "b" AND NOT "c" OR "d"
("a" OR (NOT "b")) AND ((NOT "c") OR "d")

אפשר להשמיט את האופרטור AND בין ההשוואות. אפשר גם להחליף את האופרטור NOT באופרטור - (מינוס). לדוגמה, שתי השאילתות הבאות זהות:

a="b" AND c="d" AND NOT e="f"
a="b" c="d" -e="f"

במסמכי התיעוד האלה אנחנו תמיד משתמשים במונחים AND ו-NOT.

בכל המסננים, למעט המסננים שמשמשים את תצוגות היומן, אפשר להשתמש באופרטורים AND, OR ו-NOT. תצוגות יומן תומכות רק בפעולות AND ו-NOT.

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

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

השוואות

ההשוואות הן בפורמט הבא:

[FIELD_NAME] [OP] [VALUE]

השוואה כוללת שלושה רכיבים:

‫[FIELD_NAME]: מזהה נתיב השדה של שדה ברשומה ביומן. דוגמאות למזהים האלה:
```
resource.type
resource.labels.zone
resource.labels.project_id
insertId
jsonPayload.httpRequest.protocol
labels."compute.googleapis.com/resource_id"
```
אם רכיב של מזהה נתיב שדה מכיל תווים מיוחדים, צריך להוסיף לו מירכאות כפולות. לדוגמה, compute.googleapis.com/resource_id צריך להיות תחום במירכאות כפולות כי הוא מכיל קו נטוי /.

פרטים נוספים זמינים בקטע מזהים של נתיבי שדות במסמך הזה.

‫[OP]: אופרטור השוואה, אחד מהבאים:

=           -- equal
!=          -- not equal
> < >= <=   -- numeric ordering
:           -- "has" matches any substring in the log entry field
=~          -- regular expression search for a pattern
!~          -- regular expression search not for a pattern

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

‫[VALUE]: מספר, מחרוזת, פונקציה או ביטוי בסוגריים. מחרוזות משמשות לייצוג טקסט שרירותי, וגם ערכים בוליאניים, ערכי מנייה ומחרוזות של בייטים. הערך [VALUE] מומר לסוג השדה לפני ההשוואה. במקום ערכי null ב-JSON, משתמשים ב-NULL_VALUE.

כדי לסנן ערך null ב-JSON, משתמשים בתחביר הבא:

jsonPayload.field = NULL_VALUE      -- includes "field" with null value
NOT jsonPayload.field = NULL_VALUE  -- excludes "field" with null value

אם [VALUE] הוא שילוב בוליאני של השוואות בתוך סוגריים, שם השדה ואופרטור ההשוואה חלים על כל רכיב. לדוגמה:

jsonPayload.cat = ("longhair" OR "shorthair")
jsonPayload.animal : ("nice" AND "pet")

ההשוואה הראשונה בודקת אם הערך בשדה cat הוא longhair או shorthair. הבדיקה השנייה מוודאת שהערך בשדה animal מכיל את המילים nice ו-pet, בכל סדר.

מזהים של נתיבי שדות

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

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

httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
insertId
jsonPayload { variable }
labels { variable }
logName
metadata { systemLabels, userLabels }
operation{ id, producer, first, last }
protoPayload { @type, variable }
receiveTimestamp
resource { type, labels }
severity
sourceLocation: { file, line, function }
spanId
textPayload
timestamp
trace

דוגמאות למזהי נתיבי שדות שאפשר להשתמש בהם בהשוואות:

‫resource.type: אם המזהה הראשון של הנתיב הוא resource, המזהה הבא חייב להיות שדה בסוג MonitoredResource.
‫httpRequest.latency: אם המזהה הראשון של הנתיב הוא httpRequest, המזהה הבא חייב להיות שדה מהסוג HttpRequest.
labels.[KEY] אם מזהה הנתיב הראשון הוא labels, אז המזהה הבא, [KEY], חייב להיות אחד מהמפתחות בצמדי מפתח/ערך שמופיעים בשדה labels.
‫logName: מכיוון שהשדה logName הוא מחרוזת, אי אפשר להוסיף אחריו שמות של שדות משנה.

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

לדוגמה, jsonPayload הוא שדה struct, ולכן שם שדה שמוטמע בתוך jsonPayload כמו jsonPayload.end_time שונה מ-jsonPayload.endTime. באופן דומה, בשדה של מפה כמו labels, מפתח התווית labels.env_name שונה מ-labels.envName. לעומת זאת, כשמבצעים שאילתה בשדה הרגיל של מאגר אחסון לפרוטוקולים protoPayload, אין צורך לשמור על האותיות הרישיות.

למידע על סוגי השדות LogEntry, אפשר לעיין במאמר בנושא google.logging.v2.

תווים מיוחדים

אם שדה LogEntry מכיל תווים מיוחדים, צריך להוסיף מירכאות לשדה היומן. לדוגמה:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

רשימת התווים המיוחדים מופיעה בקטע string במאמר בנושא ערכים והמרות.

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

סוגי משאבים במעקב

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

לדוגמה, מכונות וירטואליות ב-Compute Engine משתמשות בסוג המשאב gce_instance, ומכונות וירטואליות ב-Amazon EC2 משתמשות בסוג המשאב aws_ec2_instance. בדוגמה הבאה אפשר לראות איך להגביל את השאילתות לשני סוגי המכונות הווירטואליות:

resource.type = ("gce_instance" OR "aws_ec2_instance")

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

חסרים שדות

אם משתמשים בשם שדה בשאילתה, והשדה הזה לא מופיע ברשומה ביומן, השדה חסר, לא מוגדר או מוגדר כברירת מחדל:

אם השדה הוא חלק ממטען הייעודי (payload) של רשומת היומן (jsonPayloadאו protoPayload), או אם הוא נמצא בתווית בקטע labels של רשומת היומן, השדה חסר. שימוש בשדה חסר לא יציג שגיאה, אבל כל ההשוואות שמשתמשות בשדות חסרים ייכשלו בלי להציג הודעה.

דוגמאות: jsonPayload.nearest_store, protoPayload.name.nickname
אם השדה מוגדר בסוג LogEntry, הוא מוגדר כברירת מחדל. ההשוואות מתבצעות כאילו השדה קיים והערך שלו הוא ערך ברירת המחדל.

דוגמאות: httpRequest.remoteIp, trace, operation.producer
אחרת, הערך בשדה הוא undefined, שזו שגיאה שמזוהה לפני השימוש בשאילתה.

דוגמאות: thud, operation.thud, textPayload.thud

כדי לבדוק אם שדה חסר או שמוגדר בו ערך ברירת מחדל קיים בלי לבדוק ערך מסוים בשדה, משתמשים בהשוואה :*. לדוגמה, ההשוואה הבאה מצליחה אם השדה operation.id מופיע באופן מפורש ברשומה ביומן:

operation.id:*

שימו לב להתנהגות של השאילתות הבאות:

כשמשתמשים באופרטור הבוליאני NOT בשדה חסר, התוצאה היא TRUE:
```
-- Returns TRUE
NOT missingField=foo
```
כשמשתמשים באופרטור ההשוואה 'לא שווה ל' != בשדה חסר, התוצאה היא FALSE:
```
-- Returns FALSE
missingField!=foo
```

סוגי אובייקטים ומערכים

כל שדה ברשומה ביומן יכול להכיל סקלר, אובייקט או מערך.

שדה סקלרי מאחסן ערך יחיד, כמו 174.4 או -1. string נחשב גם הוא סקלר. שדות שאפשר להמיר למחרוזת (או ממחרוזת), כמו Duration ו-Timestamp, הם גם סוגים סקלריים.
סוג אובייקט מאחסן אוסף של ערכים עם שמות, כמו ערך ה-JSON הבא:
```
{"age": 24, "height": 67}
```
אפשר להפנות לערך בתוך אובייקט. לדוגמה, אם jsonPayload.x הכיל את הערך הקודם, הערך של jsonPayload.x.age יהיה 24.
שדה מערך מאחסן רשימה של ערכים – כולם מאותו סוג. לדוגמה, שדה שמכיל מדידות יכול לכלול מערך של מספרים:
```
{8.5, 9, 6}
```
כשמבצעים השוואות ו-[FIELD_NAME] הוא שדה מערך, כל רכיב במערך מושווה ל-[VALUE] והתוצאות מצורפות באמצעות האופרטור OR. לדוגמה, אם jsonPayload.shoeSize הוא שדה מערך שמאחסן את {8.5, 9, 6}, ההשוואה:
```
jsonPayload.shoeSize < 7
```
שווה ל:
```
8.5 < 7 OR 9 < 7 OR 6 < 7
```
בדוגמה הזו, ההשוואה הכוללת מסתיימת בהצלחה.

ערכים והמרות

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

סוג השדה	ערך שאילתה מותר
`bool`	הערכים True או False, בכל אותיות הרישיות או הקטנות. דוגמאות: True,‏ true
`bytes`	מחרוזת שמכילה רצף כלשהו של בייטים. דוגמה: "\377\377".
`Duration`	מחרוזת שמכילה מספר עשרוני עם סימן, ואחריו אחת מהיחידות הבאות: ns,‏ us,‏ ms,‏ s,‏ m או h. הערכים של משך הזמן מדויקים עד לרמת הננו-שנייה. דוגמה: ‎3.2s.
`enum`	השם של ליטרל מסוג מנייה, לא תלוי אותיות רישיות. דוגמאות: ‫"WARNING", שהוא ערך מסוג LogSeverity.
`double`	כל מספר, עם או בלי סימן וחלק מעריכי, או מחרוזות הערכים המיוחדות NaN,‏ ‎-Infinity ו-Infinity (עם או בלי אותיות רישיות). דוגמאות: ‎"-3.2e-8",‏ "nan".
`intNN`	כל מספר שלם עם סימן שלא חורג מגודל הסוג. דוגמה: ‎-3.
`string`	כל מחרוזת שמכילה טקסט בקידוד UTF-8 או ASCII‏ 7 סיביות. צריך להוסיף לכל מרכאות מוטמעות לוכסן הפוך (escape). ערכי מחרוזות צריכים להיות מוקפים במירכאות כפולות כדי להשתמש בתו בריחה (escape) עם התווים המיוחדים הבאים: מחרוזות שמתחילות ב-`+` (פלוס), `-` (מינוס) או `.` (נקודה). מחרוזות עם `~` (טילדה), `=` (סימן שווה), `()` (סוגריים), `:` (נקודתיים), `>` (גדול מ-), `<` (קטן מ-), `,` (פסיק), `.` (נקודה) או `*` (כוכבית). כל רצף בריחה, למשל `\t`.
`Timestamp`	מחרוזת בפורמט RFC 3339 או ISO 8601. דוגמאות&colon; ‎"2024-08-02T15&colon;01&colon;23.045Z" (RFC 3339), "2024-08-02" (ISO 8601). בביטויי שאילתות, חותמות זמן בפורמט RFC 3339 יכולות לציין אזור זמן עם 'Z' או `±hh:mm`. חותמות הזמן מיוצגות ברמת דיוק של ננו-שנייה.
`uintNN`	כל מספר שלם לא חתום שלא חורג מגודל הסוג. דוגמה: "1234".

אם ניסיון המרה נכשל, ההשוואה נכשלת.

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

הסוגים intNN ו-uintNN מייצגים סוגים של מספרים שלמים בגדלים שונים, כמו int32 ו-uint64. כשכותבים ערך שצריך להמיר למספר שלם מסוג 64 ביט, כותבים את הערך כמחרוזת, למשל '9223372036854775807'.

סוגים של שדות ביומן

כך נקבע הסוג של שדה ביומן:

השדות ביומן שמוגדרים בסוג LogEntry ובסוג הרכיב הם שדות של מאגר אחסון לפרוטוקולים. לשדות של פרוטוקול למאגר נתונים זמני יש סוגים מפורשים.
שדות ביומן שמהווים חלק מאובייקטים מסוג protoPayload הם גם שדות של מאגר אחסון לפרוטוקולים, ויש להם סוגים מפורשים. השם של סוג מאגר אחסון לפרוטוקולים מאוחסן בשדה "@type" של protoPayload. מידע נוסף זמין במאמר בנושא מיפוי JSON.

כשמסננים לפי שדה שמשויך לסוג ההודעה Any, המערכת עוברת אוטומטית על השדה value. לכן, אל תכללו אותו בשאילתה. מידע נוסף זמין במאמר בנושא פתרון בעיות.
לשדות ביומן בתוך jsonPayload יש סוגים שמוסקים מהערך של השדה כשהרשומה ביומן מתקבלת:
- שדות שהערכים שלהם הם מספרים ללא מרכאות הם מסוג double.
- השדות שהערכים שלהם הם true או false הם מסוג bool.
- שדות שהערכים שלהם הם מחרוזות הם מסוג string.
מספרים שלמים ארוכים (64 ביט) מאוחסנים בשדות מחרוזת, כי אי אפשר לייצג אותם בדיוק כערכי double.
הסוגים Duration ו-Timestamp מזוהים רק בשדות של מאגר אחסון לפרוטוקולים. במקומות אחרים, הערכים האלה מאוחסנים בשדות מחרוזת.

תגובות

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

אפשר להשתמש בתגובות במקרים הבאים:

כדי להוסיף הערות למסננים מורכבים עם מידע על הפעולה של סעיף מסוים:

 -- All of our target users are emitted by Compute Engine instances.
 resource.type = "gce_instance"
 -- Looking for logs from "alex".
 jsonPayload.targetUser = "alex"

כדי להפעיל או להשבית סעיף במהירות, מוסיפים או מסירים את הקידומת של התגובה:

 resource.type = "gce_instance"
 -- jsonPayload.targetUser = "alex"
 jsonPayload.targetUser = "kiran"
 -- jsonPayload.targetUser = "sasha"

אופרטורים להשוואה

המשמעות של אופרטורי השוויון (=, !=) והשוני (<, <=, >, >=) תלויה בסוג הבסיסי של שם השדה בצד ימין.

כל הסוגים המספריים: השוויון והאי-שוויון הם בעלי המשמעות הרגילה עבור מספרים.
‫bool: שוויון פירושו אותו ערך בוליאני. אי השוויון מוגדר על ידי true>false.
‫enum: שוויון פירושו אותו ערך מספור. באי-שוויון נעשה שימוש בערכים המספריים הבסיסיים של מילולי הספירה.
‫Duration: שוויון פירושו משך זמן זהה. האי-שוויון מבוסס על משך הזמן. לדוגמה: כמשכי זמן, "1s">"999ms".
‫Timestamp: שוויון פירושו אותו רגע בזמן. אם a ו-b הם ערכים מסוג Timestamp, המשמעות של a < b היא ש-a מוקדם יותר בזמן מ-b.
‫bytes: האופרנדים מושווים בייט אחר בייט, משמאל לימין.
‫string: ההשוואות לא תלויות באותיות רישיות. ספציפית, שני האופרנדים עוברים קודם נורמליזציה באמצעות נורמליזציה של Unicode מסוג NFKC_CF, ואז מתבצעות השוואות לקסיקוגרפיות. עם זאת, חיפושים של ביטויים רגולריים לא מנורמלים. מידע נוסף על חיפוש רשומות ביומן באמצעות ביטויים רגולריים זמין במאמר בנושא שימוש בביטויים רגולריים.

אופרטור המחרוזת המשנית (:) רלוונטי ל-string ול-bytes, והוא מטופל כמו שוויון, אלא שהאופרנד הימני צריך להיות שווה רק לחלק כלשהו מהשדה הימני. התאמות של מחרוזות משנה בשדות באינדקס לא מנצלות את היתרונות של אינדקסים של יומנים.

הגבלות גלובליות

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

השאילתה הפשוטה ביותר שנכתבת במונחים של הגבלה גלובלית היא ערך יחיד:

"The Cat in The Hat"

אפשר לשלב הגבלות גלובליות באמצעות האופרטורים AND ו-OR כדי ליצור שאילתה מעניינת יותר. לדוגמה, אם רוצים להציג את כל הרשומות ביומן שיש להן שדה שמכיל cat ושדה שמכיל hat או bat, כותבים את השאילתה כך:

("cat" AND ("hat" OR "bat"))

במקרה הזה, יש שלוש הגבלות גלובליות: cat, ‏ hat ו-bat. ההגבלות הגלובליות האלה מוחלות בנפרד והתוצאות משולבות, בדיוק כמו אם הביטוי היה נכתב ללא סוגריים.

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

logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log" AND
"GCE_OPERATION_DONE"

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

פונקציות

אפשר להשתמש בפונקציות מובנות כהגבלות גלובליות בשאילתות:

function = identifier ( [ argument { , argument } ] )

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

log_id

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

הארגומנט היחיד של הפונקציה log_id הוא מזהה יומן שלא עבר קידוד כתובת URL:

log_id(non-URL-encoded log ID)

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

log_id("cloudaudit.googleapis.com/activity")

בשאילתה הקודמת, הארגומנט מורכב רק מתווים אלפאנומריים ומתווים מיוחדים (/, _, -, .).

העברה (cast)

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

cast([FIELD], [TYPE][, OPTION])

הפרמטרים של הביטוי הקודם מוגדרים כך:

‫[FIELD]: השם של שדה ברשומה ביומן, כמו logName או jsonPayload.a_field.
‫[TYPE]: סוג הנתונים, כמו STRING, ‏ INT64, ‏ FLOAT64, ‏ BOOL.
- ‫TIMESTAMP או DURATION: יש סוגי נתונים שמציעים אפשרויות נוספות, כמו ציון אזור זמן של מסד הנתונים של אזורי הזמן של IANA עבור סוג הנתונים TIMESTAMP.

לדוגמה, השאילתה הבאה מבצעת המרה של השדה timestamp ל-STRING ומציינת את אזור הזמן America/New_York:

cast(timestamp, STRING, TIME_ZONE("America/New_York")) =~ "^2025-04-02.*"

regexp_extract

משתמשים בפונקציה regexp_extract כדי למצוא את המחרוזת המשנית הראשונה שתואמת לביטוי רגולרי:

REGEXP_EXTRACT([FIELD], [REGULAR_EXPRESSION])

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

‫[FIELD]: השם של שדה ברשומה ביומן, כמו logName או jsonPayload.a_field.
‫[REGULAR_EXPRESSION]: הביטוי הרגולרי RE2 שצריך להכיל קבוצה לחילוץ אחת ((...)). אם נדרש קיבוץ נוסף לביטוי הרגולרי, צריך להשתמש בקבוצה שלא מבצעת לכידה (?:...). אם יש כמה קבוצות לחילוץ או אם אין קבוצות לחילוץ, תופיע שגיאה.

אפשר לשרשר את הפונקציות cast ו-regexp_extract:

CAST(REGEXP_EXTRACT(CAST(timestamp, STRING), "\\d+:\\d+:(\\d+)"), INT64) < 30

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

מקור

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

הפונקציה source לא תואמת למשאבי צאצא. לדוגמה, שימוש ב-source(folders/folder_123) יתאים ליומנים מהמשאב folder_123, ולא ליומנים ממשאבי הפרויקט Google Cloud בתוך folder_123.

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

source(RESOURCE_TYPE/RESOURCE_ID)

משאב	שאילתה לדוגמה
ארגון	`source(organizations/ORGANIZATION_ID)`
תיקייה	`source(folders/FOLDER_ID)`
Google Cloud פרויקטים	`source(projects/PROJECT_ID)`

דוגמה

הפונקציה sample בוחרת חלק ממספר הרשומות הכולל ביומן:

sample([FIELD], [FRACTION])

‫[FIELD]: השם של שדה ברשומה ביומן, למשל logName או jsonPayload.a_field. הערך של השדה קובע אם רשומת היומן נכללת במדגם. סוג השדה חייב להיות מחרוזת או ערך מספרי. הגדרה של [FIELD] ל-insertId היא בחירה טובה, כי לכל רשומה ביומן יש ערך שונה בשדה הזה.

‫[FRACTION] הוא החלק היחסי של רשומות ביומן שיש להן ערכים בשביל [FIELD] שצריך לכלול. זהו מספר שגדול מ-0.0 ולא גדול מ-1.0. לדוגמה, אם מציינים 0.01, הדגימה מכילה בערך אחוז אחד מכל הרשומות ביומן שיש להן ערכים עבור [FIELD]. אם הערך של [FRACTION] הוא 1, כל רשומות היומן עם ערכים של [FIELD] נבחרות.

דוגמה: השאילתה הבאה מחזירה 25 אחוז מהרשומות ביומן syslog:

logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)

פרטים: אלגוריתם דטרמיניסטי שמבוסס על גיבוב משמש כדי לקבוע אם רשומה ביומן נכללת בדגימה או לא. רמת הדיוק של הדגימה שמתקבלת תלויה בהתפלגות של הערכים שעברו גיבוב. אם הערכים המגובבים לא מפוזרים באופן אחיד, יכול להיות שהמדגם שיתקבל יהיה מוטה. במקרה הגרוע ביותר, כש-[FIELD] תמיד מכיל את אותו ערך, המדגם שמתקבל מכיל את [FRACTION] של כל רשומות היומן או שלא מכיל רשומות יומן בכלל.

אם הסמל [FIELD] מופיע ברשומה ביומן, אז:

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

אם הסמל [FIELD] לא מופיע ברשומה ביומן, אז:

אם [FIELD] הוא חלק מהמטען הייעודי (payload) של רשומת היומן או מהקטעים labels, רשומת היומן לא תיבחר לדוגמה, גם אם [FRACTION] הוא 1.
אחרת, רשומת היומן מטופלת כאילו [FIELD] נמצאת ברשומת היומן והערך של [FIELD] הוא ערך ברירת המחדל. ערך ברירת המחדל נקבע לפי סוג LogEntry. מידע נוסף על שדות חסרים ושדות עם ערכי ברירת מחדל זמין בקטע שדות חסרים במאמר הזה.

כדי להחריג מהדגימה רשומות ביומן עם שדות שהוגדרו להם ערכי ברירת מחדל, משתמשים באופרטור field-exists, ‏ :*. השאילתה הבאה יוצרת מדגם של אחוז אחד של רשומות ביומן שבהן סופק ערך באופן מפורש עבור field:

field:* AND sample(field, 0.01)

ip_in_net

הפונקציה ip_in_net קובעת אם כתובת IP ברשומה ביומן כלולה בתת-רשת. אפשר להשתמש בזה כדי לדעת אם הבקשה מגיעה ממקור פנימי או חיצוני. לדוגמה:

ip_in_net([FIELD], [SUBNET])

‫[FIELD] הוא שדה עם ערך מחרוזת ברשומה ביומן, שמכיל כתובת IP או טווח. השדה יכול להיות חוזר, ובמקרה כזה רק אחד מהשדות החוזרים צריך להכיל כתובת או טווח שנכללים ברשת המשנה.

‫[SUBNET] הוא קבוע מחרוזת לכתובת IP או לטווח כתובות. אם [SUBNET] לא מייצג כתובת או טווח IP חוקיים, כמו שמתואר בהמשך הקטע הזה, זו שגיאה.

דוגמה: השאילתה הבאה בודקת כתובת IP במטען הייעודי (payload) של רשומות יומן מהיומן my_log:

logName = "projects/my_project/logs/my_log" AND
ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")

פרטים: אם הערך [FIELD] חסר ברשומה ביומן, אם הוא מוגדר כברירת מחדל או אם הוא לא מכיל כתובת או טווח IP חוקיים, הפונקציה מחזירה False. מידע נוסף על שדות חסרים ושדות עם ערכי ברירת מחדל מופיע בקטע שדות חסרים במאמר הזה.

בהמשך מופיעות דוגמאות לכתובות ולטווחי IP נתמכים:

‫IPv4: ‏10.1.2.3
רשת משנה של IPv4: ‏ 10.1.2.0/24
‫CIDR IPv6: 1234:5678:90ab:cdef:1234:5678:90ab:cdef
תת-רשת CIDR IPv6: ‏ 1:2::/48

פונקציית `SEARCH`

אפשר להשתמש בפונקציה המובנית SEARCH כדי למצוא מחרוזות בנתוני היומן:

SEARCH([query])
SEARCH([field], [query])

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

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

כשמעבדים את הפונקציה SEARCH, מחרוזת query מעובדת על ידי מנתח טקסט שמפצל את המחרוזת לטוקנים. ב-Cloud Logging תמיד מתבצעות השוואות לא תלויות-רישיות, גם עבור טוקנים שמוקפים בגרשיים הפוכים. ההתנהגות הזו שונה מזו של BigQuery, ששומר על האותיות הרישיות והקטנות בטוקנים שמוקפים בגרשיים הפוכים. מידע על כללי הניתוח זמין במסמך BigQuery בנושא כללי ניתוח טקסט.

כשיוצרים חיפוש, כדאי לקחת בחשבון את הנקודות הבאות:

הטוקנים לא תלויי-רישיות. הפונקציות הבאות מפיקות את אותן תוצאות:
```
SEARCH("world")
SEARCH("World")
```
הפונקציות הקודמות מתאימות לרשומה ביומן אם שדה יחיד מכיל את הטוקן world. הפונקציה SEARCH מבצעת התאמות מדויקות ולא התאמות של מחרוזות משנה, ולכן הפונקציות הקודמות לא מתאימות לשדה שהערך שלו הוא worldwide.
אם לא מציינים את השדה לחיפוש, הפונקציה SEARCH מתאימה לרשומה ביומן אם הרשומה מכילה את כל האסימונים. עם זאת, סדר הטוקנים לא משנה והטוקנים לא חייבים להופיע באותו שדה ברשומת היומן.

הפונקציות הבאות מפיקות את אותן תוצאות, והן תואמות לרשומה ביומן שמכילה את הטוקנים hello ו-world:
```
SEARCH("hello world")
SEARCH("World hello")
```
אם מציינים את השדה לחיפוש, הפונקציה SEARCH מחפשת רק בשדה הזה. התאמה מתרחשת כשהשדה הזה מכיל את כל האסימונים, אבל הסדר של האסימונים לא משנה.

הפונקציות הבאות יוצרות התאמה רק אם השדה textPayload מכיל את האסימונים hello ו-world:
```
SEARCH(textPayload, "hello world")
```
כדי להגדיר התאמה מדויקת לביטוי שלא תלויה באותיות רישיות, מקיפים את הביטוי בגרשיים הפוכים. לדוגמה, הפונקציות הבאות מתאימות למחרוזת hello world:
```
SEARCH("`hello world`")
SEARCH("`Hello World`")
SEARCH("`HELLO WORLD`")
```
הפונקציות הבאות משתמשות בגרש הפוך, ולכן הן מפיקות תוצאות שונות:
```
SEARCH("`hello world`")
SEARCH("`world hello`")
```

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

חיפוש לפי זמן

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

timestamp >= "2023-11-29T23:00:00Z"
timestamp <= "2023-11-29T23:30:00Z"

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

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

timestamp > "2023-11-29"

שימוש בביטויים רגולריים

אפשר להשתמש בביטויים רגולריים כדי ליצור שאילתות ומסננים עבור מאגרי נתונים, מדדים ובכל מקום שבו נעשה שימוש במסנני יומנים. לדוגמה, אפשר להשתמש בביטויים רגולריים בLogs Explorer וב-Google Cloud CLI.

ביטוי רגולרי הוא רצף של תווים שמגדיר חיפוש. שפת השאילתות של Logging משתמשת בתחביר RE2. הסבר מלא על התחביר של RE2 זמין ב-RE2 wiki ב-GitHub.

מאפיינים של שאילתות עם ביטויים רגולריים:

אפשר להתאים ביטוי רגולרי רק לשדות מסוג מחרוזת.
לא מתבצע נירמול של המחרוזת. לדוגמה, kubernetes לא נחשב זהה ל-KUBERNETES. מידע נוסף זמין בקטע אופרטורים להשוואה.
השאילתות הן תלויות אותיות רישיות (case-sensitive) ולא מוצמדות כברירת מחדל.
אפשר להשתמש באופרטורים בוליאניים בין כמה ביטויים רגולריים בצד שמאל של אופרטור ההשוואה של הביטוי הרגולרי, =~ ו-!~.

שאילתת ביטוי רגולרי בנויה באופן הבא:

התאמת דפוס:

jsonPayload.message =~ "regular expression pattern"

לא תואם לתבנית:

jsonPayload.message !~ "regular expression pattern"

השינויים =~ ו-!~ הופכים את השאילתה לשאילתת ביטוי רגולרי, והתבנית שמנסים להתאים חייבת להיות בתוך מירכאות כפולות. כדי לשלוח שאילתה לגבי דפוסים שמכילים מירכאות כפולות, צריך להשתמש בתו בריחה (escape) באמצעות קו נטוי הפוך.

הערה: שאילתות של ביטויים רגולריים עשויות להיות מהירות יותר משאילתות טקסט רגילות. לדוגמה, אם רוצים לחפש רשומות ביומן שמכילות גם את foo וגם את bar, יכול להיות שיהיה מהר יותר להשתמש בשאילתת הביטוי הרגולרי jsonPayload.message =~ "foo.*bar|bar.*foo" מאשר בשאילתת המחרוזת המשנית jsonPayload.message : ("foo" AND "bar").

דוגמאות לשאילתות ביומני נתונים באמצעות ביטויים רגולריים

סוג השאילתה	דוגמה
שאילתה רגילה	`sourceLocation.file =~ "foo"`
שאילתה עם חיפוש לא תלוי-רישיות	`labels.subnetwork_name =~ "(?i)foo"`
שאילתה שמכילה מירכאות	`jsonPayload.message =~ "field1=\"bar.*\""`
שאילתה באמצעות ערך בוליאני `or`	`labels.pod_name =~ "(foo\|bar)"`
שליחת שאילתות באמצעות עוגנים	`logName =~ "/my%2Flog$"`
השאילתה לא תואמת לתבנית	`labels.pod_name !~ "foo"`
שליחת שאילתות באמצעות אופרטור בוליאני	`labels.env =~ ("^prod.server" OR "^staging.server")`
שאילתה שמתחילה בערך	`logName =~ "^foo"`
שאילתה שמסתיימת בערך	`logName =~ "foo$"`

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

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

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

שימוש בשדות עם אינדקס

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

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

אופטימיזציה של השאילתות

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

דוגמה: שימוש בפונקציה `SEARCH`

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

דוגמה: שימוש בשם היומן הנכון

מציינים את היומן שמכיל את רשומות היומן שמעניינות אתכם. כדי לדעת מה השם האמיתי של היומן, צריך לבדוק את אחת הרשומות ביומן. לדוגמה, בחלונית התוצאות אפשר לראות שהקטע Compute Engine מכיל יומן בשם activity. בבדיקה מדוקדקת יותר של הרשומות ביומן הביקורת Admin Activity, השם של היומן הוא למעשה cloudaudit.googleapis.com/activity.

ההשוואה הבאה שגויה. הוא לא תואם לשום דבר כי הוא משתמש בשם היומן הלא נכון:

logName = "projects/my-project-id/logs/activity"   -- WRONG!

ההשוואה הבאה נכונה. הוא בוחר רשומות ביומן מתוך רשומות ביומן הביקורת Admin Activity. צריך להשתמש בקידוד URL לשם היומן, כמו שמוצג:

logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

דוגמה: בחירת הרשומות הנכונות ביומן

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

resource.type = "gce_instance" AND
resource.labels.instance_id = "6731710280662790612"
logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

דוגמה: בחירת תקופת הזמן הנכונה

מציינים את תקופת הזמן שרוצים לחפש בה. דרך מהירה לקבוע חותמות זמן שימושיות בפורמט RFC 3339 היא באמצעות הפקודה date של GNU/Linux:

$ date --rfc-3339=s
2023-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2023-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2023-06-27 12:40:00-04:00

משתמשים בערכים של חותמות הזמן האלה בשאילתות הבאות. כדי ליצור חותמת זמן שמתאימה ל-Logging, מחליפים את הרווח בין התאריך לשעה באות T.

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

timestamp >= "2023-06-27T14:40:00-04:00"

דוגמה נוספת: כדי לחפש הודעות שנשלחו לפני שלוש עד חמש שעות:

timestamp >= "2023-06-27T12:40:00-04:00" AND
timestamp <= "2023-06-27T14:40:00-04:00"

צמצום ההגבלות הדיסג'נקטיביות

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

לדוגמה, השאילתה SEARCH("foo") AND SEARCH("bar") משתמשת באינדקסים ולכן היא תהיה מהירה יותר מהשאילתה SEARCH("foo") OR SEARCH("bar").

מזעור החיפושים הגלובליים והחיפושים של מחרוזות משנה

אל תתפתו להשתמש בקיצורי דרך כשמקלידים שאילתות.

דוגמה: אל תשתמשו בחיפושים גלובליים

אם מחפשים רשומה ביומן עם הערך Hello Kitty במטען הייעודי:

אל תשתמשו בחיפוש גלובלי. הסיבה הראשונה היא שכל החיפושים הם חיפושים של מחרוזת משנה:
```
   "Hello Kitty"   -- THIS CAUSES A SLOW SEARCH!
   
```
כן להגביל את החיפוש לשדה יחיד, גם אם צריך לשמור על חיפוש מחרוזת המשנה:
```
   textPayload:"Hello Kitty"
   
```
כן כדאי להשתמש במבחן שוויון אם אתם יכולים:
```
   textPayload = "Hello Kitty"
   
```
כן, אם לרשומות ביומן יש מטען ייעודי (payload) מובנה, צריך להפנות לשדות ספציפיים במטען הייעודי.
```
   jsonPayload.my_favorite_cat = "Hello Kitty"
   
```

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

   logName = "projects/my-project_id/logs/somelog" AND
   jsonPayload.my_favorite_cat = "Hello Kitty"

כן משתמשים בפונקציה SEARCH ומציינים את הטקסט המלא שצריך להתאים. הפונקציה SEARCH מבצעת התאמה לא תלוית-רישיות:
```
  SEARCH("Hello Kitty")
  
```
אל תשתמשו בפונקציה SEARCH ותציינו טקסט חלקי. לדוגמה, הפונקציה הבאה לא מתאימה ל-"Hello Kitty".
```
  SEARCH("Hello Kit")
  
```

דוגמאות לחיפושים

רשומות היומן שמוצגות הן אלה שתואמות לשאילתה. אם התפריט Jump to time מכיל ערך, התצוגה תגולל לנקודת הזמן הזו. הנה כמה דוגמאות לשאילתות:

resource.type=k8s_cluster

מוצא את כל רשומות היומן של Google Kubernetes Engine. רשימה של סוגי המשאבים זמינה במאמר רשימת משאבים במעקב.

בזמן ההקלדה, בחלונית השאילתה מוצעות השלמות לשדות כמו resource.type.

resource.type=k8s_cluster AND logName:request_log

מחפש רשומות ביומן של אשכולות Google Kubernetes Engine משמות יומנים שמכילים את request_log. חשוב לשים לב לכמה דברים:

האופרטור = מציין שוויון מדויק. סוג המשאב צריך להיות בדיוק "k8s_cluster", למעט אותיות רישיות או קטנות.
האופרטור : פירושו 'יש'. השדה logName חייב להכיל את הערך request_log, בכל אותיות הרישיות או הקטנות. השם בפועל של היומן ארוך הרבה יותר. השימוש ב-: עלול להאט את החיפושים.
ההשוואות מחוברות באמצעות AND. אפשר להשתמש גם ב-OR, אבל אם לא מציינים את האופרטור, המערכת מניחה שמשתמשים ב-AND.

resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

הפונקציה מוצאת רשומות ביומן עם אחד משני סוגי משאבים: מכונת VM של Compute Engine או מכונת VM של AWS EC2. ערכי היומן צריכים להיות severity לפחות ERROR, שזה שווה לבחירה באפשרות ERROR בתפריט החומרה של ממשק השאילתות.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

הפקודה מוצאת את כל הרשומות ביומן הביקורת Admin Activity בפרויקט [PROJECT_ID]. כל יומני הביקורת משתמשים באותו שם יומן בפרויקט, אבל יש להם סוגי משאבים שונים. מזהה היומן, cloudaudit.googleapis.com/activity, חייב להיות בקידוד URL בשם היומן. שימוש בשוויון בהשוואה מזרז את החיפוש. מידע נוסף זמין במאמר הסבר על יומני הביקורת.

unicorn

מוצא רשומות ביומן שמכילות את המחרוזת unicorn בכל שדה, ללא הבדל בין אותיות קטנות לאותיות גדולות. מונח חיפוש שלא משמש להשוואה בין שדות הוא שאילתה של 'כל השדות'.

unicorn phoenix

מחפש רשומות ביומן שמכילות את הערך unicorn בשדה כלשהו ואת הערך phoenix בשדה כלשהו.

textPayload:(unicorn phoenix)

חיפוש רשומות ביומן שבהן השדה textPayload מכיל את המילים unicorn ו-phoenix בכל סדר שהוא – האופרטור AND מרומז בין שתי המילים.

textPayload:"unicorn phoenix"

מחפש רשומות ביומן שהשדה textPayload שלהן מכיל את המחרוזת "unicorn phoenix".

NOT textPayload: "unicorn phoenix"

מוצאת רשומות ביומן שבהן השדה textPayload לא מכיל את המחרוזת "unicorn phoenix". סוג השאילתה הזה מצמצם את כמות רשומות היומן הלא רצויות.

timestamp >= "2023-11-29T23:00:00Z" timestamp <= "2023-11-29T23:30:00Z"

חיפוש רשומות ביומן בפרק זמן של 30 דקות.

פתרון בעיות

בעיות בתחביר

אם נתקלתם בבעיות בביטויים של השאילתות, כדאי לבדוק את הדברים הבאים:

השאילתה שלך עומדת בכללי התחביר, עם סוגריים וגרשיים תואמים.
שמות השדות ברשומה ביומן מאויתים בצורה נכונה.
פעולות בוליאניות מופיעות באותיות רישיות (AND, ‏ OR, ‏ NOT).
חשוב לוודא שאתם משתמשים ב-NULL_VALUE כדי לייצג ערכי JSON null.
יש להוסיף סוגריים לביטויים בוליאניים כמגבלות גלובליות או כצד ימין של השוואות, לשם הבהרה. לדוגמה, שתי השאילתות הבאות נראות זהות, אבל הן לא:
```
insertId = "ABC-1" OR "ABC-2"  -- ERROR!?
insertId = ("ABC-1" OR "ABC-2")
```
טקסט שלא מוקף במירכאות לא יכול להכיל תווים מיוחדים. אם אתם לא בטוחים, הוסיפו מרכאות כפולות. לדוגמה, בהשוואה הבאה, ההשוואה הראשונה לא חוקית בגלל אופרטור המחרוזת המשובץ (:). ההשוואה חייבת להיכתב עם מרכאות:
```
insertId = abc:def  -- ILLEGAL!
insertId = "abc:def"
```
הערה: אם משתמשים בסרגל החיפוש ולא מקיפים את מונחי החיפוש במירכאות כפולות, נעשה שימוש בפונקציה SEARCH. הפונקציה SEARCH מבצעת חיפוש לאורך גבולות הטוקנים. לדוגמה, אם מזינים world בסרגל החיפוש, המערכת של Logging מריצה את השאילתה SEARCH("world"). השאילתה הקודמת תואמת ל-world אבל לא ל-worlds.
ב-Google Cloud CLI צריך להוסיף מרכאות כפולות לשאילתה. כדי להשתמש במירכאות לביטול המשמעות של תווים מיוחדים באמצעות הפקודה gcloud logging, צריך להוסיף גרשיים מסביב לשאילתה כולה:
```
gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
```
כשמסננים לפי שדה שמשויך לסוג ההודעה Any, המערכת עוברת אוטומטית על השדה value. לכן, אין לכלול את value בשאילתה.

לדוגמה, השדה Status בהודעה AuditLog מכיל שדה details מסוג google.protobuf.Any. כדי לשלוח שאילתה לשדה details, משמיטים את השדה value כשמציינים את המסנן:
- מומלץ
```
protoPayload.status.details.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"
```
- לא מומלץ
```
protoPayload.status.details.value.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"
```