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

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

תמיכה בשפת SQL

השאילתות שמשמשות בדף Observability Analytics תומכות בפונקציות של GoogleSQL, עם כמה חריגים.

הפקודות הבאות של SQL לא נתמכות בשאילתות SQL שמונפקות באמצעות הדף Observability Analytics:

• פקודות DDL ו-DML
• פונקציות בהגדרת המשתמש ב-JavaScript
• פונקציות של BigQuery ML
• משתני SQL

התכונות הבאות נתמכות רק כשמריצים שאילתה על מערך נתונים מקושר באמצעות הדפים BigQuery Studio ו-Looker Studio, או באמצעות כלי שורת הפקודה של BigQuery:

• פונקציות בהגדרת המשתמש ב-JavaScript
• פונקציות של BigQuery ML
• משתני SQL

שיטות מומלצות

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

נתוני יומן

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

-- Matches log entries whose timestamp is within the most recent 1 hour.
WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

נתוני מעקב

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

-- Matches trace spans whose start_time is within the most recent 1 hour.
WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

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

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

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. כדי לקבל את ההרשאות שדרושות לטעינת הדף Observability Analytics, לכתיבה, להרצה ולשמירה של שאילתות פרטיות בנתוני המעקב, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

   • ‫Observability View Accessor (roles/observability.viewAccessor) בתצוגות הניראות שרוצים לשלוח אליהן שאילתות. התפקיד הזה תומך בתנאי IAM, שמאפשרים להגביל את ההרשאה לתצוגה ספציפית. אם לא מצרפים תנאי להענקת התפקיד, לחשבון המשתמש תהיה גישה לכל תצוגות הנתונים של יכולת התצפית. תצוגות ה-Observability זמינות ב-Public Preview.
   • Observability Analytics User (roles/observability.analyticsUser) on your project. התפקיד הזה כולל את ההרשאות שנדרשות לשמירה ולהרצה של שאילתות פרטיות, ולהרצה של שאילתות משותפות.
   • מציג היומנים (roles/logging.viewer) בפרויקט.
   • בעל הרשאת גישה לתצוגת יומנים (roles/logging.viewAccessor) בפרויקט שבו מאוחסנות תצוגות היומנים שרוצים להריץ עליהן שאילתות.

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

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

איך משתמשים בשאילתות שבדף הזה

1. נכנסים לדף Observability Analytics במסוף Google Cloud :

   עוברים אל Observability Analytics

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

2. בחלונית Query, לוחצים על  SQL, ואז מעתיקים ומדביקים שאילתה בחלונית של שאילתת ה-SQL.

   נתוני יומן

   לפני שמעתיקים שאילתה, מחליפים את השדות הבאים בסעיף FROM

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫LOCATION: המיקום של תצוגת היומן או תצוגת ניתוח הנתונים.
   • ‫BUCKET_ID: השם או המזהה של קטגוריה ביומן.
   • ‫LOG_VIEW_ID: המזהה של תצוגת היומן, שמוגבל ל-100 תווים ויכול לכלול רק אותיות, ספרות, קווים תחתונים ומקפים.

   הדוגמה הבאה מציגה את הפורמט של פסוקית FROM עבור תצוגת יומן:

   FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

   דוגמאות היומנים בדף הזה הן שאילתות של תצוגת יומן. כדי לשלוח שאילתה לתצוגת Analytics, צריך להשתמש בפורמט הנתיב הבא: `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`. בביטוי הקודם, PROJECT_ID הוא מזהה הפרויקט, ו-LOCATION ו-ANALYTICS_VIEW_ID הם המיקום והשם של התצוגה המפורטת ב-Analytics.

   נתוני מעקב

   הפורמט של FROM cause for querying the _AllSpans view:

   FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`

   הפסקה FROM מכילה את השדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט.
   • ‫LOCATION: המיקום של קטגוריית ה-Observability.
   • ‫_Trace הוא שם קטגוריית הנתונים של יכולת התצפית.
   • ‫Spans הוא שם מערך הנתונים.
   • ‫_AllSpans הוא שם התצוגה.

   הערה: התווים שמפרידים בין חלקי הנתיב הם נקודות, (.). אם רכיב של נתיב כמו Google Cloud project מכיל נקודה, צריך לוודא שכל שדה נתיב מוקף במירכאות הפוכות בודדות, (`).

כדי להשתמש בשאילתות שמופיעות במסמך הזה בדף BigQuery Studio או כדי להשתמש בכלי שורת הפקודה של BigQuery, צריך לערוך את סעיף FROM ולהזין את הנתיב למערך הנתונים המקושר.

נתוני יומן

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

נתוני מעקב

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

תרחישים נפוצים לדוגמה

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

הצגת רשומות ביומן בקטגוריית ברירת המחדל של היומן

כדי להריץ שאילתה על קטגוריית _Default, מריצים את השאילתה הבאה:

SELECT
  timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload
FROM
  `PROJECT_ID.LOCATION._Default._AllLogs`
-- Limit to 1000 entries
LIMIT 1000

חילוץ ערך שדה באמצעות ביטוי רגולרי

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

SELECT
  -- Display the timestamp, and the part of the name that begins with test.
  timestamp, REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Get the value of jobName, which is a subfield in a JSON structure.
  JSON_VALUE(json_payload.jobName) IS NOT NULL
ORDER BY timestamp DESC
LIMIT 20

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

כדי למצוא התאמות של מחרוזות משנה, כמו בשאילתה הקודמת, שימוש בפונקציה CONTAINS_SUBSTR יוצר שאילתה יעילה יותר.

הצגת כל נתוני העקבות

כדי להריץ שאילתה על התצוגה _AllSpans, מריצים את השאילתה הבאה:

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

הצגת מידע נפוץ על טווחים

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

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

מידע נוסף זמין במאמר בנושא ביטויים מותנים.

הצגת האחוזון ה-50 וה-99 של זמן האחזור של הטווח

כדי להציג את האחוזון ה-50 וה-99 של זמן האחזור לכל שירות RPC, מריצים את השאילתה הבאה:

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

מידע נוסף על הספירה מופיע במאמר בנושא OpenTelemetry: SpanKind.

כדי לראות את התוצאות בגרף, אפשר ליצור תרשים עם המאפיין rpc_service_method. לדוגמה, אפשר להוסיף שני מדדים: אחד לממוצע של הערך duration_nano_p50 והשני לממוצע של השדה duration_nano_p99.

סינון רשומות ביומן

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

סינון רשומות ביומן לפי סוג מטען ייעודי (payload)

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

• מטענים ייעודיים (payloads) של טקסט

  -- Matches log entries that have a text payload.
  WHERE text_payload IS NOT NULL
  

• מטענים ייעודיים (payloads) של JSON

  -- Matches log entries that have a JSON payload.
  WHERE json_payload IS NOT NULL
  

• מטענים ייעודיים (payloads) של פרוטו

  -- Matches log entries that have a proto payload.
  -- Because proto_payload has a data type of RECORD, this statement tests
  -- whether a mandatory subfield exits.
  WHERE proto_payload.type IS NOT NULL
  

בתוצאות השאילתה, השדות json_payload ו-proto_payload מוצגים בפורמט JSON, שאפשר לנווט בו.

סינון נתוני היומן לפי חותמת זמן

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

-- Matches log entries whose timestamp is within the most recent hour
WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

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

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

סינון לפי משאב

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

-- Matches log entries whose resource type is gce_instance
WHERE resource.type = "gce_instance"

סינון לפי חומרה

כדי לסנן את נתוני היומן לפי רמת חומרה, מוסיפים הצהרה של severity לסעיף WHERE:

-- Matches log entries whose severity is INFO or ERROR
WHERE severity IS NOT NULL AND severity IN ('INFO', 'ERROR')

אפשר גם לסנן את רשומות היומן לפי severity_number, שהוא מספר שלם. לדוגמה, התנאי הבא תואם לכל רשומות היומן שרמת החומרה שלהן היא לפחות NOTICE:

-- Matches log entries whose severity level is at least NOTICE
WHERE severity_number IS NOT NULL AND severity_number > 200

מידע על הערכים המספריים מופיע במאמר בנושא LogSeverity.

סינון לפי שם היומן

כדי לסנן את נתוני היומן לפי שם יומן, מוסיפים הצהרת log_name או log_id לסעיף WHERE:

• שם היומן מציין את נתיב המשאב:

  -- Matches log entries that have the following log ID.
  WHERE log_name="projects/cloud-logs-test-project/logs/cloudaudit.googleapis.com%2Factivity"
  

• המזהה של היומן לא כולל את נתיב המשאב:

  -- Matches log entries that have the following log id.
  WHERE log_id = "cloudaudit.googleapis.com/data_access"
  

סינון רשומות ביומן לפי תווית משאב

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

SELECT
  timestamp, JSON_VALUE(resource.labels.zone) AS zone, json_payload, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries whose resource type is gce_instance and whose zone is
  -- us-central1-f. Because resource has data type JSON, you must use JSON_VALUE
  -- to get the value for subfields, like zone.
  resource.type = "gce_instance" AND
  JSON_VALUE(resource.labels.zone) = "us-central1-f"
ORDER BY timestamp ASC

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

{
   type: "gce_instance"
   labels: {
      instance_id: "1234512345123451"
      project_id: "my-project"
      zone: "us-central1-f"
   }
}

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

סינון לפי בקשת HTTP

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

-- Matches log entries that have a HTTP request_method field.
-- Don't compare http_request to NULL. This field has a data type of RECORD.
WHERE http_request.request_method IS NOT NULL

אפשר גם להשתמש בהצהרה IN:

-- Matches log entries whose HTTP request_method is GET or POST.
WHERE http_request.request_method IN ('GET', 'POST')

סינון לפי סטטוס HTTP

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

-- Matches log entries that have an http_request.status field.
WHERE http_request.status IS NOT NULL

סינון לפי שדה בתוך סוג נתונים של JSON

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

-- Compare the value of the status field to NULL.
WHERE JSON_VALUE(json_payload.status) IS NOT NULL

הסעיף הקודם שונה מעט מהסעיף הבא:

-- Compare the status field to NULL.
WHERE json_payload.status IS NOT NULL

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

{
    status: {
        measureTime: "1661517845"
    }
}

בנתוני היומן האחרים, השדה json_payload בנוי בצורה שונה:

{
    @type: "type.googleapis.com/google.cloud.scheduler.logging.AttemptFinished"
    jobName: "projects/my-project/locations/us-central1/jobs/test1"
    relativeUrl: "/food=cake"
    status: "NOT_FOUND"
    targetType: "APP_ENGINE_HTTP"
}

הפסקה WHERE json_payload.status IS NOT NULL תואמת לשתי הרשומות ביומן. עם זאת, הפסוקית WHERE JSON_VALUE(json_payload.status) IS NOT NULL מתאימה רק לרשומה השנייה ביומן.

סינון רשומות של מעקב

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

סינון לפי סוגי נתונים של מחרוזות

השדה name מאוחסן כ-String.

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

  -- Matches spans that have a name field.
  WHERE name IS NOT NULL
  

• כדי לנתח רק את הטווחים שבהם name מקבל את הערך "POST", משתמשים בסעיף הבא:

  -- Matches spans whose name is POST.
  WHERE STRPOS(name, "POST") > 0
  

• כדי לנתח רק את הטווחים שבהם name מכיל את הערך "POST", משתמשים באופרטור LIKE עם תווים כלליים:

  -- Matches spans whose name contains POST.
  WHERE name LIKE "%POST%"
  

סינון לפי סוגי נתונים של מספרים שלמים

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

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

  -- Matches spans that have field named kind.
  WHERE kind IS NOT NULL
  

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

  -- Matches spans whose kind value is 1 or 2.
  WHERE kind IN (1, 2)
  

סינון לפי סוגי נתונים של רשומות

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

סינון לפי סטטוס או קוד סטטוס

השדה status הוא דוגמה לשדה שסוג הנתונים שלו הוא RECORD. בשדה הזה מאוחסן מבנה נתונים אחד, עם חברים שמסומנים בתוויות code ו-message.

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

  -- Matches spans that have a status.code field that has a value of 1.
  WHERE status.code = 1
  

  השדה status.code מאוחסן כמספר שלם.

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

  -- Matches spans that have status field. When the status field exists, it
  -- must contain a subfield named code.
  -- Don't compare status to NULL, because this field has a data type of RECORD.
  WHERE status.code IS NOT NULL
  

סינון לפי אירועים או קישורים

השדות events ו-links מאוחסנים עם סוג נתונים RECORD, אבל אלה שדות חוזרים.

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

  -- Matches spans that have at least one event. Don't compare events to NULL.
  -- The events field has data type of RECORD and contains a repeated fields.
  WHERE ARRAY_LENGTH(events) > 0
  

• כדי להתאים ליחידות לוגיות למעקב שיש להן אירוע שבו השדה name מכיל את הערך message, משתמשים בפסוקית הבאה:

  WHERE
    -- Exists is true when any event in the array has a name field with the
    -- value of message.
    EXISTS(
      SELECT 1
      FROM UNNEST(events) AS ev
      WHERE ev.name = 'message'
    )
  

סינון לפי סוגי נתונים ב-JSON

השדה attributes הוא מסוג JSON. כל מאפיין בנפרד הוא צמד מפתח/ערך.

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

  -- Matches spans where at least one attribute is specified.
  WHERE attributes IS NOT NULL
  

• כדי לנתח רק את הטווחים שבהם למפתח המאפיין שנקרא component יש ערך של "proxy", משתמשים בפסקה הבאה:

  -- Matches spans that have an attribute named component with a value of proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') = 'proxy'
  

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

  -- Matches spans that have an attribute named component whose value contains proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') LIKE '%proxy%'
  

קיבוץ וצבירה של רשומות ביומן

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

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

קיבוץ של רשומות ביומן לפי חותמת זמן

כדי לקבץ נתונים לפי חותמת זמן, משתמשים בפונקציה TIMESTAMP_TRUNC, שמקצרת חותמת זמן לרמת פירוט שצוינה, כמו HOUR:

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
  JSON_VALUE(json_payload.status) AS status,
  -- Count the number log entries in each group.
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a status field whose value isn't NULL.
  json_payload IS NOT NULL AND JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY
  -- Group by hour and status
  hour,status
ORDER BY hour ASC

מידע נוסף זמין בTIMESTAMP_TRUNCמאמרי העזרה ובקטע פונקציות של תאריך ושעה.

קיבוץ של רשומות ביומן לפי משאב

השאילתה הבאה מראה איך לקבץ רשומות ביומן לפי סוג המשאב, ואז לספור את מספר הרשומות ביומן בכל קבוצה:

SELECT
   -- Count the number of log entries for each resource type
   resource.type, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
GROUP BY resource.type
LIMIT 100

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

השאילתה הבאה מראה איך לקבץ רשומות ביומן לפי רמת החומרה, ואז לספור את מספר הרשומות ביומן בכל קבוצה:

SELECT
  -- Count the number of log entries for each severity.
  severity, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  severity IS NOT NULL
GROUP BY severity
ORDER BY severity
LIMIT 100

קיבוץ של רשומות ביומן לפי log_id

השאילתה הבאה מראה איך לקבץ רשומות ביומן לפי מזהה היומן, ואז לספור את מספר הרשומות ביומן בכל קבוצה:

SELECT
  -- Count the number of log entries for each log ID.
  log_id, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
GROUP BY log_id
ORDER BY count DESC
LIMIT 100

חישוב זמן האחזור הממוצע של בקשות HTTP לכל כתובת URL

השאילתה הבאה ממחישה איך לקבץ רשומות ביומן לפי כתובת ה-URL של בקשת ה-HTTP והמיקום, ואז לספור את מספר הרשומות ביומן בכל קבוצה:

SELECT
  -- Compute the average latency for each group. Because the labels field has a
  -- data type of JSON, use JSON_VALUE to get the value of checker_location.
  JSON_VALUE(labels.checker_location) AS location,
  AVG(http_request.latency.seconds) AS secs, http_request.request_url
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries when the request_method field is GET.
  http_request IS NOT NULL AND http_request.request_method IN ('GET')
GROUP BY
  -- Group by request URL and location
  http_request.request_url, location
ORDER BY location
LIMIT 100

חישוב ממוצע הבייטים שנשלחו לבדיקה של רשת משנה

השאילתה הבאה מראה איך לקבץ רשומות ביומן לפי המיקום שצוין בתוויות המשאבים, ואז לחשב את מספר הרשומות ביומן בכל קבוצה:

SELECT
  -- Compute the average number of bytes sent per location. Because labels has
  -- a data type of JSON, use JSON_VALUE to get the value of the location field.
  -- bytes_sent is a string. Must cast to a FLOAT64 before computing average.
  JSON_VALUE(resource.labels.location) AS location,
  AVG(CAST(JSON_VALUE(json_payload.bytes_sent) AS FLOAT64)) AS bytes
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  resource.type = "gce_subnetwork" AND json_payload IS NOT NULL
GROUP BY
  -- Group by location
  location
LIMIT 100

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

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

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

SELECT
  -- Extract the value that begins with test.
  -- Count the number of log entries for each name.
  REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  json_payload.jobName IS NOT NULL
GROUP BY name
ORDER BY count
LIMIT 20

דוגמאות נוספות זמינות במאמרי העזרה בנושא REGEXP_EXTRACT.

קיבוץ וצבירה של נתוני מעקב

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

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

קיבוץ טווחי זמן לפי שעת התחלה

כדי לקבץ נתונים לפי שעת התחלה, משתמשים בפונקציה TIMESTAMP_TRUNC, שמקצרת חותמת זמן לגרנולריות שצוינה כמו HOUR:

SELECT
  -- Truncate the start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code AS code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans shows start time is within the previous 12 hours.
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 12 HOUR)
GROUP BY
  -- Group by hour and status code.
  hour, code
ORDER BY hour DESC

מידע נוסף זמין בTIMESTAMP_TRUNCמאמרי העזרה ובקטע פונקציות של תאריך ושעה.

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

ספירת טווחי זמן לפי קוד סטטוס

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

SELECT
  -- Count the number of spans for each status code.
  status.code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE status.code IS NOT NULL
GROUP BY status.code

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

חישוב משך הזמן הממוצע של כל הטווחים

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

SELECT
  -- Group by name, and then compute the average duration for each group.
  name,
  AVG(duration_nano) AS nanosecs,
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY name
ORDER BY nanosecs DESC

חישוב משך הזמן הממוצע ואחוזונים לכל שם שירות

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

SELECT
  -- Set the service name by the first non-null value.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,

  -- Count the number spans for each service name. Also compute statistics.
  COUNT(*) AS span_count,
  AVG(duration_nano) AS avg_duration_nano,
  MIN(duration_nano) AS min_duration_nano,
  MAX(duration_nano) AS max_duration_nano,

  -- Calculate percentiles for duration
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)] AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS p99_duration_nano,

  -- Count the number of unique trace IDs. Also, collect up to 5 unique
  -- span names and status codes.
  COUNT(DISTINCT trace_id) AS distinct_trace_count,
  ARRAY_AGG(DISTINCT name IGNORE NULLS LIMIT 5) AS sample_span_names,
  ARRAY_AGG(DISTINCT status.code IGNORE NULLS LIMIT 5) AS sample_status_codes
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY service_name
ORDER BY span_count DESC

חיפוש בעמודות

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

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

• חיפושים שמבוססים על מחרוזת משנה: מציינים את מיקום החיפוש, מחרוזת מילולית, ואז משתמשים בפונקציה CONTAINS_SUBSTR. המערכת מבצעת בדיקה לא תלוית-רישיות כדי לקבוע אם המחרוזת המילולית קיימת בביטוי. הפונקציה CONTAINS_SUBSTR מחזירה TRUE אם ליטרל המחרוזת קיים, ומחזירה FALSE אם לא. ערך החיפוש חייב להיות ערך מילולי STRING, אבל לא הערך המילולי NULL.

חיפוש מבוסס-טוקנים בתצוגת יומן

השאילתה הבאה משאירה רק את השורות שבהן יש שדה שתואם בדיוק לערך '35.193.12.15':

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID` AS t
WHERE
  -- Search data access audit logs for the IP address that matches 35.193.12.15.
  -- The use of backticks prevents the string from being tokenized.
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  SEARCH(t,"`35.193.12.15`")
ORDER BY timestamp ASC
LIMIT 20

אם לא משתמשים בגרשיים הפוכים במחרוזת השאילתה, המחרוזת מפולחת על סמך הכללים שמוגדרים בתיעוד של SEARCH. לדוגמה, כשמריצים את ההצהרה הבאה, מחרוזת השאילתה מפולחת לארבעה טוקנים: ‎"35", "193", "12"‎ ו-‎ "15":

  SEARCH(t,"35.193.12.15")

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

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

  SEARCH(t,"`cloudaudit.googleapis.com/data_access`")

ההצהרה הקודמת מחפשת בכל שדה של רשומות היומן בתצוגת היומן, בעוד שההצהרה המקורית מחפשת רק בשדה log_id של רשומות היומן.

כדי לבצע כמה חיפושים בכמה שדות, צריך להפריד בין המחרוזות ברווח. לדוגמה, ההצהרה הבאה תתאים לשורות שבהן שדה מכיל את הערכים Hello World,‏ happy ו-days:

  SEARCH(t,"`Hello World` happy days")

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

   SEARCH((text_payload, json_payload) ,"`35.222.132.245`")

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

חיפוש מחרוזת משנה בתצוגת יומן

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

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID` AS t
WHERE
  -- Search data access audit logs for the IP address that matches 35.193.12.15.
  -- CONTAINS_SUBSTR performs a contains-test.
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  CONTAINS_SUBSTR(t,"35.193.12.15")
ORDER BY timestamp ASC
LIMIT 20

הרצת שאילתות על כמה תצוגות

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

ההגבלות הבאות חלות על הצטרפות לתצוגות:

1. המיקומים של התצוגות עומדים באחד מהתנאים הבאים:

   • לכל התצוגות יש את אותו המיקום.
   • כל התצוגות נמצאות במיקום global או us.

2. כשמשאבי אחסון משתמשים במפתחות הצפנה בניהול הלקוח (CMEK), אחד מהתנאים הבאים מתקיים:

   • משאבי אחסון שמשתמשים ב-CMEK משתמשים באותו מפתח Cloud KMS.
   • למשאבי אחסון שמשתמשים ב-CMEK יש אב משותף, ובאב הזה מוגדר מפתח Cloud KMS שמוגדר כברירת מחדל ונמצא באותו מיקום כמו משאבי האחסון.

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

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

• משאבי האחסון לא משתמשים ב-CMEK.
• משאב אחסון אחד משתמש ב-CMEK והשני לא.
• שני משאבי האחסון משתמשים ב-CMEK ובאותו מפתח Cloud KMS.

• שני משאבי האחסון משתמשים ב-CMEK, אבל במפתחות שונים. עם זאת, המשאבים חולקים ישות אב שמציינת מפתח ברירת מחדל של Cloud KMS שנמצא באותו מיקום כמו משאבי האחסון.

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

הצטרפות לשתי תצוגות של יומנים לפי מזהה המעקב

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

SELECT
  -- Do an inner join on two tables by using the span ID and trace ID.
  -- Don't join only by span ID, as this field isn't globally unique.
  -- From the first view, show the timestamp, severity, and JSON payload.
  -- From the second view, show the JSON payload.
  a.timestamp, a.severity, a.json_payload, b.json_payload, a.span_id, a.trace
FROM  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_1` a
JOIN  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_2` b
ON
  a.span_id = b.span_id AND
  a.trace = b.trace
LIMIT 100

שאילתה של שני תצוגות יומן עם הצהרת איחוד

כדי לשלב את התוצאות של שני משפטי SELECT או יותר ולמחוק שורות כפולות, משתמשים באופרטור UNION. כדי לשמור על שורות כפולות, משתמשים באופרטור UNION ALL:

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
-- Create a union of two log views
FROM(
  SELECT * FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_1`
  UNION ALL
  SELECT * FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_2`
)
-- Sort the union by timestamp.
ORDER BY timestamp ASC
LIMIT 100

איחוד נתונים של מעקב ויומנים באמצעות מזהה המעקב

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

SELECT
  T.trace_id,
  T.span_id,
  T.name,
  T.start_time,
  T.duration_nano,
  L.log_name,
  L.severity,
  L.json_payload
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN
  `PROJECT_ID.LOCATION._Default._AllLogs` AS L
ON
  -- Join log and trace data by both the span ID and trace ID.
  -- Don't join only on span ID, this field isn't globally unique.
  T.span_id = L.span_id
  -- A regular expression is required because the storage format of the trace ID
  -- differs between a log view and a trace view.
  AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

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

הסרת רשומות כפולות ביומן

ב-Observability Analytics, רשומות כפולות ביומן לא מוסרות לפני הפעלת שאילתה. ההתנהגות הזו שונה מההתנהגות כשמבצעים שאילתה על רשומות ביומן באמצעות הכלי Logs Explorer, שבו רשומות כפולות מוסרות על ידי השוואה בין שמות היומנים, חותמות הזמן ושדות מזהה ההוספה.

אפשר להשתמש באימות ברמת השורה כדי להסיר רשומות כפולות ביומן.

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

מידע נוסף זמין במאמר פתרון בעיות: יש רשומות כפולות ביומן בתוצאות של Observability Analytics.

המאמרים הבאים

• שאילתה וניתוח של טלמטרייה באמצעות Observability Analytics
• יצירת תרשים של תוצאות שאילתת SQL.
• שמירה ושיתוף של שאילתות

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

• פונקציות, אופרטורים ותנאים.
• פונקציות חיפוש.
• תחביר של שאילתות.