Menyiapkan pelacakan

Cloud Trace memungkinkan Anda menganalisis performa agen dengan melacak linimasa operasi untuk setiap kueri. Anda dapat menggunakan trace untuk mengidentifikasi bottleneck dan memahami interaksi dengan model bahasa besar (LLM) atau alat.

Dokumen ini menjelaskan cara mengaktifkan Trace untuk agen Anda dan cara melihat serta menganalisis trace di konsol Google Cloud .

Trace adalah linimasa permintaan saat agen Anda merespons setiap kueri. Misalnya, diagram berikut menunjukkan contoh trace dari agen Agent Development Kit (ADK):

Trace terdiri dari span individual, yang mewakili satu unit kerja, seperti panggilan fungsi atau interaksi dengan LLM, dengan span pertama mewakili permintaan keseluruhan. Setiap span memberikan detail tentang operasi tertentu, seperti nama operasi, waktu mulai dan berakhir, serta atribut yang relevan, dalam permintaan. Misalnya, JSON berikut menunjukkan satu span yang mewakili panggilan ke model bahasa besar (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": [],
  }

Catatan: Format trace dan span bergantung pada opsi instrumentasi yang Anda pilih. Span contoh bersifat eksperimental dan dapat berubah sewaktu-waktu, jadi Anda tidak boleh mengandalkan format yang stabil untuk saat ini. Untuk mengetahui detailnya, lihat Konvensi Semantik untuk sistem AI Generatif yang sedang dikembangkan di OpenTelemetry.

Untuk mengetahui detailnya, lihat dokumentasi Cloud Trace tentang Trace dan span serta Konteks trace.

Sebelum memulai

Sebelum dapat mengumpulkan dan menulis trace, Anda harus mengaktifkan API tertentu dan menginstal dependensi. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan dan melihat perintah dan respons multimodal dalam dokumentasi Google Cloud Observability.

Menulis trace untuk agen

Untuk menulis trace bagi agen:

ADK

Untuk mengaktifkan OpenTelemetry untuk AdkApp, tetapkan variabel lingkungan berikut saat Anda men-deploy agen ke Agent Runtime:

env_vars = {
  "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true",
  "OTEL_SEMCONV_STABILITY_OPT_IN": "gen_ai_latest_experimental",
  "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "EVENT_ONLY",
}

Perhatikan hal berikut:

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY mengaktifkan trace, log, dan metrik agen (lihat Melihat metrik untuk agen), tetapi tidak menyertakan perintah dan data respons.

• OTEL_SEMCONV_STABILITY_OPT_IN memungkinkan penggunaan konvensi semantik AI generatif terbaru.

• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT memungkinkan logging perintah input, respons output, dan ID pengguna (kolom user.id). Merekam detail ini memfasilitasi observabilitas agen dan deteksi anomali dengan melacak penggunaan dan interaksi dari waktu ke waktu.

  Catatan: Pastikan Anda memiliki izin, pemberitahuan, dan kebijakan penanganan data pengguna akhir yang diperlukan untuk pengumpulan informasi ini.
  Penting: Logging user.id disertakan saat memilih untuk "Mengaktifkan logging input perintah dan output respons" yang berlaku mulai 22 Mei 2026, dengan Agent Development Kit versi 2.1. Jika Anda memilih ikut serta sebelum 22 Mei, logging Anda tidak menyertakan user.id. Anda harus men-deploy ulang agen dan mengaktifkan kembali setelan ini agar dapat diterapkan.

• Untuk menggunakan penyerapan trace, Anda harus mengaktifkan Telemetry API. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Telemetry (OTLP) API.

• Untuk menggunakan penyerapan log, Anda harus mengaktifkan Cloud Logging API. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Cloud Logging API.

Catatan: Jika sebelumnya Anda menetapkan flag enable_tracing, sebaiknya gunakan variabel lingkungan. Misalnya, tetapkan GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true, bukan enable_tracing=true, dan tetapkan GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=false, bukan enable_tracing=false.

LangchainAgent

Untuk mengaktifkan pelacakan untuk LangchainAgent, tentukan enable_tracing=True saat Anda mengembangkan agen LangChain. Contoh:

from vertexai.agent_engines import LangchainAgent

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

LanggraphAgent

Untuk mengaktifkan pelacakan untuk LanggraphAgent, tentukan enable_tracing=True saat Anda mengembangkan agen LangGraph. Contoh:

from vertexai.agent_engines import LanggraphAgent

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

LlamaIndex

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Untuk mengaktifkan pelacakan untuk LlamaIndexQueryPipelineAgent, tentukan enable_tracing=True saat Anda mengembangkan agen LlamaIndex. Contoh:

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-3.5-flash",
      runnable_kwargs={"tools": [get_exchange_rate]},
      runnable_builder=runnable_with_tools_builder,
      enable_tracing=True,        # Optional
  )

Kustom

Untuk mengaktifkan pelacakan bagi agen kustom, buka Pelacakan menggunakan OpenTelemetry untuk mengetahui detailnya.

Tindakan ini akan mengekspor trace ke Cloud Trace di bagian project di Menyiapkan project Google Cloud .

Melihat trace untuk agen

Untuk agen yang di-deploy, Anda dapat menggunakan konsol Google Cloud untuk melihat trace agen:

1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.
   

   Buka Deployment

   Instance Agent Platform yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang Anda tentukan.

2. Klik nama instance Agent Platform Anda.

3. Klik tab Trace.

4. Anda dapat memilih Tampilan sesi atau Tampilan rentang.

   Klik sesi atau span untuk memeriksa detail trace, termasuk directed acyclic graph (DAG) span, input dan output, serta atribut metadata.

Kuota dan batas

Beberapa nilai atribut mungkin terpotong saat mencapai batas kuota. Untuk mengetahui informasi selengkapnya, lihat Kuota Cloud Trace.

Harga

Cloud Trace memiliki paket gratis. Untuk mengetahui informasi selengkapnya, lihat Harga Cloud Trace.