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

אחרי שאוספים את היומנים, אפשר להריץ שאילתות על היומנים במכשיר GDC air-gapped כדי לבדוק אירועים תפעוליים ואירועי ביקורת בעומסי העבודה של הפרויקט. אתם יכולים לסנן, להציג ולייצא זרמי יומנים בחלונית Log ב-Grafana באמצעות ביטויים של Log Query Language ‏ (LogQL). בתהליכי עבודה פרוגרמטיים, שולחים שאילתות ל-Log Query API של הארגון באמצעות HTTP או gRPC, לפי שיטות הגישה הרגילות ל-API.

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

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

לחלופין, כדי לקבל את ההרשאות שנדרשות לשליחת שאילתות ליומנים מ-Log Query API, צריך לבקש מהאדמין של IAM בפרויקט להקצות לכם את התפקיד "שליחת שאילתות ב-Log Query API" במרחב השמות של הפרויקט.

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

יצירת שאילתות ליומנים

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

נקודת קצה של מופע מעקב המערכת

למפעילי אפליקציות (AO)

כתובת ה-URL הבאה היא נקודת הקצה של מכונת המעקב של הפרויקט:

https://GDC_URL/PROJECT_NAMESPACE/grafana

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

  • ‫GDC_URL: כתובת ה-URL של הארגון ב-GDC.
  • ‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.

לאדמין של הפלטפורמה (PA)

כתובת ה-URL הבאה היא נקודת הקצה של מכונת המעקב של הפרויקט:

https://GDC_URL/platform-obs/grafana

מחליפים את GDC_URL בכתובת ה-URL של הארגון ב-GDC.

שאילתות וסינון של היומנים

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

בקטע הזה מוסבר איך לגשת ליומנים באמצעות החלונית Log ב-Grafana.

זיהוי נקודת הקצה (endpoint) של Grafana

למפעילי אפליקציות (AO)

כתובת ה-URL הבאה היא נקודת הקצה של מכונת המעקב של הפרויקט:

https://GDC_URL/PROJECT_NAMESPACE/grafana

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

  • ‫GDC_URL: כתובת ה-URL של הארגון ב-GDC.
  • ‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.

לאדמין של הפלטפורמה (PA)

כתובת ה-URL הבאה היא נקודת הקצה של מכונת המעקב של הפרויקט:

https://GDC_URL/platform-obs/grafana

מחליפים את GDC_URL בכתובת ה-URL של הארגון ב-GDC.

הצגת יומנים בממשק המשתמש של Grafana

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

  1. בוחרים את הפרויקט במסוף GDC.
  2. בתפריט הניווט, לוחצים על Operations > Logging.
  3. לוחצים על View all in Grafana Loki.

דף חדש פותח את נקודת הקצה של Grafana ומציג את ממשק המשתמש.

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

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

  • יומני פעילות: הצגת יומני פעילות.

  • יומני ביקורת: הצגת יומני ביקורת.

  • יומני פעילות ZONE_NAME: הצגת יומני פעילות מאזור מסוים.

  • יומני ביקורת ZONE_NAME: הצגת יומני ביקורת מאזור מסוים.

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

  1. מזינים שאילתה כדי לחפש יומנים בחלונית Log באמצעות ביטויי LogQL (שפת שאילתות של יומנים). אפשר לבצע את השלב הזה באחת מהדרכים הבאות:

    • משתמשים בממשק האינטראקטיבי של הכלי ליצירת שאילתות. אחר כך לוחצים על Run query.
    • מזינים את השאילתה ישירות בשדה הטקסט ולוחצים על Shift+Enter כדי להריץ אותה.

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

    האפשרות "יומני ביקורת" נבחרת בדף "ניתוח נתונים" כדי לקבל יומני ביקורת.

    איור 1. אפשרות בתפריט לשליחת שאילתות ליומני ביקורת מממשק המשתמש של Grafana.

    באיור 1, האפשרות Audit logs מציגה את הממשק שמאפשר ליצור שאילתות מ-Grafana כדי לאחזר יומני ביקורת.

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

    בוחרים טווח תאריכים ליומנים.

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

    1. לוחצים על התפריט Time Picker ב-Grafana.

    2. בתפריט, מבצעים אחת מהפעולות הבאות:

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

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

    הגדרות הזמן נשמרות לכל מרכז בקרה בנפרד. מידע נוסף על שאילתות בטווח זמן מסוים זמין בכתובת https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

    שליחת שאילתה

    שולחים שאילתה לנקודת קצה ל-API של יומן שאילתות באמצעות לקוחות HTTP או gRPC.

    HTTP

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

    שליחת שאילתות ל-Log Query API באמצעות צד הלקוח ב-HTTP כמו curl,‏ wget או צד הלקוח ב-HTTP שאתם יוצרים ומנהלים. בדוגמה הבאה משתמשים בכלי curl כדי לשלוח שאילתה ל-API, ואפשר להשתמש בפורמט דומה לפקודות wget:

    1. מאמתים את בקשת ה-cURL:

      1. מורידים ומתקינים את ה-CLI של gdcloud.

      2. מגדירים את המאפיין core/organization_console_url של gdcloud:

        gdcloud config set core/organization_console_url https://GDC_URL

        מחליפים את GDC_URL בכתובת ה-URL של הארגון ב-GDC.

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

        gdcloud auth login

      4. משתמשים בשם המשתמש ובסיסמה כדי לאמת את החשבון ולהיכנס אליו.

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

        export TOKEN="$($HOME/gdcloud auth print-identity-token --audiences=https://LOG_QUERY_API_ENDPOINT)"

        מחליפים את LOG_QUERY_API_ENDPOINT בנקודת הקצה ל-API של Log Query שממנה רוצים לשלוח שאילתות ליומנים, ובדומיין שאליו רוצים להתחבר. לכן, הערך של הדגל audiences יכול להיות, לדוגמה, https://operational-log-query-api.org-1.zone1.google.gdch.test.

        אחרי ההתחברות, אפשר להשתמש בכותרת ההרשאה בבקשת ה-cURL באמצעות הפקודה gdcloud auth print-identity-token. למידע נוסף, ראו gdcloud auth print-identity-token.

    2. כדי להציג את כל התוויות של פרויקט, שולחים את השאילתה הבאה:

      curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels \
-H "Content-Type: application/json" -v

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

      • ‫LOG_QUERY_API_ENDPOINT: נקודת קצה ל-API של Log Query שממנה רוצים לשלוח שאילתות ליומנים.
      • ‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.

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

      curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels/labels/LABEL/values \
-H "Content-Type: application/json" -v

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

      • ‫LOG_QUERY_API_ENDPOINT: נקודת קצה ל-API של Log Query שממנה רוצים לשלוח שאילתות ליומנים.
      • ‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.
      • ‫LABEL: התווית הספציפית שרוצים לשלוח שאילתה לגבי הערך שלה.

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

      curl -X GET -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/logs \
-H "Content-Type: application/json" -d \
'{"logs_filter": {"labels_equal": {"LABEL": "LABEL_VALUE"}}}' -v

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

      • ‫LOG_QUERY_API_ENDPOINT: נקודת קצה ל-API של Log Query שממנה רוצים לשלוח שאילתות ליומנים.
      • ‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.
      • ‫LABEL: התווית הספציפית שרוצים לשלוח שאילתה ליומנים שלה.
      • ‫LABEL_VALUE: ערך התווית שלגביו רוצים לשלוח שאילתה ליומנים.

      במאמרי העזרה של ה-API מפורטות כל האפשרויות ליצירת שאילתת logs_filter.

    gRPC

    יש תמיכה רחבה ב-gRPC בשפות תכנות, והוא מספק שיטת תקשורת יעילה יותר בהשוואה לצד הלקוח ב-HTTP.

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

    • ליצור ספריית לקוח משלכם על סמך מאגרי אחסון לפרוטוקולים ש-Google מספקת.
    • מטמיעים אימות בלקוח.
    • מטמיעים ניסיונות חוזרים.

    מידע נוסף על מאגרי האחסון לפרוטוקולים זמין במאמרי העזרה של ה-API.

    בדוגמה הבאה מוסבר איך לשלוח שאילתות ליומנים מתוכנית Go באמצעות לקוח gRPC לא מאומת. בדוגמה הזו, נניח שיצרתם חבילת golang שכוללת קובץ build של Bazel כדי לייבא יחסי תלות של קוד:

    1. שומרים את הקוד הבא בתוכנית Go בשם client.go:

      package main
import (
        "context"
        "crypto/tls"
        "flag"
        "fmt"
        "google.golang.org/grpc/credentials"
        "google.golang.org/grpc/metadata"
        pb "<import path to generated log query api protos>/pkg/apis/public/logging/v1/proto"
        "google.golang.org/grpc"
)

var serverAddr = flag.String("server", "localhost:8080", "server address")

func main() {
        flag.Parse()
        tc := credentials.NewTLS(&tls.Config{InsecureSkipVerify: true})
        conn, err := grpc.Dial(*serverAddr, grpc.WithTransportCredentials(tc))

        if err != nil {
                panic(error.Error(fmt.Errorf("create client connection failed: %v", err)))
        }
        defer conn.Close()

        c := pb.NewLogsClient(conn)
        md := metadata.Pairs("clienttest", "test")
        ctx := metadata.NewOutgoingContext(context.Background(), md)

        err = listLabels(ctx, c, "project-foo")
        if err != nil {
                panic(error.Error(err))
        }

        if err := listLabelValues(ctx, c, "project-foo", "resource-bar"); err != nil {
                panic(error.Error(err))
        }

        if err := listLogs(ctx, c, "project-foo", &pb.ListLogsFilter{
                LabelsEqual:    map[string]string{"resource-bar": "resource-bar-value"},
                OrderAscending: true,
        }); err != nil {
                panic(error.Error(err))
        }
}

// List all labels for a project.

func listLabels(ctx context.Context, c pb.LogsClient, project string) error {
        lbr := &pb.ListLabelsRequest{
                Parent:   project,
                PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLabels(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list labels: %v", err)
        }
        fmt.Printf("%v", resp)
        return nil
}

// List specific label values for a project.

func listLabelValues(ctx context.Context, c pb.LogsClient, project string, label string) error {
        lbr := &pb.ListLabelValuesRequest{
                Parent:   project,
                Label:    label,
                PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLabelValues(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list label values: %v", err)
        }
        fmt.Printf("%v", resp)
        return nil
}

// List logs for a specific project.

func listLogs(ctx context.Context, c pb.LogsClient, project string, lf *pb.ListLogsFilter) error {
        lbr := &pb.ListLogsRequest{
                Parent:     project,
                LogsFilter: lf,
                PageSize:   5, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLogs(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list logs: %v", err)
        }
        fmt.Printf("logs: %v", resp)
        return nil
}

    2. מריצים את התוכנית ב-Go:

      go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443

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

      אם לא מציינים את דגל השרת, בקשת ברירת המחדל מגיעה אל localhost.

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

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

  • ‫cluster: שם האשכול.
  • ‫namespace: מרחב השמות של הפרויקט.
  • ‫node: שם הצומת.
  • ‫pod: שם ה-Pod.
  • ‫container: שם המאגר.

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

  • בחירת יומני שרת:

    {cluster="admin", namespace="kube-system", resources="k8s_container", container="kube-apiserver"}

  • בחירת יומני ביקורת של אשכולות:

    {cluster="admin", resources="k8s_audit"}