追蹤服務專員

本頁面說明如何在代理程式上啟用 Cloud Trace，以及如何查看追蹤記錄，分析查詢回應時間和執行的作業。

追蹤記錄是時間軸，記錄代理程式對每項查詢的回應。舉例來說，下方的甘特圖顯示 LangchainAgent 的追蹤記錄範例：

查詢的 Trace 範例 

甘特圖的第一列代表追蹤記錄，追蹤記錄是由個別範圍組成，代表單一工作單位，例如函式呼叫或與 LLM 的互動，第一個範圍代表整體要求。每個範圍都會提供特定作業的詳細資料，例如作業名稱、開始和結束時間，以及要求中的任何相關屬性。舉例來說，下列 JSON 顯示代表呼叫大型語言模型 (LLM) 的單一範圍：

  {
    "name": "llm",
    "context": {
        "trace_id": "ed7b336d-e71a-46f0-a334-5f2e87cb6cfc",
        "span_id": "ad67332a-38bd-428e-9f62-538ba2fa90d4"
    },
    "span_kind": "LLM",
    "parent_id": "f89ebb7c-10f6-4bf8-8a74-57324d2556ef",
    "start_time": "2023-09-07T12:54:47.597121-06:00",
    "end_time": "2023-09-07T12:54:49.321811-06:00",
    "status_code": "OK",
    "status_message": "",
    "attributes": {
        "llm.input_messages": [
            {
                "message.role": "system",
                "message.content": "You are an expert Q&A system that is trusted around the world.\nAlways answer the query using the provided context information, and not prior knowledge.\nSome rules to follow:\n1. Never directly reference the given context in your answer.\n2. Avoid statements like 'Based on the context, ...' or 'The context information ...' or anything along those lines."
            },
            {
                "message.role": "user",
                "message.content": "Hello?"
            }
        ],
        "output.value": "assistant: Yes I am here",
        "output.mime_type": "text/plain"
    },
    "events": [],
  }

詳情請參閱 Cloud Trace 說明文件中的「追蹤記錄和時距」和「追蹤記錄內容」。

為代理程式寫入追蹤記錄

如要為代理程式撰寫追蹤記錄，請按照下列步驟操作：

ADK

如要為 AdkApp 啟用追蹤功能，請在開發 Agent Development Kit 代理程式時指定 enable_tracing=True。例如：

  from vertexai.preview.reasoning_engines import AdkApp
  from google.adk.agents import Agent

  agent = Agent(
      model=model,
      name=agent_name,
      tools=[get_exchange_rate],
  )

  app = AdkApp(
      agent=agent,          # Required.
      enable_tracing=True,  # Optional.
  )

LangchainAgent

如要為 LangchainAgent 啟用追蹤功能，請在開發 LangChain 代理程式時指定 enable_tracing=True。例如：

from vertexai.preview.reasoning_engines import LangchainAgent

agent = LangchainAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

LanggraphAgent

如要為 LanggraphAgent 啟用追蹤功能，請在開發 LangGraph 代理程式時指定 enable_tracing=True。例如：

from vertexai.preview.reasoning_engines import LanggraphAgent

agent = LanggraphAgent(
    model=model,                # Required.
    tools=[get_exchange_rate],  # Optional.
    enable_tracing=True,        # [New] Optional.
)

LlamaIndex

如要啟用 LlamaIndexQueryPipelineAgent 的追蹤功能，請在開發 LlamaIndex 代理程式時指定 enable_tracing=True。例如：

from vertexai.preview import reasoning_engines

  def runnable_with_tools_builder(model, runnable_kwargs=None, **kwargs):
      from llama_index.core.query_pipeline import QueryPipeline
      from llama_index.core.tools import FunctionTool
      from llama_index.core.agent import ReActAgent

      llama_index_tools = []
      for tool in runnable_kwargs.get("tools"):
          llama_index_tools.append(FunctionTool.from_defaults(tool))
      agent = ReActAgent.from_tools(llama_index_tools, llm=model, verbose=True)
      return QueryPipeline(modules = {"agent": agent})

  agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
      model="gemini-2.0-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

自訂

如要為自訂代理程式啟用追蹤功能，請參閱「使用 OpenTelemetry 追蹤」一文。

這會將追蹤記錄匯出至「設定 Google Cloud 專案」中的專案下方的 Cloud Trace。

查看代理程式的追蹤記錄

您可以使用「追蹤記錄探索工具」查看追蹤記錄：

  1. 如要取得在 Google Cloud 控制台中查看追蹤記錄資料或選取追蹤記錄範圍的權限，請要求管理員授予您專案的 Cloud Trace 使用者 (roles/cloudtrace.user) IAM 角色。

  2. 前往 Google Cloud 控制台的「Trace Explorer」：

    前往 Trace 探索工具

  3. 在頁面頂端選取 Google Cloud 專案 (對應至 PROJECT_ID)。

詳情請參閱 Cloud Trace 說明文件。

配額與限制

如果屬性值達到配額限制，可能會遭到截斷。詳情請參閱「Cloud Trace 配額」。

定價

Cloud Trace 提供免費方案。詳情請參閱 Cloud Trace 定價。