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

# Google Cloud Trace

> Follow a request across your Google Cloud services to see where it broke.

Google Cloud Trace collects distributed traces from your Google Cloud projects: the spans a single request leaves as it moves through your services. Investigations retrieve a trace to follow one request end to end and see where it slowed down or failed.

<Note>
  Cloud Trace is connected through [Google Cloud](/investigations/connect/telemetry/google-cloud). Connect Google Cloud
  once, then enable the projects you want investigations to read. There's nothing to set up for Cloud Trace on its own.
</Note>

## What we support

Investigations retrieve a trace by its ID, scoped to a project. A trace ID usually comes from elsewhere in the investigation: a log line, an error, or an earlier metric query points at a specific request, and the trace shows what happened to it.

Once a trace is retrieved, investigations reconstruct it into the full picture of the request:

* **The span tree**: every span linked to its parent, so you can see which call led to which, where time was spent, and which service handed off to the next.
* **The services involved**: the set of services the request touched, drawn together from the trace so you can see its full path.
* **Where it failed**: spans flagged as errors, whether from a failing HTTP status, an explicit error label, or a recorded exception, so the broken step stands out rather than being buried in the tree.

A trace can answer questions like:

> Where did this request spend its time before it timed out?

> Which downstream service returned the error the user saw?

> How many services did this request pass through before it failed?

### Making sense of varied span data

Google Cloud services label their spans inconsistently. A Cloud Run service, a GKE container, an App Engine module, and an OpenTelemetry-instrumented service each name themselves differently, and errors show up under several different conventions. Investigations recognize these patterns, so a span gets attributed to the right service and an error is caught however it was recorded, instead of a trace reading as a wall of anonymous spans.

## Connecting Cloud Trace

Cloud Trace is connected through [Google Cloud](/investigations/connect/telemetry/google-cloud). Connect Google Cloud with a service account that can read traces, then enable the projects your team runs production workloads in. Each project is disabled by default, so you opt in deliberately; enabling one turns on its Cloud Trace access.

## Best practice

* Enable the projects your responders actually investigate, rather than every project the service account can reach.
* Grant the service account read-only trace access. Investigations only ever read from Cloud Trace.

## Related

<CardGroup cols={2}>
  <Card title="Google Cloud" icon="database" href="/investigations/connect/telemetry/google-cloud">
    The provider Cloud Trace is connected through.
  </Card>

  <Card title="How telemetry works" icon="magnifying-glass" href="/investigations/connect/telemetry/how-it-works">
    How investigations query your traces.
  </Card>
</CardGroup>