Access traces and spans

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This document describes how to access and view traces and spans generated by your Gemini Enterprise app. Traces and spans provide detailed insights into the performance and execution flow of requests within your application, such as when using the assistant or agents.

You can view trace data using either the Trace Explorer or directly within individual agents using the agent's Traces tab.

Key concepts

This section introduces key concepts related to observability in Gemini Enterprise.

Concept	Description
Trace	A trace is a collection of spans that represents a single request or transaction as it flows through different services and components. For example, a trace represents the entire lifecycle of a request. This includes a user asking a question from the Gemini Enterprise assistant, the Gemini Enterprise assistant responding, and any subsequent actions triggered by the answer, such as sending an email.
Span	A span is a single, timed unit of work within a trace. It represents a specific operation, such as a function call, an API request, or a database query. Each span includes details like its start and end times, a unique ID, and its relationship to other spans. These relationships together form a trace.
Span logs	Span logs are timestamped, free-form messages or events associated with a specific span. They provide detailed, contextual information about a span's execution, helping users debug issues and understand the flow of a request.

Before you begin

Make sure you have the following:

• The Gemini Enterprise Admin role or Google Cloud console Gemini Enterprise User role.

• An existing Gemini Enterprise web app. For information about creating a new app, see Create an app.

• To access traces, you must have the Cloud Trace User role (roles/cloudtrace.user).

• In your Gemini Enterprise app configurations, enable the Enable instrumentation of OpenTelemetry traces and logs observability setting. For more information, see Manage observability settings.

Access traces in Trace Explorer

To access traces and spans using the Trace Explorer, follow these steps:

1. In the Google Cloud console, go to the Trace Explorer page.

   Go to Trace Explorer

2. Select the Google Cloud project where your Gemini Enterprise app was created. You see all the spans for your project.

3. In the table, click a Span ID to view the trace details, including the span's duration and other attributes.

   Note: For more information on using the Trace Explorer, see Find and explore traces.

   

Access traces for agents

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can also view trace spans directly for individual agents on the agent's Traces tab, which displays a detailed chronological summary of span trace records and parent-child execution structures.

Note: The Traces tab is only available for the Core Assistant agent at this time.

To access traces for an agent:

1. In the Google Cloud console, navigate to your app, and then click Agents.
2. Select the agent you want to inspect, and then click the Traces tab.

Trace summary table

The main table in the Traces tab shows the following information for each trace span:

• Status: The current status of the trace (currently displays Unset).
• Trace span ID: The unique identifier for the trace span. Click the span ID link to drill down into its details.
• Span Name: A brief description of the work the span is doing.
• Span Type: The type of span. Options include:
  • Agent to Tool: An invocation from the agent to an external tool.
  • Invoke Agent: An invocation of an agent.
  • Agent to Model: A request from the agent to a large language model.
• Duration: The time taken to complete the trace span (in minutes).
• Input: The input data or message sent to the span, if any.
• Output: The output result returned by the span, if any.
• Start Time: The exact timestamp when the span began execution.

Detailed trace view

Clicking a Trace span ID opens a detailed page featuring:

1. Summary: View the baseline metadata including Start time, Duration, and total Spans count. You can click to View in Cloud Trace or switch between Graph and Timeline view buttons.
2. Visualizations: Toggle between a graphical hierarchy or a timeline view showing parent-child relationships of all trace spans.
3. Selected span details: Select a single span to display detailed sections, which can include:
   • Summary: Displays the name of the span, target service, count of total spans with this action, and total duration (in seconds).
   • Logs: View relevant event details if configured. Click View logs to navigate directly to standard logs.
   • Evaluation: Shows any evaluation results, if configured.
   • Input & Output: Complete request and response payloads.
   • Logs & Events: List of events that occurred during this span execution.
   • Stacktraces: Error details if a span execution fails.
   • Metadata & Links: Links referencing related cloud explorer entities.
   • Attributes: Resource tags and additional key-value observability parameters.