Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

במאמר הזה מוסבר על שפת השאילתות של 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, והדקדוק של שפת השאילתות של Logging נראה כך:

הגבלה פשוטה: 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")
ביטוי מורכב של קשר ו/או קשר או: 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, או אם המטען הייעודי שלו, מכיל את הביטוי "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 סיביות. צריך להוסיף לתו המירכאות המוטמעות תו בריחה (backslash). ערכי מחרוזת צריכים להיות מוקפים במירכאות כפולות כדי להשתמש בתו בריחה (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 מקבלת שני פרמטרים: השדה LogEntry שיוצג והסוג של הנתונים שאליהם השדה יומר:

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

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

‫[FIELD]: השם של שדה ברשומה ביומן, כמו logName או jsonPayload.a_field.
‫[TYPE]: סוג הנתונים, כמו STRING, ‏ INT64, ‏ FLOAT64, ‏ BOOL.
- ‫TIMESTAMP או DURATION: יש סוגי נתונים שמציעים אפשרויות נוספות, כמו ציון אזור זמן של IANA Timezone Database לסוג הנתונים 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 מוגדר כמחרוזת. הביטוי הרגולרי לוכד את הערך של שדה השניות מהמחרוזת 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] תמיד מכיל את אותו ערך, אז הדגימה שמתקבלת מכילה את כל רשומות היומן או לא מכילה אף רשומה.

אם [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 ולטווחי כתובות 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 במטען הייעודי (payload):

אל תשתמשו בחיפוש גלובלי. סיבה אחת היא שכולם חיפושים של מחרוזת משנה:
```
   "Hello Kitty"   -- THIS CAUSES A SLOW SEARCH!
   
```
כן, כדאי להגביל את החיפוש לשדה אחד, גם אם צריך לשמור על חיפוש המחרוזת המשנית:
```
   textPayload:"Hello Kitty"
   
```
כן, כדאי להשתמש במבחן שוויון אם אתם יכולים:
```
   textPayload = "Hello Kitty"
   
```
כן, אם רשומות היומן כוללות מטען ייעודי מובנה, צריך להפנות לשדות ספציפיים במטען הייעודי.
```
   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.*"
```