繪製 SQL 查詢結果圖表

Observability Analytics 可將 SQL 查詢結果以圖表呈現，方便您找出追蹤記錄資料中的模式和趨勢。執行查詢來搜尋及匯總追蹤記錄資料後，您可以在表格中查看結果、將結果轉換為圖表，以及將圖表儲存至資訊主頁。

舉例來說，下圖顯示 Span 隨時間回報的狀態，並依 service_name 分組：

事前準備

登入 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, if it is not already enabled.

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

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, if it is not already enabled.

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

1. 如要取得載入「Observability Analytics」頁面、編寫及執行追蹤記錄資料查詢，以及將圖表儲存至自訂資訊主頁所需的權限，請要求管理員授予您下列 IAM 角色：

   • 在要查詢的可觀測性檢視表上，具備可觀測性檢視表存取子 (roles/observability.viewAccessor) 角色。這個角色支援 IAM 條件，可讓您限制授予特定檢視。如果未在角色授權中附加條件，主體就能存取所有觀測能力檢視畫面。
   • 專案的 Monitoring 編輯者 (roles/monitoring.editor)。

   如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

   您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

選取要製成圖表的資料

如要設定圖表顯示的資料，請使用 SQL 建構查詢。選取「Chart」(圖表) 分頁標籤時，圖表會顯示查詢結果。執行查詢並產生圖表後，您可以變更圖表類型並選取資料欄，自訂圖表來顯示不同資料。

如要以圖表形式查看查詢結果，請按照下列步驟執行查詢：

1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

   前往「Observability Analytics」(觀測能力分析) 頁面

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 在「查詢」窗格中輸入查詢，然後點選「執行」。

3. 查詢完成後，在「Results」(結果) 分頁中，選取查詢結果的查看方式：

   • 表格：僅限表格格式。

   • 圖表：僅限圖表格式。

   • 兩者：圖表和表格格式。

     選取查詢結果的檢視方式後，您可以為所選圖表設定任何欄位，然後將查詢和結果儲存至自訂資訊主頁。如果選取「Table」(表格) 選項，系統會以表格形式儲存。否則，格式為圖表。

     如果是圖表，您可以透過圖表選項選取圖表類型，以及要納入圖表的資料列和資料欄。如要進一步瞭解圖表設定，請參閱「自訂圖表設定」。

自訂圖表設定

您可以變更圖表類型、選取要繪製圖表的維度和測量指標，以及套用細目，藉此自訂圖表設定。維度用於將資料列分組或分類，並代表 X 軸值。「Measure」(測量指標) 或 Y 軸值，是根據 Y 軸繪製的資料序列。

變更圖表類型

您可以根據選取做為維度和測量指標的資料列和資料欄類型，以及資料的視覺化呈現方式，從下列圖表類型中進行選擇。

• 長條圖 (預設)： 長條圖會在兩個軸上繪製資料。如果圖表使用類別或字串做為維度，您可以將長條圖的圖表設定設為水平或垂直，維度和測量軸會互換。

• 折線圖： 折線圖可用來呈現資料隨時間的變化。使用折線圖時，每個時間序列都會以不同的線條顯示，對應您選取的測量指標。

  如果 X 軸是以時間為基礎，每個資料點都會放在時間間隔的開頭。每個資料點都透過線性內插法連接。

• 堆疊面積圖： 面積圖是以折線圖為基礎，每條線下方的區域都會加上陰影。在面積圖中，資料序列會堆疊。舉例來說，如果您有兩個相同的系列，則系列會在折線圖中重疊，但陰影區域會在面積圖中堆疊。

• 圓餅圖或環圈圖：圓餅圖會使用圓形代表整個資料集，並以圓形中的扇形代表資料集中的類別，藉此呈現資料集中的類別與整個資料集的關係。扇形的大小代表該類別占整體的比例，通常以百分比表示。

• 表格： 表格會為查詢結果中的每一列顯示一列。資料表中的資料欄是由 SELECT 子句定義。如果您打算在資訊主頁上以表格形式顯示資料，請使用 LIMIT 子句，將結果中的資料列數量限制在幾百列以下。

• 量表或評量表： 量表和評量表會提供最新值，並根據該值與一組門檻的比較結果，顯示綠色、琥珀色或紅色。量表只會顯示最新值的相關資訊，評量表則不同，還能包含過去值的相關資訊。

  只有在查詢結果至少包含一列，且該列包含時間戳記欄和數值資料欄時，量表和評量表才能顯示查詢結果。查詢結果可以包含多個資料列和兩個以上的資料欄。

  如要在查詢中執行時間彙整，請按照下列步驟操作：

  • 設定查詢，依時間間隔匯總資料、依時間戳記遞減排序結果，並限制結果中的資料列數量。您可以使用 LIMIT 子句或日期範圍選取器，限制查詢結果中的資料列數量。

    舉例來說，下列查詢會查詢追蹤記錄資料，並以一小時為間隔匯總資料、套用限制，以及排序結果：

    SELECT TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
       COALESCE(
          JSON_VALUE(resource.attributes, '$."service.name"'),
          JSON_VALUE(attributes, '$."service.name"'),
          JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
       status.code AS status,
       COUNT(*) AS count
    FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
    GROUP BY hour, service_name, status
    ORDER BY hour DESC
    LIMIT 1000

    以下說明上述運算式中各欄位的意義：

    • PROJECT_ID：專案 ID。
    • LOCATION：觀測能力 bucket 的位置。

    上一個查詢用於產生本文件開頭顯示的圖表。該圖也顯示了圖表設定。

  • 將「維度」設為與記錄時間單位的資料欄一致。舉例來說，如果查詢依一小時匯總資料，並建立名為 hour 的資料欄，請將「Dimension」(維度) 選單設為 hour。

  • 選取「Disable interval」(停用間隔)，因為查詢已指定匯總間隔。在本範例中，這個間隔為一小時。

  • 將「Measure」(測量指標) 設為數值欄，並將函式設為「none」(無)。

    注意： 如果查詢會執行以時間為基礎的匯總，請務必遵循前述指引。如果採用其他設定，查詢和 Observability Analytics 都會執行匯總作業，導致量表或評量表顯示非預期的值。

  如要讓 Observability Analytics 執行時間彙整，請按照下列步驟操作：

  • 設定日期範圍選取器，這會影響查詢結果中的資料列數量。
  • 將「維度」設為與記錄時間單位的資料欄一致。舉例來說，您可以將這個選單設為 timestamp。
  • 將「Interval」(間隔) 選單設為特定匯總時間間隔。舉例來說，將這個欄位的值設為 1 hour。請勿選取「Automatic interval」。
  • 將「Measure」(測量) 設為數值欄，然後選取「sum」(總和) 等函式。

變更維度和測量指標

您可以選取維度和測量結果欄位，選擇要繪製哪些列和欄。

注意： 如果查詢結果包含含有長字串 (例如錯誤訊息) 的資料欄，且您選取該資料欄做為維度或細目，圖表可能會出現錯誤或非預期的值。

• 維度

  維度必須是時間戳記、數字或字串欄。根據預設，維度會設為結構定義中第一個以時間戳記為基礎的資料欄。如果查詢中沒有時間戳記，系統會選取第一個字串資料欄做為維度。您也可以在「Chart display」(圖表顯示) 面板中自訂維度。如果選取時間戳記資料欄做為維度，圖表會顯示資料隨時間變化的情形。如果選取字串資料欄做為長條圖的維度，您可以按照遞增或遞減順序排序資料，這會按照詞彙順序排序維度。您也可以保留「預設」排列順序，根據對應測量指標的值，以遞減順序排序維度。

  根據預設，系統會自動設定時間戳記的間隔，但您也可以選取自訂間隔。自動間隔會根據日期範圍選取器變更值，以維持大小相似的群組。

  您也可以停用間隔，在查詢中指定自己的匯總和日期範圍，進行更複雜的分析。停用間隔會將測量指標的匯總函式設為 none。維度間隔停用時，只能使用數值測量指標。

  注意： 只有 TIMESTAMP 欄可做為時間戳記維度。如要使用 DATE 和 DATETIME，您必須使用 CAST() 函式將資料類型轉換為 TIMESTAMP。

• 度量

  您可以在「圖表顯示」面板中選取多個測量指標。選取測量指標時，也必須選取要對分組值執行的匯總函式，例如 count、sum、average 和 percentile-99。舉例來說，count-distinct 會傳回指定資料欄中不重複值的數量。

  如果勾選維度的「停用間隔」核取方塊，則可使用 none 匯總函式選項。如果維度是字串值，系統就不會顯示「停用間隔」核取方塊。不過，如果將測量指標的匯總函式設為 none，也會停用間隔。

新增細目

注意： 如果圖表包含多個測量指標，就無法新增細目。

如要根據其他資料欄將單一資料序列分割成多個資料序列，請新增細目。

選取細目時，請選擇包含少量簡短且有意義標籤的資料欄，例如 region_name。請勿選取可能包含大量字串或長字串的欄位，例如 textPayload。

舉例來說，下圖顯示各項服務建立的 Span 數量，以及依 Span 名稱細分的資料：

產生及顯示追蹤記錄範例

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

您可以設定 SQL 圖表，分析追蹤記錄資料，顯示動態生成的範例。「範例」是與指標測量相關聯的代表性樣本要求或 span。每個範例都會連結至追蹤記錄，選取範例會開啟顯示追蹤記錄的彈出式視窗。

設定需求

如要顯示範例，必須符合下列條件：

• 圖表的查詢是以 SQL 編寫，查詢目標是追蹤記錄資料。
• 圖表會使用折線圖或長條圖。
• trace_id 和 start_time 是查詢結果的一部分。

如要隱藏範例，請前往圖表的工具列，然後選取「flare」「隱藏範例」。

系統如何產生範例

系統會套用智慧型取樣選取策略，確保範例可讀且相關：

• AVG 和 PERCENTILE 等統計測量：系統會比較原始 Span 值與圖表的內插趨勢線，並將樣本分組到偏差集區。系統會從每個集區中按比例取樣，並在時間軸上平均分布。
• 如果是 COUNT 等頻率計數：系統會沿著圖表視窗的上邊界放置範例，並在時間和資料序列細目中平均分配。

限制

• 如果圖表顯示多個時間序列，系統會減少顯示的範例數量。
• 樣本可能不會平均分布在圖表的時間間隔內。
• Y 軸刻度可能會扭曲視覺顯示。如果圖表使用對數 Y 軸，或時間序列包含離群值，就最有可能發生失真。
• 您無法設定系統產生範例的方式。

將圖表儲存至自訂資訊主頁

查詢生成圖表後，您可以將圖表儲存至自訂資訊主頁。自訂資訊主頁可讓您使用各種小工具類型，顯示及整理實用資訊。您也可以在這些資訊主頁定義變數，也就是僅套用至特定小工具的資訊主頁層級篩選器。如要將變數套用至小工具，您必須修改查詢。詳情請參閱「將變數套用至小工具」。

如果查詢在 BigQuery 引擎上執行，且查詢的資源不在相同的擁有權邊界內，資訊主頁會針對包含 SQL 查詢的小工具顯示警告訊息。擁有權界線取決於多項因素，其中一項是查詢使用的資源階層。如要避免出現這些警告，請設定 service perimeter。

如要將圖表儲存至資訊主頁，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

   前往「Observability Analytics」(觀測能力分析) 頁面

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 執行查詢來產生圖表，然後按一下「 Save to dashboard」(儲存至資訊主頁)。

3. 在「Save to dashboard」(儲存至資訊主頁) 對話方塊中，輸入圖表標題，然後選取要儲存圖表的資訊主頁。

4. 選用：如要查看自訂資訊主頁，請按一下浮動式訊息中的「View dashboard」(查看資訊主頁)。

如要查看自訂資訊主頁清單，其中包含 SQL 查詢生成的圖表，請前往「Save to dashboard」(儲存至資訊主頁) 按鈕，然後點選 「Menu」(選單)。

編輯儲存至自訂資訊主頁的圖表

圖表儲存至資訊主頁後，您仍可進行修改。詳情請參閱「修改小工具設定」。在「Configure widget」對話方塊中，您可以執行下列操作：

• 變更查詢的資料。
• 編輯用來生成圖表的查詢。
• 自訂圖表設定，以視覺化方式呈現不同資料。

限制

• 如果 Google Cloud 專案位於使用 Assured Workloads 的資料夾中，產生的圖表就無法顯示在自訂資訊主頁上。

• 資訊主頁層級篩選器不適用於透過 SQL 查詢生成的圖表。

• 選取的資料欄至少須有一列含有非空值。

• 如果您儲存查詢並自訂圖表設定，系統不會儲存自訂圖表設定。

• 如果查詢已有匯總函式，Observability Analytics 會自動套用額外的匯總函式，因此生成的圖表可能會不同。

• JSON 路徑必須轉換為字串或數字，才能繪製圖表。

後續步驟

• 儲存及共用 SQL 查詢
• SQL 查詢示例
• 在 BigQuery 中查詢連結的 BigQuery 資料集