尋找及探索追蹤記錄

如要查看追蹤記錄資料的匯總表示法，或找出及探索個別追蹤記錄或含有特定標籤的追蹤記錄，請使用「Trace 探索工具」頁面。

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

如要執行查詢，對跨度進行匯總分析，請使用「可觀測性分析」頁面或 BigQuery。這兩個介面都支援使用 SQL 查詢範圍資料。使用「可觀測性分析」頁面時，您可以將查詢結果顯示為表格或圖表。如要進一步瞭解如何使用 SQL 查詢追蹤記錄資料，請參閱「查詢及分析追蹤記錄」。

這項功能僅支援 Google Cloud 專案。如要進行 App Hub 設定，請選取 App Hub 主專案或管理專案。

關於「Trace Explorer」頁面

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

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

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

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

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

• 你可以依據「Spans」(跨度)和「Grouped」(分組) 分頁的「Duration」(時間長度) 標題，排序資料列。

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

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

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

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

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

• 您在搜尋檢視畫面中的身分與存取權管理 (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 元素設定系統要搜尋追蹤資料的檢視畫面：

      • 如要顯示專案儲存的追蹤資料，請將「範圍」元素的第一個選單設為 「專案」或 「_Default」。這兩項設定的作用相同。

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

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

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

   3. 選用：使用時間範圍選取器更新時間範圍，或使用指標在 X 軸上醒目顯示範圍。

      舉例來說，如果想查看延遲資料是否有任何趨勢，您可以將這個選取器設為「最近 2 週」。跨度資料會儲存 30 天。

3. 探索熱視圖：

   • 使用顏色找出趨勢和離群值。與只有少數跨度的儲存格相比，跨度較多的儲存格顏色較深。

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

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

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

   • 如要查看延遲趨勢，請將「圖表檢視畫面」選單設為「跨度時間 (百分位數)」。時間圖表會顯示第 50、90、95 和 99 個百分位數。

   • 如要查看隨時間變化的回應狀態，請將「圖表檢視」選單設為「範圍率」。圖表會顯示傳送至專案的範圍率。

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

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

     舉例來說，您可以依時間長度排序「範圍」表格，找出延遲時間較長的範圍。

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

   • 如要找出 App Hub 註冊的服務和工作負載，請在「服務/工作負載」欄中搜尋包含服務圖示 或工作負載圖示 的項目。App Hub 註冊的服務或工作負載隨附的連結會開啟對應的應用程式監控資訊主頁。

   如要進一步瞭解特定分組，請選取資料列的時距名稱。系統會開啟飛出視窗，顯示時距的追蹤記錄。接著，您就可以探索時距和追蹤記錄。

6. 新增篩選器來限制要顯示哪些時距。如要進一步瞭解如何篩選追蹤記錄資料，請參閱下一節。

篩選追蹤記錄資料

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

新增或移除篩選器時，追蹤記錄探索器頁面顯示的資料會重新整理，只顯示符合所有已套用篩選器的範圍。

依 ID 篩選追蹤記錄

排解事件或失敗問題時，您可能知道追蹤 ID。如要探索該追蹤記錄，請前往工具列，依序點選「網頁瀏覽」「搜尋追蹤記錄」，然後輸入追蹤記錄 ID。

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

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

套用時間範圍篩選器

「範圍篩選器」窗格會列出最常見的篩選器。你可以從任何子類別選取多個項目。新增或移除篩選器時，「篩選器」列也會隨之更新。

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

一般情況下，您可以使用下列範圍篩選器：

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

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

使用篩選列

您可以在「篩選」列中套用篩選器，方法是選取預先定義的篩選鍵和值，或是輸入鍵和值。

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

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

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

  舉例來說，如要依主機 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}

先前的資源屬性是由您新增至應用程式的檢測所產生。您可以依任何資源屬性篩選追蹤資料。不過，下列範圍篩選器會依應用程式、服務和工作負載 ID 篩選：

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

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

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

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

探索追蹤記錄

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

1. 開啟並設定「Trace 探索工具」頁面。如需這些步驟的相關資訊，請參閱「查看匯總的追蹤記錄資料」。

2. 如要查看時距或追蹤記錄的詳細資料，請執行下列其中一項操作：

   • 前往「Trace 探索工具」頁面，然後從表格中選取項目。您可以依據任何表格標題排序表格列，也可以套用篩選器，限制表格顯示的範圍。

   • 前往「Trace Explorer」頁面的工具列，依序點選「pageview」(網頁檢視)「Search for trace」(搜尋追蹤記錄)，然後輸入追蹤記錄 ID。

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

     

     飛出視窗會顯示分割畫面。其中一側會顯示追蹤記錄中的時距。另一側則會顯示分頁，方便您查看時距專屬資訊，例如屬性、中繼資料，以及附加的提示詞和回應。如要進一步瞭解這些分頁，請參閱「查看屬性、記錄項目和事件」。

     時間軸的元素是動態的。如要探索其他時間範圍，請選取該範圍，查看所選範圍的屬性、記錄項目和事件。

探索呼叫階層

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

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

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

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

搜尋追蹤記錄中的時距

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

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

舉例來說，如果輸入 GET，系統會醒目顯示「名稱」、「服務/工作負載」和「屬性」窗格中顯示 GET 的文字 (忽略大小寫)。

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

時距的「詳細資料」飛出式視窗包含下列各項的索引標籤：

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

• 屬性：列出附加至範圍的屬性。追蹤記錄探索工具會顯示 GenAI 圖示 ，指出哪些範圍含有生成式 AI 屬性。如需標籤相關資訊，請參閱「追蹤記錄標籤」。

• 記錄檔和事件：這個分頁會列出 trace_id 和 span_id 欄位與所選時距相符的事件和記錄項目。系統只會顯示您有權查看的記錄項目。

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

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

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

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

• 中繼資料和連結：列出一般資訊、有關插樁範圍的資訊，以及結構定義的連結。

  「中繼資料」部分會顯示下列資訊：

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

  • 這個表格列出其他範圍的連結。這個表格會列出每個連結的下列資訊：

    • 連結至時距的鍵/值組合。
    • 連結至時距的追蹤記錄 ID。如果這個欄位列出「目前的追蹤記錄」，則時距會連結至同一追蹤記錄中的另一個時距。

    如需連結的相關資訊，請參閱 Links API 參考資料頁面。

  「檢測範圍」和「結構定義資訊」部分會顯示範圍的名稱和版本，並提供結構定義的連結。如果時距不含這類資訊，系統會省略這些部分。

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

查看生成式 AI 活動

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

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

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

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

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

    下圖說明「輸入/輸出」如何轉譯附加至範圍的文字生成式 AI 事件：

    

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

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

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

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

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

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

  tools/call NAME
  

  在上述運算式中，NAME 是指叫用的端點。例如：roll_dice。

如要瞭解哪些遠端 Google Cloud MCP 伺服器支援追蹤記錄產生功能，以及如何設定應用程式，指示這些伺服器產生範圍，請參閱「使用 Trace 檢查 MCP 呼叫」。

後續步驟

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