尋找及探索追蹤記錄

您可以在「Trace Explorer」頁面查看匯總延遲趨勢、篩選 Cloud Trace 資料，以及檢查個別追蹤記錄和 span，排解效能瓶頸和錯誤。根據預設，「Trace 探索工具」頁面會查詢儲存在Google Cloud 專案中的追蹤記錄資料。不過，您可以設定頁面，查詢儲存在多個專案中的追蹤記錄資料。

如要使用 SQL 對時距執行自訂匯總分析，請使用「Observability Analytics」頁面或 BigQuery。使用「Observability Analytics」頁面時，您可以表格或圖表形式查看查詢結果。如要瞭解如何使用 SQL 查詢追蹤記錄資料，請參閱「查詢及分析追蹤記錄」。

關於「Trace Explorer」頁面

為了協助您找出追蹤記錄資料中的趨勢和模式，系統會匯總延遲時間資料，並以圖表呈現。熱視圖會使用顏色表示儲存格中的跨度數量。Span 數量較多的儲存格顏色會比 Span 數量較少的儲存格深。每個儲存格的工具提示都會顯示延遲時間和其他資訊。您也可以查看延遲時間百分位數和 Span 速率資訊。

下方的螢幕截圖說明如何顯示追蹤資料：

調查問題時，您可能想查看特定追蹤記錄，或只查看具有特定屬性的 span：

• 如要限制要顯示哪些時距，請套用篩選器。例如，您可以依服務、應用程式、錯誤狀態和其他屬性篩選。

• 如要顯示特定追蹤記錄，請使用工具列的網頁瀏覽「Trace ID」(追蹤 ID) 選項。

如要找出離群值並查看個別 Span 的詳細資料，請使用表格部分：

• 您可以依據時間長度標頭，排序「Spans」(Span) 和「Grouped」(分組) 分頁中的資料列。

• 如要瞭解不同服務產生的 Span 數量，請使用「Grouped」(分組) 分頁標籤。每個資料列都對應至服務和時距名稱，並顯示每個項目的延遲統計資料。

如要查看 Span 或分組的詳細資料，請從表格部分的資料列中選取項目。系統會開啟彈出式視窗，顯示追蹤記錄中的 Span。在這個檢視畫面中，您可以探索 Span、其屬性，以及查看事件和記錄資料。您也可以在追蹤記錄中搜尋 Span 和屬性的關鍵字。

「追蹤記錄探索工具」頁面顯示的追蹤記錄資料取決於下列因素：

• 「Scope」(範圍) 設定：決定系統要搜尋哪些檢視畫面的追蹤記錄資料。頁面開啟時，「Scope」(範圍) 元素會設為預設追蹤記錄範圍，系統會查詢該範圍內列出的檢視，找出追蹤記錄資料。

  在新專案中，預設追蹤記錄範圍會列出專案的 _AllSpans 檢視畫面。這個檢視畫面提供專案儲存的所有追蹤資料讀取權限。

  您可以建立追蹤記錄範圍，查詢儲存在多個專案中的資料。詳情請參閱「查看各專案的追蹤記錄」。

• 您在搜尋到的檢視畫面中擁有的 Identity and Access Management (IAM) 權限。如果沒有查看專案追蹤記錄資料的權限， Google Cloud 控制台會顯示警告訊息，且不會顯示該專案的資料。

• 時間範圍設定。

• 套用的篩選器。

您可以將追蹤資料儲存到自訂資訊主頁。詳情請參閱「在自訂資訊主頁上顯示追蹤記錄資料」。

本頁其餘部分將進一步說明如何尋找及探索追蹤記錄資料。

事前準備

如要取得使用 Google Cloud 控制台查看追蹤記錄資料及選取追蹤記錄範圍所需的權限，請要求管理員授予您專案的 Cloud Trace 使用者 (roles/cloudtrace.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備必要權限，可使用 Google Cloud 控制台查看追蹤記錄資料，以及選取追蹤記錄範圍。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

您必須具備下列權限，才能使用 Google Cloud 控制台查看追蹤記錄資料，以及選取追蹤記錄範圍：

• 如要選取追蹤記錄範圍，請按照下列步驟操作： cloudtrace.traceScopes.[get, list]
• 如要讀取預設追蹤記錄範圍，請執行下列操作： observability.scopes.get

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要進一步瞭解角色，請參閱「使用 Identity and Access Management 控管存取權」。

查看匯總追蹤記錄資料

如要查看追蹤記錄資料的匯總資訊，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的 「Trace Explorer」頁面：

   前往「Trace explorer」(Trace 探索工具)

   您也可以透過搜尋列找到這個頁面。

   首次將追蹤資料寫入 Google Cloud 專案後，可能需要幾分鐘的時間，才能查看該資料。如果等待幾分鐘後，仍沒有看到任何追蹤記錄資料，則可能是專案沒有可顯示的資料，或是設定問題。如要瞭解如何解決這些問題，請參閱「疑難排解：追蹤記錄介面中沒有資料」。

2. 設定「Trace Explorer」頁面：

   1. 在 Google Cloud 控制台的工具列中，選取 Google Cloud 專案。如要設定 App Hub，請選取 App Hub 主專案或管理專案。

   2. 選用：使用 Scope 元素，設定系統搜尋追蹤資料的檢視畫面：

      • 如要顯示專案儲存的追蹤記錄資料，請將「Scope」(範圍) 元素的第一個選單設為 「Project」(專案) 或 「_Default」(_預設)。這兩項設定的效果相同。

      • 如要顯示多項專案儲存的追蹤記錄資料，請展開「Scope」(範圍) 元素的第一個選單，選取「Trace scope」(追蹤記錄範圍)，然後選取列出這些專案 _AllSpans 檢視畫面的追蹤記錄範圍。選取後，「Scope」(範圍) 選單會顯示追蹤記錄範圍圖示 ，以及所選追蹤記錄範圍的名稱。

      系統顯示的資料取決於您在搜尋檢視表中的 IAM 角色。舉例來說，如果您沒有查看資料檢視中資料的必要權限，系統就不會顯示該資料。

      詳情請參閱「建立及管理追蹤記錄範圍」。

   3. 選用：使用日期範圍選取器，或用指標醒目顯示 X 軸上的範圍，即可更新日期範圍。

      舉例來說，如要查看延遲時間資料是否有任何趨勢，可以將這個選取器設為「Last 2 weeks」(過去 2 週)。跨度資料會保留 30 天。

3. 探索熱視圖：

   • 使用顏色來識別趨勢和離群值。如果儲存格包含許多跨度，顏色會比包含少量跨度的儲存格深。

   • 使用儲存格的工具提示查看儲存格詳細資料。工具提示會列出 span 數量、日期和時間，以及儲存格的時間間隔。

     提示： 如果您選取熱視圖中的儲存格，系統會更新列出個別 span 或 span 分組的表格。

4. 探索延遲時間百分位數和錯誤率：

   • 如要查看延遲時間趨勢，請將「Chart view」(圖表檢視) 選單設為「Span duration (percentile)」(Span 持續時間 (百分位數))。時間長度圖表會顯示第 50、90、95 和 99 個百分位數。

   • 如要查看回應狀態與時間的關係，請將「Chart view」(圖表檢視) 選單設為「Span rate」(Span 頻率)。圖表會顯示傳送至專案的 Span 速率。

5. 使用「範圍」和「分組」表格找出離群值，或查看統計資訊。「時距」表格會列出個別時距。「Grouped」(分組) 表格會依名稱和服務或工作負載名稱，將 span 分組。

   • 如要查看離群值或尋找範圍名稱，請排序表格。你可以依任何欄標題排序。

     舉例來說，依據時間長度排序「Spans」(Span) 表格，即可找出延遲時間較長的 Span。

   • 如要查看平均延遲時間等統計資料，請使用「Grouped」(分組) 表格。

   • 如要尋找已註冊 App Hub 的服務和工作負載，請在「Service/workload」(服務/工作負載) 欄中，搜尋包含服務圖示 或工作負載圖示 的項目。如果服務或工作負載已在 App Hub 註冊，系統會提供連結，點選後即可開啟對應的應用程式監控資訊主頁。

   如要進一步瞭解特定分組，請選取資料列的 span 名稱。系統會開啟彈出式視窗，顯示追蹤記錄中的 Span。接著即可探索範圍和追蹤記錄。

6. 如要限制顯示的 span，請新增篩選器。如要瞭解如何篩選追蹤記錄資料，請參閱下一節。

篩選追蹤記錄資料

如要只顯示感興趣的資訊，請套用篩選器。 篩選器會限制顯示的資料。例如，您可以依服務名稱和狀態篩選。或者，如果您已將應用程式部署至 App Hub，可能只想查看應用程式的追蹤記錄資料，或應用程式中特定服務或工作負載的追蹤記錄資料。

新增或移除篩選器時，「Trace Explorer」頁面顯示的資料會重新整理，只顯示符合所有套用篩選器的 span。

依追蹤 ID 篩選

排解事件或故障時，您可能會知道追蹤 ID。如要探索該追蹤記錄，請前往工具列，按一下「pageview」追蹤記錄 ID，然後輸入追蹤記錄 ID。

提示： 如果輸入有效的追蹤 ID，但結果空白，則追蹤記錄可能儲存在未搜尋的專案中。如要解決這項問題，請找出儲存追蹤記錄的專案，然後更新「Scope」(範圍) 設定。

輸入有效 ID 後，系統會開啟「詳細資料」彈出式視窗，顯示追蹤記錄和跨度相關資訊。您可以使用該窗格中的選項探索追蹤記錄。例如，您可以在 Span 中搜尋關鍵字。

如果輸入的追蹤記錄 ID 找不到相符項目，追蹤記錄資料可能儲存在「追蹤記錄探索工具」頁面未搜尋的檢視區塊中，或者您可能沒有可查看追蹤記錄資料的 IAM 角色。如要解決這些失敗問題，請找出儲存追蹤資料的專案。請確認您的 IAM 角色可讓您查看各項專案的追蹤記錄資料，然後確認「Scope」(範圍) 元素列出專案的追蹤記錄資料預設檢視畫面。詳情請參閱「設定 Trace Explorer 搜尋的檢視畫面」。

套用時間範圍篩選器

「Span filters」(Span 篩選器) 窗格會列出最常見的篩選器。您可以從任何子類別選取多個項目。新增或移除篩選條件時，「Filter」(篩選條件) 列也會隨之更新。

所有選單的值都來自追蹤資料。如果選單包含沒有任何文字的選項，代表該選項是指不含對應屬性的範圍。

通常可用的範圍篩選器如下：

• OpenTelemetry 服務：依 service.name 屬性篩選。
• Span name：Span 的名稱。
• 時距狀態：要求狀態。如要瞭解這些值，請參閱 OpenTelemetry SpanStatus 說明文件。
• 時間長度：Span 的時間長度。
• 範圍種類：說明範圍之間的關係。如要瞭解這些值，請參閱 OpenTelemetry SpanKind 說明文件。
• App Hub 應用程式：依 gcp.apphub.application.id 資源屬性篩選。
• App Hub 服務：依 gcp.apphub.service.id 資源屬性篩選。
• App Hub 工作負載：依gcp.apphub.workload.id資源屬性篩選。

如要依「Span filters」(範圍篩選器) 窗格中未列出的屬性篩選，請使用「Filter」(篩選器) 列。

使用篩選列

您可以使用「Filter」(篩選器) 列，套用預先定義的篩選器鍵和所選值，也可以同時輸入鍵和值。

如要新增篩選器，請選取「新增篩選器」，然後執行下列其中一項操作：

• 選取已定義的鍵，例如「Span name」(Span 名稱)，然後從次要選單中選取值。

• 選取「新增屬性篩選器」，然後新增自訂鍵和值。 如果輸入自己的篩選器索引鍵，請使用與 Span 屬性索引鍵相同的語法。

  舉例來說，如要依主機 ID 篩選，請將鍵設為 host.id。同樣地，如要依狀態碼篩選，請將鍵設為 /http/status_code。 在這種情況下，您可以將值設為 200，產生篩選器 /http/status_code: 200。如要讓篩選器比對任何值，請選取「任何值」。

依應用程式篩選

如果追蹤資料包含下列資源屬性，您可以依 App Hub 應用程式、工作負載或服務篩選追蹤資料：

• gcp.apphub.application.{container,id,location}
• gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

這些資源屬性是由您新增至應用程式的檢測所產生。

在「Trace Explorer」頁面中，使用下列「Span filters」(Span 篩選器) 選單，依應用程式、服務或工作負載限制 Span：

• App Hub 應用程式
• App Hub 服務
• App Hub 工作負載

如要開啟已在 App Hub 註冊的服務和工作負載的 Application Monitoring 資訊主頁，請按照下列步驟操作：

1. 前往「範圍」或「分組」表格，找出服務或工作負載。您可以尋找服務圖示 、工作負載圖示 ，或篩選表格。

2. 選取「服務/工作負載」欄中的連結。

探索追蹤記錄

如要在追蹤記錄中探索 Span，請按照下列步驟操作：

1. 開啟並設定「Trace Explorer」頁面。如要瞭解這些步驟，請參閱「查看匯總追蹤記錄資料」。

2. 如要查看 Span 或追蹤記錄的詳細資料，請執行下列任一操作：

   • 前往「Trace Explorer」頁面，然後從表格中選取項目。您可以依任何表格標題排序表格列。您可以套用篩選器，限制表格顯示的時距。

   • 前往「Trace Explorer」頁面的工具列，依序點選「pageview」「Trace ID」，然後輸入追蹤記錄 ID。

     「Details」(詳細資料) 彈出式視窗會開啟，並以時間軸格式顯示追蹤記錄及其 span，以及所選 span 的相關資訊：

     

     彈出式視窗包含分割畫面。其中一側會顯示追蹤記錄中的跨度。另一側則會顯示分頁，可讓您查看特定 Span 的資訊，例如屬性、中繼資料，以及附加的提示和回覆。如要瞭解這些分頁，請參閱「查看屬性、記錄項目和事件」。

     時間軸的元素是動態的。選取一個 Span，即可查看其屬性、記錄項目和事件。

探索呼叫階層

根據預設，呼叫階層會以時間軸的形式顯示。第一個項目代表追蹤記錄，後續每個項目則代表一個 span。每個項目都會顯示下列資訊：

• 「Name」(名稱) 欄會顯示名稱和 Span 或追蹤記錄 ID。GenAI 圖示 表示 span 包含生成式 AI 事件或屬性。
• 「服務/工作負載」欄會顯示服務或工作負載名稱。系統會使用 OpenTelemetry 屬性 service.name 設定這個值。如果沒有，系統會顯示 App Engine 服務名稱。
• 延遲時間長條的顏色和長度反映了指令狀態和持續時間。
• 延遲時間長條上的圓圈表示記錄項目或事件與該 span 相關聯。如要變更這項行為，請使用「記錄檔和事件」選單。

如要以有向無環圖 (DAG) 形式查看呼叫階層，請在工具列中選取「Graph」：

在 DAG 檢視畫面中，每個元素都會顯示名稱和延遲時間。顏色反映了 Span 的狀態。您可以使用指標上的滾輪變更圖表大小。

搜尋追蹤記錄中的 span

如要在追蹤記錄中搜尋跨度中的關鍵字，請使用「在追蹤記錄中尋找」欄位。

搜尋功能僅適用於 span 名稱、服務或工作負載名稱，以及屬性欄位。您只能以純文字搜尋，無法搜尋記錄、事件或中繼資料。

舉例來說，如果您輸入 GET，系統就會醒目顯示「名稱」、「服務/工作負載」和「屬性」欄位中，不區分大小寫的 GET 相符項目。

查看屬性、記錄項目和事件

時間範圍的「詳細資料」飛出式視窗包含下列各項的分頁：

• 輸入/輸出：顯示符合 OpenTelemetry GenAI 語意慣例的事件。只有在 Span 包含這些事件時，系統才會顯示這個分頁。為協助您識別這些 span，如果 span 包含符合這些慣例的事件或屬性，時間軸檢視畫面會顯示「GenAI」GenAI圖示 和 span 名稱。詳情請參閱「查看生成式 AI 事件和屬性」。

• 屬性：列出附加至 Span 的屬性。Trace Explorer 會顯示 GenAI 圖示 ，指出哪些 span 含有生成式 AI 屬性。如要瞭解標籤，請參閱「追蹤標籤」。

• 「Logs & Events」(記錄和事件)：這個分頁會列出 trace_id 和 span_id 欄位與所選 Span 相符的事件和記錄項目。系統只會顯示您有權查看的記錄項目。

  如要查看這個分頁中的項目，請按一下「顯示更多」。

  如果您想使用「Logs Explorer」頁面查看記錄資料，請按一下「View logs」(查看記錄)。查詢設定為篩選特定追蹤記錄、Span 和時間範圍。

  注意： 生成式 AI 事件會顯示在「Inputs/Outputs」(輸入/輸出) 分頁。詳情請參閱「查看生成式 AI 事件」。

• Stacktraces：列出可用的堆疊追蹤。

• 中繼資料和連結：列出一般資訊、檢測範圍相關資訊，以及結構定義連結。

  「Metadata」(中繼資料) 專區會顯示下列資訊：

  • Span ID：Span ID 是 64 位元整數，不為 0。詳情請參閱 TraceSpan。
  • 父項 Span ID。
  • 專案 ID。
  • 開始時間和結束時間。

  • 列出其他 Span 連結的表格。下表列出每個連結的下列資訊：

    • 連結至 Span 的鍵/值組合。
    • 連結至時距的追蹤記錄 ID。如果這個欄位列出「Current trace」(目前追蹤記錄)，則表示該 span 連結至同一追蹤記錄中的另一個 span。

    如要瞭解連結，請參閱 Links API 參考資料頁面。

  「Instrumentation scope」(檢測範圍) 和「Schema information」(結構定義資訊) 區段會顯示範圍的名稱和版本，並提供結構定義的連結。如果 Span 不含這項資訊，系統會省略這些部分。

「詳細資料」飛出視窗也可能包含標示為「輸入/輸出」的分頁。這個分頁會顯示生成式 AI 事件。

查看生成式 AI 事件

如要找出含有符合 OpenTelemetry 生成式 AI 語意慣例的屬性或事件的時距，請尋找「生成式 AI」GenAI圖示 ：

• 「Attributes」分頁會顯示附加至 Span 的屬性。如要只列出生成式 AI 屬性，請啟用「僅限生成式 AI 屬性」。

• 「Inputs/Outputs」分頁會顯示符合這些慣例的事件和相關聯屬性，這些屬性也會顯示在「Attributes」分頁中。支援的設定有兩種：

  • 以文字為基礎的提示和回覆會以屬性的形式附加至 span，這些屬性是描述特徵或事件的鍵/值組合。舉例來說，鍵 gen_ai.system 的值會識別提供生成式 AI 功能的系統。生成式 AI 屬性的鍵開頭為 gen_ai。

  • 儲存在 Cloud Storage bucket 中的多模態提示詞和回覆。Cloud Trace 會關聯追蹤記錄和記錄資料，找出這些事件。如要瞭解支援的設定，請參閱「收集及查看多模態提示和回覆」。

    以下螢幕截圖說明「Inputs/Outputs」(輸入/輸出) 如何轉譯附加至 Span 的文字生成式 AI 事件：

    

    如要瞭解產生上述螢幕截圖的範例應用程式，請參閱「使用 OpenTelemetry 檢測 LangGraph ReAct 代理」。

查看對遠端 MCP 伺服器的呼叫

如要查看 MCP 伺服器生成的 Span，請執行下列任一操作：

• 依據範圍名稱篩選追蹤資料。

• 新增屬性篩選器，索引鍵為 mcp.method.name，值為 tools/call。

  這個篩選器專門用於尋找名稱符合 MCP 的 OpenTelemetry 語意慣例的時距。名稱類似於：

  tools/call NAME
  

  在上述運算式中，NAME 是指叫用的端點。舉例來說，這可能類似於 roll_dice。

如要瞭解哪些 Google Cloud MCP 伺服器會產生追蹤記錄，以及如何設定應用程式，指示 MCP 伺服器產生 span，請參閱「使用 Trace 調查 MCP 呼叫」。

後續步驟

• 在自訂資訊主頁上顯示追蹤記錄資料
• 建立及管理追蹤記錄範圍
• 分享追蹤記錄和範圍
• 疑難排解