使用 OpenTelemetry 檢測 LangGraph ReAct 代理程式

本文說明如何使用 OpenTelemetry 檢測 LangGraph ReAct 代理，以便從代理收集遙測資料。使用者提示、代理回覆和選項會以附加至 Span 的屬性形式，包含在遙測資料中。代理回覆也會包含在記錄項目中，這些項目與含有生成式 AI 事件的 span 相關。當代理使用 Langchain 的 ChatVertexAI 呼叫 Gemini 模型時，適用本文件中的操作說明。

使用 LangGraph ReAct 代理的應用程式，也可以收集多模態提示和回覆。本文說明如何收集文字提示詞和回覆。如要收集多模態資料，則須進行額外設定。詳情請參閱「收集及查看多模態提示和回覆」。

檢測生成式 AI 應用程式，收集遙測資料

如要檢測生成式 AI 應用程式，收集記錄、指標和追蹤記錄資料，請按照下列步驟操作：

1. 安裝 OpenTelemetry 套件
2. 設定 OpenTelemetry 以收集及傳送遙測資料
3. 追蹤生成式 AI 代理的叫用

安裝 OpenTelemetry 套件

新增下列 OpenTelemetry 檢測和匯出工具套件：

uv add 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-otlp-proto-grpc'

記錄、指標和追蹤記錄資料會透過Telemetry (OTLP) API 傳送至 Google Cloud ，該 API 會實作 OpenTelemetry Protocol。opentelemetry-exporter-otlp-proto-grpc 程式庫會叫用 Telemetry (OTLP) API 端點。

追蹤記錄資料的儲存格式，通常與 OpenTelemetry 通訊協定定義的 proto 檔案一致。不過，欄位可能會先從 OpenTelemetry 專屬資料類型轉換為 JSON 資料類型，再儲存。如要進一步瞭解儲存格式，請參閱「追蹤記錄資料的結構定義」。

設定 OpenTelemetry 來收集及傳送遙測資料

在 LangGraph 代理的初始化程式碼中，設定 OpenTelemetry 擷取遙測資料，並傳送至 Google Cloud 專案：

如要查看完整範例，請在範例的工具列中選取 GitHub 標誌。

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "langgraph-sql-agent",
            CLOUD_PROVIDER: "gcp",
            CLOUD_ACCOUNT_ID: project_id,
            # The project to send spans to
            "gcp.project_id": project_id,
            CLOUD_REGION: "us-central1",
            SERVICE_NAMESPACE: "local",
            SERVICE_INSTANCE_ID: "local-instance",
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(
            OTLPLogExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/logs",
            )
        )
    )
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(
        OTLPMetricExporter(
            credentials=channel_creds,
            endpoint="https://telemetry.googleapis.com:443/v1/metrics",
        )
    )
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

追蹤生成式 AI 代理的叫用

如要追蹤 LangGraph 代理叫用的執行作業，請在代理叫用周圍建立自訂 span：

如要查看完整範例，請在範例的工具列中選取 GitHub 標誌。

# Invoke the agent within a span
with tracer.start_as_current_span("invoke agent"):
    result = agent.invoke({"messages": [prompt]}, config=config)

建議您在應用程式程式碼的重要位置加入上述程式碼。

如要進一步瞭解如何新增自訂 Span 和指標，請參閱「在應用程式中新增自訂追蹤記錄和指標」。

執行範例

這個範例是 LangGraph 代理，已透過 OpenTelemetry 檢測，可將追蹤記錄和記錄 (含生成式 AI 提示和回覆) 以及指標傳送至Google Cloud 專案。

LangGraph 代理角色

LangGraph 代理定義為 SQL 專家，可完整存取臨時 SQLite 資料庫。代理是使用 LangGraph 預先建構的 ReAct 代理實作，並透過 SQLDatabaseToolkit 存取資料庫 (一開始為空白)。

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時不需要特定 IAM 角色，只要您獲派某個專案的角色，即可選取該專案。
• 建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，不要選取現有專案。如果採用這種做法，當您完成這些步驟後，就可以直接刪除該專案，並移除相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認 Google Cloud 專案已啟用計費功能。

啟用 Vertex AI、Service Usage、Telemetry、Cloud Logging、Cloud Monitoring 和 Cloud Trace API (如有尚未啟用的 API)：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時不需要特定 IAM 角色，只要您獲派某個專案的角色，即可選取該專案。
• 建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，不要選取現有專案。如果採用這種做法，當您完成這些步驟後，就可以直接刪除該專案，並移除相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認 Google Cloud 專案已啟用計費功能。

啟用 Vertex AI、Service Usage、Telemetry、Cloud Logging、Cloud Monitoring 和 Cloud Trace API (如有尚未啟用的 API)：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

1. 如要取得讓範例應用程式寫入記錄、指標和追蹤記錄資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

   • Cloud 遙測資料追蹤記錄寫入者 (roles/telemetry.tracesWriter)
   • 記錄檔寫入者 (roles/logging.logWriter)
   • Monitoring 指標寫入者 (roles/monitoring.metricWriter)
   • Vertex AI 使用者 (roles/aiplatform.user)

   如果您在 Cloud Shell、 Google Cloud 資源或本機開發環境中執行範例，這些權限就足夠。

   重要事項：正式版應用程式通常會依賴服務帳戶，提供寫入記錄、指標和追蹤資料所需的憑證。在這些情況下，請將先前的角色授予服務帳戶。

2. 請務必指定配額專案。Vertex AI API (aiplatform.googleapis.com) 必須指定配額專案。詳情請參閱「設定配額專案」。例如，下列指令可設定配額專案。

   gcloud config set billing/quota_project PROJECT_ID

執行範例

如要執行範例，請按照下列步驟操作：

1. 在 Cloud Shell 複製存放區：

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git
   

2. 前往範例目錄：

   cd opentelemetry-samples/python/langgraph-sql-agent
   

3. 設定環境變數：

   # Capture GenAI prompts and responses
   export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
   # Capture application logs automatically
   export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
   # Set the location to one that supports gemini-3.5-flash
   export GOOGLE_CLOUD_REGION=global
   

   如要改用其他模型，請編輯 main.py。請確認模型支援您指定的位置。如要瞭解模型，請參閱「Google 模型」。

4. 建立虛擬環境並執行範例：

   uv run main.py
   

   應用程式會顯示類似下列的訊息：

   Starting agent using ephemeral SQLite DB.
   

5. 如要建立資料庫，請在「Talk to the SQL agent >>」提示詞輸入值，然後按下 Enter 鍵。

   Cloud Shell 隨即會顯示代理執行的動作。

   以下是使用者與應用程式互動的範例：

   Talk to the SQL agent >> Create a new table to hold weather data.
   👤 User: Create a new table to hold weather data.
   🤖 Agent: Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
   
   CREATE TABLE weather (
     date DATE,
     location VARCHAR(255),
     temperature REAL,
     humidity REAL,
     precipitation REAL
   );
   
   🤖 Agent: I have created the weather table.
   👤 User: Add altitude to the table.
   🤖 Agent
   
   ALTER TABLE weather ADD COLUMN altitude REAL;
   
   

6. 如要退出，請輸入 Ctrl-C。

生成式 AI 代理執行的動作並非確定性，因此即使輸入相同的提示，也可能看到不同的回覆。

查看追蹤記錄、指標和記錄

本節說明如何查看生成式 AI 事件。

事前準備

如要取得查看記錄、指標和追蹤記錄資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 記錄檢視器 (roles/logging.viewer)
• Monitoring 檢視者 (roles/monitoring.viewer)
• Cloud Trace 使用者 (roles/cloudtrace.user)

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

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

查看遙測資料

如要查看生成式 AI 事件，請使用「Trace Explorer」頁面：

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

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

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

2. 在工具列中，依序選取「Add filter」(新增篩選器)、「Span name」(Span 名稱) 和「invoke agent」。

   「執行範例」一節包含執行範例，其中會將兩個提示傳送至應用程式。下圖顯示篩選資料後的「Trace Explorer」頁面：

   

   如果您從未使用過 Cloud Trace，Google Cloud Observability 必須建立資料庫來儲存追蹤記錄資料。建立資料庫可能需要幾分鐘，這段期間無法查看追蹤記錄資料。

3. 如要探索 Span 和記錄資料，請在「Spans」(Span) 表格中選取 Span。

   「Details」(詳細資料) 頁面隨即開啟。這個頁面會顯示相關聯的追蹤記錄及其 span。頁面上的表格會顯示所選時距的詳細資訊。這類資訊包括：

   • 「Inputs/Outputs」(輸入/輸出) 分頁會顯示生成式 AI 代理的事件。如要進一步瞭解這些事件，請參閱「查看生成式 AI 事件」。

     以下螢幕截圖顯示一項追蹤記錄，其中一個 span 的名稱為 invoke_agent。該 span 會叫用 Gemini。Gemini 跨距包含生成式 AI 事件：

     

   • 「Logs & Events」(記錄和事件) 分頁會列出與 Span 相關聯的記錄項目和事件。如要在 Logs Explorer 中查看記錄資料，請在這個分頁的工具列中選取「View logs」(查看記錄)。

     記錄資料包含 LangGraph 代理的回應。舉例來說，在範例執行作業中，JSON 酬載包含下列內容：

     {
       logName: "projects/my-project/logs/otel_python_inprocess_log_name_temp"
       jsonPayload: {
         message: {
           role: "model"
           content: [
             0: {
               text: "Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
     
               CREATE TABLE weather (
                   date DATE,
                   location VARCHAR(255),
                   temperature REAL,
                   humidity REAL,
                   precipitation REAL
               );
               "
             }
           ]
         }
       index: 0
       }
     ...
     }
     

範例會檢測並將指標資料傳送至 Google Cloud 專案，但不會產生任何指標。