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

אתם יכולים להשתמש בשאילתות SQL לדוגמה ב-Observability Analytics כדי לנתח את הנתונים של Cloud Trace, לזהות ערכים חריגים של זמן האחזור ולחשב את אחוזוני הביצועים של יחידות לוגיות למעקב בשירותים שלכם.

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

תמיכה בשפת SQL

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

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

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

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

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

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

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

אם כוללים שדה 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)

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

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

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

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

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

    • Observability View Accessor (roles/observability.viewAccessor) on the observability views that you want to query. התפקיד הזה תומך בתנאי IAM, שמאפשרים להגביל את ההרשאה לתצוגה ספציפית. אם לא מצרפים תנאי למתן התפקיד, לחשבון המשתמש תהיה גישה לכל תצוגות הנתונים של יכולת התצפית.
    • משתמש עם הרשאה לניתוח נתוני יכולת צפייה (roles/observability.analyticsUser) בפרויקט. התפקיד הזה כולל את ההרשאות שנדרשות לשמירה ולהרצה של שאילתות פרטיות, ולהרצה של שאילתות משותפות.

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

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

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

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

    עוברים אל Observability Analytics

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

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

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

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

    סעיף FROM מכיל את השדות הבאים:

כדי להשתמש בשאילתות שמוצגות במסמך הזה בדף BigQuery Studio או כדי להשתמש בכלי שורת הפקודה bq, צריך לערוך את סעיף FROM ולהזין את הנתיב למערך הנתונים המקושר של BigQuery. לדוגמה, כדי לשלוח שאילתה לתצוגה _AllSpans במערך הנתונים המקושר ב-BigQuery שנקרא my_linked_dataset שנמצא בפרויקט myproject, הנתיב הוא `myproject.my_linked_dataset._AllSpans`.

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

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

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

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

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

הצגת מידע נפוץ על תגי span

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

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. התחביר שבו משתמשים בסעיף הזה תלוי בסוג הנתונים של השדה. בקטע הזה תמצאו כמה דוגמאות לסוגי נתונים שונים.

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

השדה 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 start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code