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.

If you are using sinks to export trace data toBigQuery, thenthis document applies to you. The usage of sinks to export trace data is nolonger recommended. Instead, we recommend that you use Log Analytics, whichsupports the sameSQL query language as BigQuery.This document describes how to migrate from a sink-based solution to one thatuses Log Analytics. It also includes information about how to query yourtrace data by using BigQuery services.

To get started with Log Analytics, seeQuery and analyze traces.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

1. To get the permissions that you need to load theLog Analytics page, run queries, and createa linked dataset, ask your administrator to grant you the following IAM roles on your project:

   • Cloud Trace Admin (roles/cloudtrace.admin)
   • Observability Editor (roles/observability.editor)
   • BigQuery User (roles/bigquery.user)

   For more information about granting roles, seeManage access to projects, folders, and organizations.

   You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

2. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Migrate to Log Analytics

1. Completed the actions listed in theBefore you beginsection of this document. Those actions include enabling theObservability API.

2. Verify that you have access to your trace data by using Log Analytics:

   1. In the Google Cloud console, go to themanage_searchLog Analytics page:

      Go toLog Analytics

      If you use the search bar to find this page, then select the result whose subheading isLogging.

   2. In theViews menu, go to theTraces section,and then select_Trace.Spans._AllSpans.

      TheSchema pane is updated and displays the schema.

      If you don't see a view named_Trace.Spans._AllSpans, then yourGoogle Cloud project doesn't contain a observability bucketnamed_Trace. For information about how to resolve this situation,seeTrace storage initialization fails.

   3. In theSchema pane, selectQuery.

      The query editor field is updated. TheFROM clause lists anentry similar to the following:

      `PROJECT_ID.us._Trace.Spans._AllSpans`

   4. In the toolbar, selectRun Query.

      If the toolbar displaysRun in BigQuery, then clicksettingsSettings, and selectAnalytics (default).

   You have verified that you can query your trace data byusing theLog Analytics page.

3. Optional: If you want to join your trace data with other business data thatis available to BigQuery, then create a linkedBigQuery dataset. For more information, seeQuery a linked BigQuery dataset.

4. Delete trace sinks and unnecessary datasets:

   1. To list existing trace sinks, execute thegcloud alpha trace sinks list command:

      gcloudalphatracesinkslist

   2. For each sink, execute thegcloud alpha trace sinks delete command:

      gcloudalphatracesinksdeleteSINK_NAME

   3. Optional: Delete any unnecessary BigQuery datasets.For information about how to delete a BigQuery dataset,seeDelete datasets.

Schema comparison

This section provides information about the differences betweenLog Analytics and sink-based export schemas.

What's next

• Query and analyze traces.
• Sample queries.