Gerenciar armazenamento de rastreamento

Este documento descreve como usar a API Observability para receber informações sobre o bucket de observabilidade que armazena seus dados de rastreamento. Ele inclui informações sobre como listar conjuntos de dados, links e visualizações. Para saber mais sobre como os dados de rastreamento são armazenados, consulte Visão geral do armazenamento de rastreamentos.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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 the resourcemanager.projects.create permission. Learn how to grant roles.

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 the serviceusage.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 the resourcemanager.projects.create permission. Learn how to grant roles.

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Para receber as permissões necessárias para listar buckets, links e visualizações, peça ao administrador para conceder a você o papel do IAM de Leitor de observabilidade (roles/observability.viewer) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Selecione a guia para como planeja usar as amostras nesta página:
gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.
Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Listar buckets de observabilidade

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

LOCATION: o local dos buckets de observabilidade. Para listar todos os buckets de observabilidade, independente do local, defina o local como um hífen (-).
PROJECT_ID: o identificador do projeto.

Execute o comando gcloud beta observability buckets list:

Linux, macOS ou Cloud Shell

gcloud beta observability buckets list \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

A resposta lista o nome, a descrição e a hora de criação de cada bucket de observabilidade. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

REST

Para listar os buckets de observabilidade que estão no seu projeto e em um local específico, envie uma solicitação ao endpoint projects.locations.buckets.list.

Você precisa especificar o parâmetro "parent", que tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION

Os campos na expressão anterior têm os seguintes significados:

PROJECT_ID: o identificador do projeto.
LOCATION: o local do bucket de observabilidade. Se você definir LOCATION como um hífen, (-), todos os buckets de observabilidade no projeto serão listados.

A resposta é uma matriz de objetos Bucket. Para cada objeto, o valor do campo name tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Por exemplo, quando um comando foi emitido para o endpoint buckets.list com o parâmetro "parent" definido como projects/my-project/locations/us, a resposta foi:

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

Você pode emitir comandos para outros endpoints da API Observability para receber mais informações sobre o bucket com o ID BUCKET_ID. Por exemplo, é possível listar os conjuntos de dados no bucket e as visualizações e links em cada conjunto. Para uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

Listar conjuntos de dados em um bucket de observabilidade

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.
LOCATION: o local dos buckets de observabilidade.
PROJECT_ID: o identificador do projeto.

Execute o comando gcloud beta observability buckets datasets list:

Linux, macOS ou Cloud Shell

gcloud beta observability buckets datasets list \
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets list `
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets list ^
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

A resposta lista o nome, a descrição e a hora de criação de cada conjunto de dados. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Dataset for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace/datasets/Spans

REST

Para listar os conjuntos de dados de um bucket de observabilidade, envie uma solicitação para o endpoint projects.locations.buckets.datasets.list.

Você precisa especificar o parâmetro "parent", que tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

Os campos na expressão anterior têm os seguintes significados:

PROJECT_ID: o identificador do projeto.
LOCATION: o local do bucket de observabilidade.
BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.

A resposta é uma matriz de objetos Dataset. Para cada objeto, o valor do campo name tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID

Por exemplo, quando um comando foi emitido para o endpoint buckets.datasets.list com o parâmetro "parent" definido como projects/my-project/locations/us/buckets/_Trace, a resposta foi:

{
  "datasets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans",
      "description": "Trace Spans",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

Você pode emitir comandos para outros endpoints da API Observability para receber informações sobre o conjunto de dados com ID DATASET_ID. Por exemplo, é possível listar as visualizações e os links em cada conjunto de dados. Para uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

Listar visualizações em um conjunto de dados

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

DATASET_ID: o ID do conjunto de dados. Seus dados de rastreamento são armazenados em um conjunto de dados chamado Spans.
BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.
LOCATION: o local dos buckets de observabilidade.
PROJECT_ID: o identificador do projeto.

Execute o comando gcloud beta observability buckets datasets views list:

Linux, macOS ou Cloud Shell

gcloud beta observability buckets datasets views list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID \
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets views list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID `
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets views list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID ^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

A resposta lista o nome, a hora de criação e a hora de atualização de cada visualização de observabilidade. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:

---
createTime: '2026-01-21T21:39:22.381083860Z'
displayName: _AllSpans
name: projects/pamstestproject1/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans
updateTime: '2026-01-21T21:39:22.381083860Z'

REST

Para listar as visualizações em um conjunto de dados, envie uma solicitação para o endpoint projects.locations.buckets.datasets.views.list.

Você precisa especificar o parâmetro "parent", que tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

Os campos na expressão anterior têm os seguintes significados:

PROJECT_ID: o identificador do projeto.
LOCATION: o local do bucket de observabilidade.
BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.
DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, o ID pode ser Spans.

A resposta é uma matriz de objetos View. Para cada objeto, o valor do campo name tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

No exemplo anterior, o ID de uma visualização é representado por OBS_VIEW_ID. Por exemplo, esse campo pode ter um valor de _AllSpans.

Por exemplo, quando um comando foi emitido para o endpoint buckets.datasets.views.list com o parâmetro "parent" definido como projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views, a resposta foi:

{
  "views": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans",
      "filter": "",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

Para uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

Listar links em um conjunto de dados

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

DATASET_ID: o ID do conjunto de dados. Seus dados de rastreamento são armazenados em um conjunto de dados chamado Spans.
BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.
LOCATION: o local dos buckets de observabilidade.
PROJECT_ID: o identificador do projeto.

Execute o comando gcloud beta observability buckets datasets links list:

Linux, macOS ou Cloud Shell

gcloud beta observability buckets datasets links list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets links list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets links list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

A resposta lista o nome e o horário de criação de cada link. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:

---
createTime: '2026-04-02T21:23:09.272323714Z'
name: projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/mydataset

REST

Para listar os links em um conjunto de dados, envie uma solicitação ao endpoint projects.locations.buckets.datasets.links.list.

Você precisa especificar o parâmetro "parent", que tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

Os campos na expressão anterior têm os seguintes significados:

PROJECT_ID: o identificador do projeto.
LOCATION: o local do bucket de observabilidade.
BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.
DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, o ID pode ser Spans.

A resposta é uma matriz de objetos Link. Para cada objeto, o valor do campo name tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/links/LINK_ID

O LINK_ID é o nome do conjunto de dados do BigQuery. Esse campo é globalmente exclusivo para seu projeto Google Cloud .

Por exemplo, quando um comando foi emitido para o endpoint buckets.datasets.links.list com o parâmetro "parent" definido como projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links, a resposta foi:

{
  "links": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/my_link",
      "description": "My link for traces to BigQuery",
      "createTime": "2025-01-12T15:42:30.988919645Z"
    }
  ]
}

Para uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

Criar um link em um conjunto de dados

Esta seção descreve como criar um link em um conjunto de dados, o que permite consultar seus dados de rastreamento no BigQuery.

Antes de começar

Conclua a configuração necessária para listar links.
Para receber as permissões necessárias para criar um link em um conjunto de dados, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:
- Editor de observabilidade (roles/observability.editor)
- Usuário do BigQuery (roles/bigquery.user)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar um conjunto de dados vinculado do BigQuery

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

LINK_ID: o nome do conjunto de dados do BigQuery.
DATASET_ID: o ID do conjunto de dados. Seus dados de rastreamento são armazenados em um conjunto de dados chamado Spans.
BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.
LOCATION: o local dos buckets de observabilidade.
PROJECT_ID: o identificador do projeto.

Execute o comando gcloud beta observability buckets datasets links create:

Linux, macOS ou Cloud Shell

gcloud beta observability buckets datasets links create \
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID \
 --dataset=DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

Windows (PowerShell)

gcloud beta observability buckets datasets links create `
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID `
 --dataset=DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta observability buckets datasets links create ^
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID ^
 --dataset=DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

O comando "create" inicia uma operação de longa duração. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:

Create request issued for: [mydataset]
Waiting for operation [projects/my-project/locations/us/operations/operation-1775164903749-64e80c9817833-9ff804b6-c3e9cbe7] to complete...done.
Created link [mydataset].

REST

Para criar um link para um conjunto de dados do BigQuery, envie uma solicitação ao endpoint projects.locations.buckets.datasets.links.create.

Você precisa especificar o parâmetro "parent", que tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

Os campos na expressão anterior têm o seguinte significado:

PROJECT_ID: o identificador do projeto.
LOCATION: o local do bucket de observabilidade.
BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, o ID pode ser _Trace.
DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, o ID pode ser Spans.

Esse comando requer um parâmetro de consulta e um corpo da solicitação:

O parâmetro de consulta, linkId, precisa ser especificado e definido como o nome do conjunto de dados do BigQuery. Por exemplo, linkId="my_link". O nome do conjunto de dados do BigQuery precisa ser exclusivo para seu projeto Google Cloud , ter no máximo 100 caracteres e incluir apenas letras, dígitos e sublinhados.
O corpo da solicitação é um objeto Link. O valor do campo name tem o seguinte formato:
```
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID/links/LINK_ID
```
O valor fornecido para o campo name precisa corresponder ao conjunto de dados vinculado do BigQuery referenciado pelo parâmetro de consulta.

O campo LINK_ID é o nome do conjunto de dados do BigQuery.

A resposta é um objeto Operation. Esse objeto contém informações sobre o progresso do método. Quando o método é concluído, o objeto Operation contém dados de status.

Para uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

A seguir

Para saber mais sobre como usar a página Explorador de traces, consulte Encontrar e explorar traces.

Para saber como analisar seus intervalos de rastreamento com SQL, consulte Consultar e analisar rastreamentos.

Gerenciar armazenamento de rastreamento Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

gcloud

REST

Listar buckets de observabilidade

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

Listar conjuntos de dados em um bucket de observabilidade

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

Listar visualizações em um conjunto de dados

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

Listar links em um conjunto de dados

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

Criar um link em um conjunto de dados

Antes de começar

Criar um conjunto de dados vinculado do BigQuery

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

A seguir

Gerenciar armazenamento de rastreamento