שיפור זמן השאילתה באמצעות הוספה לאינדקס בהתאמה אישית

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

סקירה כללית

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

כדי לשפר את ביצועי השאילתות, מערכת Logging מוסיפה באופן אוטומטי לאינדקס את השדות הבאים של LogEntry:

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

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

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

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

לפני שמתחילים

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

  • מוודאים שמשתמשים בגרסה העדכנית של ה-CLI של gcloud. מידע נוסף מופיע במאמר ניהול רכיבי Google Cloud CLI.

  • מוודאים שיש לכם תפקיד בניהול זהויות והרשאות גישה (IAM) עם ההרשאות הבאות:

    למידע נוסף על התפקידים האלה, ראו בקרת גישה באמצעות IAM.

הגדרת האינדקס בהתאמה אישית

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

  • ‫fieldPath: מתאר את הנתיב הספציפי לשדה LogEntry ברשומות ביומן. לדוגמה, jsonPayload.req_status.
  • ‫type: מציין אם השדה הוא מסוג מחרוזת או מספר שלם. הערכים האפשריים הם INDEX_TYPE_STRING ו-INDEX_TYPE_INTEGER.

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

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

gcloud

משתמשים בפקודה gcloud logging buckets create ומגדירים את הדגל --index:

gcloud logging buckets create BUCKET_NAME \
--location=LOCATION \
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

פקודה לדוגמה:

gcloud logging buckets create int_index_test_bucket \
--location=global \
--description="Bucket with integer index" \
--index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

כדי ליצור קטגוריה, משתמשים ב-projects.locations.buckets.create ב-Logging API. מכינים את הארגומנטים לשיטה באופן הבא:

  1. מגדירים את הפרמטר parent בתור המשאב שבו רוצים ליצור את הקטגוריה: projects/PROJECT_ID/locations/LOCATION

    המשתנה LOCATION מתייחס לאזור שבו רוצים לאחסן את היומנים.

    לדוגמה, אם רוצים ליצור קטגוריה לפרויקט my-project באזור asia-east2, הפרמטר parent ייראה כך: projects/my-project/locations/asia-east2

  2. מגדירים את הפרמטר bucketId, לדוגמה my-bucket.

  3. בגוף הבקשה של LogBucket, מגדירים את האובייקט IndexConfig כדי ליצור את האינדקס בהתאמה אישית.

  4. מפעילים את projects.locations.buckets.create כדי ליצור את הקטגוריה.

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

gcloud

משתמשים בפקודה gcloud logging buckets update ומגדירים את הדגל --add-index:

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

פקודה לדוגמה:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

משתמשים ב-projects.locations.buckets.patch ב-Logging API. בגוף הבקשה LogBucket, מגדירים את האובייקט IndexConfig כך שיכלול את השדות LogEntry שרוצים להוסיף לאינדקס.

מחיקת שדה מותאם אישית שנוסף לאינדקס

כדי למחוק שדה מהאינדקס בהתאמה אישית של קטגוריה:

gcloud

משתמשים בפקודה gcloud logging buckets update ומגדירים את הדגל --remove-indexes :

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--remove-indexes=INDEX_FIELD_NAME

פקודה לדוגמה:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status

API

משתמשים ב-projects.locations.buckets.patch ב-Logging API. בגוף הבקשה LogBucket, מסירים את השדות LogEntry מהאובייקט IndexConfig.

עדכון סוג הנתונים של השדה המותאם אישית שנוסף לאינדקס

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

gcloud

משתמשים בפקודה gcloud logging buckets update ומגדירים את הדגל --update-index:

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

פקודה לדוגמה:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

משתמשים ב-projects.locations.buckets.patch ב-Logging API. בגוף הבקשה LogBucket, מעדכנים את האובייקט IndexConfig כדי לספק את סוג הנתונים הנכון לשדה LogEntry.

עדכון הנתיב של שדה מותאם אישית שנוסף לאינדקס

כדי לתקן את נתיב השדה של שדה מותאם אישית שנוסף לאינדקס:

gcloud

משתמשים בפקודה gcloud logging buckets update ומגדירים את הדגלים --remove-indexes ו---update-index:

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--remove-indexes=OLD_INDEX_FIELD_NAME \
--update-index=fieldPath=NEW_INDEX_FIELD_NAME,type=INDEX_TYPE

פקודה לדוגמה:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status_old_path \
--add-index=fieldPath=jsonPayload.req_status_new_path,type=INDEX_TYPE_INTEGER

API

משתמשים ב-projects.locations.buckets.patch ב-Logging API. בגוף הבקשה LogBucket, מעדכנים את האובייקט IndexConfig כדי לספק את נתיב השדה הנכון לשדה LogEntry.

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

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

gcloud

משתמשים בפקודה gcloud logging buckets describe:

gcloud logging buckets describe BUCKET_NAME \
--location=LOCATION

פקודה לדוגמה:

gcloud logging buckets describe indexed-bucket \
--location global

API

משתמשים ב-projects.locations.buckets.get ב-Logging API.

ניקוי שדות מותאמים אישית שנוספו לאינדקס

כדי להסיר את כל השדות המותאמים אישית שנוספו לאינדקס מקטגוריה:

gcloud

משתמשים בפקודה gcloud logging buckets update ומוסיפים את הדגל --clear-indexes:

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--clear-indexes

פקודה לדוגמה:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--clear-indexes

API

משתמשים ב-projects.locations.buckets.patch ב-Logging API. בגוף הבקשה LogBucket, מוחקים את האובייקט IndexConfig.

שליחת שאילתות וצפייה בנתונים שנוספו לאינדקס

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

gcloud

כדי לקרוא את הרשומות ביומן מתיקיית יומנים, משתמשים בפקודה gcloud logging read ומוסיפים LOG_FILTER כדי לכלול את הנתונים שנוספו לאינדקס:

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=LOG_VIEW_ID

API

כדי לקרוא יומנים ממאגר יומנים, משתמשים ב-method‏ entries.list. מגדירים את resourceNames כדי לציין את הקטגוריה ואת תצוגת היומן המתאימות, ומגדירים את filter כדי לבחור את הנתונים שנוספו לאינדקס.

למידע מפורט על תחביר הסינון, קראו את המאמר שפת השאילתות של Logging.

הוספה לאינדקס וסוגי שדות

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

בזמן הכתיבה

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

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

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

בזמן השאילתה

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

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

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

לדוגמה, נניח שיש לנו את המטענים הייעודיים הבאים ב-JSON:

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

עכשיו מפעילים את המסנן הזה על כל אחד מהם:

jsonPayload.value > 20

אם לשדה jsonPayload.value אין אינדקס מותאם אישית, אז רישום ביומן מחיל התאמה מסוג גמיש:

  • במקרה של "A", מערכת הרישום ביומן מזהה שהערך של המפתח "value" הוא למעשה מספר שלם, ושאפשר להמיר את האילוץ "20" למספר שלם. לאחר מכן, מערכת הרישום ביומן מעריכה את 12345 > 20 ומחזירה את הערך "true" כי זה המצב מבחינה מספרית.

  • ב-"B", הכלי Logging מזהה שהערך של המפתח "value" הוא למעשה מחרוזת. לאחר מכן היא בוחנת את "3" > "20" ומחזירה את הערך True, כי זה המצב מבחינה אלפאנומרית.

אם השדה jsonPayload.value נכלל באינדקס בהתאמה אישית, אז Logging מעריך את האילוץ הזה באמצעות האינדקס במקום הלוגיקה הרגילה של Logging. ההתנהגות משתנה:

  • אם האינדקס הוא מסוג מחרוזת, כל ההשוואות הן השוואות של מחרוזות.
    • הרשומה "A" לא תואמת, כי "12345" לא גדול מ-"20" מבחינה אלפאנומרית. הרשומה "B" תואמת, כי המחרוזת "3" גדולה מ-"20".
  • אם האינדקס הוא מסוג מספר שלם, כל ההשוואות הן השוואות של מספרים שלמים.
    • הרשומה B לא תואמת, כי הערך המספרי 3 לא גדול מ-20. הרשומה "A" תואמת, כי "12345" גדול מ-"20".

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

מקרה קצה של סינון

נניח שמסננים ערך מחרוזת באינדקס jsonPayload.value מסוג מספר שלם:

jsonPayload.value = "hello"

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

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

jsonPayload.value > 50

אף אחת מהאפשרויות לא מתאימה, כי הערכים "12345" ו-"3" לא גדולים אלפאנומרית מ-"50".