‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

בדף הזה מוסבר איך להשתמש בממשק המשתמש של Grafana ובממשק ה-API של Log Query כדי לשלוח שאילתות ליומנים ולהציג אותם באופן חזותי, וכך לקבל תובנות לגבי אירועים ופעילות בשירות.

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

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

לוחות Grafana: תוכלו לקבל תובנות לגבי רשומת הפעילות של הפרויקט דרך לוח היומן של מופע Grafana. בחלונית הזו אפשר לשלוח שאילתות ולזהות יומנים ספציפיים, ולקבל נתונים מפורטים שמותאמים לצרכים שלכם. ‫Grafana מספק ממשק ידידותי למשתמש לסינון ולניתוח של נתוני עומס העבודה, ליצירת לוחות בקרה ולוחות מותאמים אישית להמחשה מקיפה.
‫Log Query API: כדי לגשת ליומנים באופן פרוגרמטי, אפשר להשתמש ב-Log Query API של הפרויקט. ‫Log Query API הוא API שאינו מבוסס על Kubernetes, שתומך ב-HTTP וב-gRPC, וחושף נקודות קצה משלו. כדי לגשת ל-API הזה רק בארגון ספציפי ב-Distributed Cloud, צריך לפעול לפי שיטות הגישה הרגילות ל-API.

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

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

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

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

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

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

חלונית Grafana Log

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

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

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

  https://GDC_URL/PROJECT_NAMESPACE/grafana

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

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

לדוגמה, נקודת הקצה של Grafana לפרויקט platform-obs בארגון org-1 היא https://org-1/platform-obs/grafana.

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

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

במסוף GDC, בוחרים את הפרויקט.
בתפריט הניווט, בוחרים באפשרות פעולות > רישום ביומן.
לוחצים על הצגת הכול ב-Grafana Loki.

ייפתח דף חדש עם נקודת הקצה של Grafana ויוצג ממשק המשתמש.
בממשק המשתמש, לוחצים על ניתוח ניתוח בתפריט הניווט כדי לפתוח את הדף ניתוח.
בתפריט בסרגל ניתוח, בוחרים מקור נתונים כדי לאחזר יומנים, בהתאם לסוג היקום:
- יקומים עם אזור אחד: בוחרים אחד ממקורות הנתונים הבאים כדי להציג נתוני רישום מאזור אחד ביקום:
  - יומנים תפעוליים: הצגת יומנים תפעוליים.
  - יומני ביקורת: הצגת יומני ביקורת.
- ‫Multi-zone universes: ‏ Grafana יכול להתחבר לאזורים שונים ולהציג נתונים חוצי-אזורים. בוחרים אחד ממקורות הנתונים הבאים כדי להציג נתוני רישום מכל אזור ביקום, ללא קשר לאזור שבו נכנסתם לחשבון:
  - יומני פעילות ZONE_NAME: הצגת יומני פעילות מאזור מסוים.
  - יומני ביקורת ZONE_NAME: הצגת יומני ביקורת מאזור מסוים.
  בנוסף, כדי ליצור תרשימים של נתונים מאזורים שונים בלוח בקרה אחד ולהוסיף כמה אזורים לשאילתה, בוחרים באפשרות מעורב כמקור הנתונים.
  
  הערה: יומני הביקורת זמינים רק לאדמינים של הפלטפורמה, גם אם הם לא יכולים ליצור או להגדיר יעדים לרישום ביומן הביקורת. מפעילים של אפליקציות יכולים לגשת רק ליומני פעילות.
מזינים שאילתה כדי לחפש יומנים בחלונית Log באמצעות ביטויים של LogQL (שפת שאילתות של יומנים). אפשר לבצע את השלב הזה באחת מהדרכים הבאות:
- שימוש בממשק האינטראקטיבי של כלי בניית השאילתות. אחר כך לוחצים על Run query.
- מזינים את השאילתה ישירות בשדה הטקסט ומקישים על Shift+Enter כדי להריץ את השאילתה.
בדף מוצגים היומנים שתואמים לשאילתה. אחרי שמריצים שאילתה על היומנים, אפשר לייצא אותם. לוחצים על ייצוא כדי להוריד את היומנים בפורמט טקסט פשוט או CSV. אפשר גם לבחור טווח זמן ליומנים.

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

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

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

בחירת טווח זמן ליומנים

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

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

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

Log Query API

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

זיהוי נקודת הקצה של Log Query API

Log Query API חושף את שתי נקודות הקצה הבאות לשאילתות ביומני ביקורת וביומנים תפעוליים:

נקודת קצה של יומן הביקורת:
```
audit-log-query-api.ORG_DOMAIN
```
הערה: יומני ביקורת זמינים רק לאדמינים של הפלטפורמה, גם אם הם לא יכולים ליצור או להגדיר יעדים לרישום ביומן הביקורת.
נקודת קצה של יומן תפעולי:
```
operational-log-query-api.ORG_DOMAIN
```

מחליפים את ORG_DOMAIN בשם הדומיין של הארגון. אפשר לראות את המאפיין הזה באמצעות הפקודה gdcloud config list. שם הדומיין חייב להיות בהתאם לתחביר org-name.zone.google.gdch.com. לדוגמה, לארגון בשם org-1, באזור zone1, בסביבת בדיקה יש דומיין כמו org-1.zone1.google.gdch.test.

ל-Log Query API יש שלוש אפשרויות של נקודות קצה:

‫labels: רשימה של כל התוויות בפרויקט.
‫labels/labels/LABEL/values: רשימת ערכי תוויות ספציפיים של פרויקט.
‫logs: הצגת יומנים של פרויקט ספציפי.

מידע נוסף זמין במאמרי העזרה של ה-API.

שליחת שאילתה

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

HTTP

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

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

מאמתים את בקשת cURL:
1. מורידים ומתקינים את gdcloud CLI.
2. מגדירים את המאפיין gdcloud core/organization_console_url:
```
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.
כדי להציג רשימה של כל התוויות בפרויקט, שולחים את השאילתה הבאה:
```
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: מרחב השמות של הפרויקט.
כדי לראות את רשימת הערכים של תווית ספציפית בפרויקט, שולחים את השאילתה הבאה:
```
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: התווית הספציפית שרוצים לשאול לגבי הערך שלה.
אם רוצים לשלוח שאילתה ליומנים של פרויקט ספציפי, צריך ליצור שאילתת 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 לייבוא יחסי תלות בקוד:

שומרים את הקוד הבא בתוכנת 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
}

מריצים את תוכנית Go:
```
go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫PATH_TO_API: הנתיב לקובץ ה-API.
- ‫LOG_QUERY_API_ENDPOINT: נקודת קצה ל-API של Log Query שממנה רוצים לשלוח שאילתות ליומנים.
אם לא מציינים את דגל השרת, בקשת ברירת המחדל מגיעה אל localhost.

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

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

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

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

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

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

בוחרים ביומני ביקורת של האשכול:
```
{cluster="admin", resources="k8s_audit"}
```