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

This document describes the storage model for Cloud Trace data. Itintroduces observability buckets, observability views, and links. If youcreate a link, then you can query your trace data from BigQuery.

This document doesn't describe the schema, which specifies how individualspans are stored. To learn more, seeTrace schema.

Observability storage model

The Observability API storage model relies on the following architecture:

Observability buckets

An observability bucket is the management entity for datasets, which storedata. An observability bucket is in a specific location and has a dataretention policy. When a Google Cloud service uses theObservability API to store their data, the system creates anobservability bucket based on the name of the service. For example, forthe Cloud Trace service, the system-created bucket is named_Trace.To learn about the structure of an observability bucket, seeBucket.

Datasets

A dataset is a storage entity. Each dataset is a child of anobservability bucket. When the system creates an observability bucket fora Google Cloud service, it also creates one dataset. For example, after thesystem creates the_Trace bucket, it creates the dataset namedSpans.That dataset stores your trace data. To learn about the structure of adataset, seeDataset.

Views on datasets

Each dataset hosts one or more view. Aview provides read access to asubset of entries in the dataset. When a dataset is created, the systemautomatically creates one view. That view includes all data in the dataset.The name of the view depends on the service. For example, for theCloud Trace service, the system creates a view named_AllSpanson theSpans dataset. To learn about the structure of a view, seeView.

Links on datasets

Each dataset can contain at most one link. When you create alink for adataset, the system creates a linked BigQuery dataset. Youcan then query the data in your dataset by using BigQueryor by other services that use the BigQuery API.To learn about the structure of a link, seeLink.

The system doesn't automatically create links on datasets.

Storage configuration for trace data

Your trace data is stored in an observability bucket named_Trace. The systemcreates a dataset namedSpans on this bucket. On that dataset, the systemcreates a view named_AllSpans. This view includes all data in the dataset.

The system makes a single attempt to create the bucket named_Tracewhen the bucket doesn't exist and either of the following are true:

• An application sends trace data to your Google Cloud project by using theCloud Trace API or the Telemetry API.

• You enable Cloud Trace for a Google Cloud service, and then that servicesends trace data to your Google Cloud project. For example, Cloud Service Meshsupports collecting traces; however, trace collection is disabled bydefault. If youenable tracing for Cloud Service Mesh,then the data sent by that service causes the system to create the bucket.

  Trace data generated by Cloud Run functions, Cloud Run, andApp Engine don't cause the system to create the observability bucket.Spans from these services are stored only when the observability bucket exists.

To determine whether the observability bucket named_Trace exists or to triggera flow that creates this bucket, do the following:

1. In the Google Cloud console, go to theTrace explorer page:

   Go toTrace explorer

   You can also find this page by using the search bar.

2. Do one of the following:

   • If the page displays trace data, then you don't need to do anything. YourGoogle Cloud project contains an observability bucket named_Trace.

   • If the page displays the following banner, then your doesn't have anytrace data, or it only has data from Cloud Run functions,Cloud Run, and App Engine.

     Tracestorageisnotinitializedforthisproject.Enabletracestoragetobegincollectingtracedata.

     If you want to trigger a flow that creates anobservability bucket named_Trace, then go to the banner and clickEnable.

   • If the page displays the following banner, then initialization of theobservability bucket named_Trace failed. If you this message, thengo to the banner and clickFile a ticket.

     Initializingtracestoragehasfailedforanunexpectedreason.Pleasefileasupportticketforassistance.

Limitations

You can't do the following:

• Modify or delete observability buckets.
• Create, delete, or modify datasets.
• Create, delete, or modify views.
• Use the Google Cloud console to list buckets, datasets, views, or links.
• Create observability buckets in the locations other than theus; anobservability bucket must be in theus location.

What's next

• To learn how to manage the storage for your trace data, seeManage trace storage.

• To learn more about using theTrace Explorer page, seeFind and explore traces.