> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idun-group.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Trace

> Set up Google Cloud Trace to capture distributed traces and analyze agent latency.

Set up Google Cloud Trace to capture distributed traces from your agents and analyze latency in the Google Cloud Console.

<Tip>
  Before starting, complete the [quickstart guide](/quickstart) to have an agent running on Idun Engine.
</Tip>

## Set up GCP Trace observability

<Steps>
  <Step title="Prepare your Google Cloud project">
    1. Create a Google Cloud project if you do not have one
    2. Enable the **Cloud Trace API** in your project
    3. Verify that the environment where your agent runs has credentials with permission to write traces (the `Cloud Trace Agent` role)

    <Tabs>
      <Tab title="Running on Google Cloud">
        If running on Cloud Run, GKE, or Compute Engine, the default service account typically has the required permissions if scopes are configured.
      </Tab>

      <Tab title="Running locally or elsewhere">
        Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to your service account key file, or configure application default credentials.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create an observability configuration">
    1. On the Idun Engine main page, navigate to **Observability**
    2. Click **Add configuration**
    3. Select **GCP Trace**
    4. Enter a **Configuration Name** (for example, "GCP Trace Prod")
    5. Fill in the required details:
       * **Project ID**: Your Google Cloud Project ID (for example, `my-project-123`)
       * **Region**: (Optional) Specific region if applicable
       * **Trace Name**: (Optional) Name for the trace session
       * **Sampling Rate**: A number between 0.0 and 1.0 (for example, `1.0` for 100% sampling)
       * **Flush Interval**: Time in seconds to wait before sending traces (default `5`)
       * **Ignore URLs**: (Optional) Paths to exclude from tracing
    6. Click **Create configuration**
  </Step>

  <Step title="Attach GCP Trace to your agent">
    1. Navigate to the agent you want to trace
    2. Click **Edit Agent**
    3. Click **Next** to reach the observability configuration step
    4. Select **GCP Trace** as the observability provider
    5. Select the configuration you created
    6. Click **Next**
    7. Click **Save changes** to finalize

    After saving, click **Restart** on your agent page to reload the configuration.
  </Step>
</Steps>

## View trace data

Once your agent is running with observability enabled:

1. Interact with your agent
2. Open the [Google Cloud Console](https://console.cloud.google.com/)
3. Navigate to **Trace** > **Trace List**

You will see traces from your agent's execution. Use these to analyze latency and find bottlenecks.

## Best practices

* **Adjust sampling rate**: For high-traffic agents, lower the sampling rate to reduce costs and noise
* **Use meaningful trace names**: This helps when filtering traces in the GCP Console

## Troubleshooting

<AccordionGroup>
  <Accordion title="Traces not showing up?">
    1. **Check API**: Verify the Cloud Trace API is enabled in your project
    2. **Check permissions**: Confirm the agent's service account has the `Cloud Trace Agent` role
    3. **Wait for flush**: Traces are sent in batches. Wait a few seconds (based on your flush interval) after execution before checking the console
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="GCP Logging" icon="file-text" horizontal href="/observability/gcp-logging">
  Pair tracing with structured logs in Google Cloud Logging.
</Card>

<Card title="Local trace store" icon="database" horizontal href="/observability/traces">
  Inspect the same agent runs in the bundled admin UI.
</Card>

<Card title="Deploy to Cloud Run" icon="cloud" horizontal href="/standalone/cloud-run">
  Run the standalone next to your traces with managed Postgres.
</Card>