Listar buckets e gerenciar conjuntos de dados de observabilidade

É possível usar a API Observability ou a Google Cloud CLI para listar seus buckets, conjuntos de dados, visualizações e links de observabilidade, além de criar links do BigQuery para analisar dados armazenados com SQL. Para criar links, também é possível usar o Terraform.

os conjuntos de dados de observabilidade armazenam seus dados de trace. Para informações sobre o armazenamento de registros e métricas ou o formato de dados de trace, consulte Visão geral do armazenamento de telemetria e Esquema de trace.

Antes de começar

Antes de gerenciar o armazenamento de observabilidade, configure o projeto e os papéis do Identity and Access Management (IAM) e escolha a interface que você planeja usar.

Configurar o projeto e os papéis

  1. 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

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Observability API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. 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 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 interface que você quer usar

gcloud

Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

gcloud init

Terraform

Para usar os exemplos do Terraform desta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

  1. Instale a CLI do Google Cloud.

  2. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

  3. Crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Se um erro de autenticação for retornado, confirme se você fez login na CLI gcloud com sua identidade federada.

Saiba mais em Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

    Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Listar buckets de observabilidade

Nesta seção, descrevemos como listar seus buckets de observabilidade. Um bucket de observabilidade é a entidade de gerenciamento de conjuntos de dados, que armazenam dados.

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, independentemente do local, defina o local como um hífen (-).
  • PROJECT_ID: o identificador do projeto.

Execute o comando gcloud observability buckets list:

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

A resposta lista o nome, a descrição e o horário 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

Terraform

Não é possível usar o Terraform para listar buckets de observabilidade.

REST

Para listar os buckets de observabilidade que estão no seu projeto e em um local específico, use o método projects.locations.buckets.list.

É preciso especificar o parâmetro pai, 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

Confira um exemplo de resposta:

{
  "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
    }
  ]
}

Use a API Observability para receber mais informações sobre o bucket com o ID BUCKET_ID. Por exemplo, é possível listar os conjuntos de dados nesse bucket, além das visualizações e dos links em cada conjunto de dados. Para mais informações, consulte a documentação de referência da API Observability.

Listar conjuntos de dados em um bucket de observabilidade

Nesta seção, descrevemos como listar os conjuntos de dados de observabilidade em um bucket de observabilidade. Um bucket de observabilidade é o contêiner de gerenciamento de conjuntos de dados, que armazenam dados. Quando o Google Cloud Observability cria um bucket, ele cria automaticamente um conjunto de dados.

gcloud

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

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

Execute o comando gcloud observability buckets datasets list:

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

gcloud 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 o horário de criação de cada conjunto de dados. Veja 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

Terraform

Não é possível usar o Terraform para listar conjuntos de dados de observabilidade.

REST

Para listar os conjuntos de dados de um bucket de observabilidade, use o método projects.locations.buckets.datasets.list.

É preciso especificar o parâmetro pai, 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, esse 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/datasets/DATASET_ID

Confira um exemplo de resposta:

{
  "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",
    }
  ]
}

Use a API Observability para receber informações sobre o conjunto de dados com o ID DATASET_ID. Por exemplo, é possível listar as visualizações e os links em cada conjunto de dados. Para mais informações, consulte a documentação de referência da API Observability.

Visualizações em lista em um conjunto de dados

Nesta seção, descrevemos como listar suas visualizações de observabilidade. Cada conjunto de dados de observabilidade hospeda uma ou mais visualizações. Uma visualização fornece acesso de leitura a um subconjunto de entradas no conjunto de dados. O Google Cloud Observability cria uma visualização quando cria um conjunto de dados. Essa visualização inclui todos os dados do conjunto.

gcloud

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

  • DATASET_ID: o ID do conjunto de dados. Os dados de trace são armazenados em um conjunto de dados chamado Spans.
  • BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, esse ID pode ser _Trace.
  • LOCATION: o local do bucket de observabilidade.
  • PROJECT_ID: o identificador do projeto.

Execute o comando gcloud observability buckets datasets views list:

Linux, macOS ou Cloud Shell

gcloud 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 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 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, o horário de criação e o horário 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'

Terraform

Não é possível usar o Terraform para listar visualizações de observabilidade.

REST

Para listar as visualizações em um conjunto de dados, use o método projects.locations.buckets.datasets.views.list.

É preciso especificar o parâmetro pai, 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, esse ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, esse 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/datasets/DATASET_ID/views/OBS_VIEW_ID

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

Confira um exemplo de resposta:

{
  "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 mais informações, consulte a documentação de referência da API Observability.

Nesta seção, descrevemos como listar os links nos conjuntos de dados de observabilidade. Um link pode permitir que você consulte seus dados usando os serviços do BigQuery ou que um serviço do Google Cloud consulte um subconjunto desses dados.

gcloud

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

  • DATASET_ID: o ID do conjunto de dados. Os dados de trace são armazenados em um conjunto de dados chamado Spans.
  • BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, esse ID pode ser _Trace.
  • LOCATION: o local do bucket de observabilidade.
  • PROJECT_ID: o identificador do projeto.

Execute o comando gcloud observability buckets datasets links list:

Linux, macOS ou Cloud Shell

gcloud 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 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 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. Veja 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

Terraform

Não é possível usar o Terraform para listar links em conjuntos de dados de observabilidade.

REST

Para listar os links em um conjunto de dados, use o método projects.locations.buckets.datasets.links.list.

É preciso especificar o parâmetro pai, 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, esse ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, esse 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/datasets/DATASET_ID/links/LINK_ID

LINK_ID é o nome do conjunto de dados do BigQuery. Esse campo precisa ser exclusivo no projeto do Google Cloud .

Confira um exemplo de resposta:

{
  "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 mais informações, consulte a documentação de referência da API Observability.

Nesta seção, descrevemos como criar um conjunto de dados vinculado do BigQuery em um conjunto de dados de observabilidade, o que permite usar os serviços do BigQuery para consultar seus dados de trace. Cada conjunto de dados de observabilidade é compatível com um conjunto de dados vinculado do BigQuery.

Quando você cria um link em um conjunto de dados de observabilidade, ocorre o seguinte:

  • O Google Cloud Observability pode criar as seguintes contas de serviço ou modificar as concessões de papel do IAM:

  • Os registros de auditoria registram a solicitação para criar um link e a solicitação do gerenciador de agentes de serviço para conceder à conta de serviço do Monitoring o papel do IAM de Agente de serviço do Monitoring. Esses registros também registram a conclusão da operação de longa duração.

Antes de começar

  1. 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

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Cloud Monitoring and Observability APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. Para receber as permissões necessárias para criar um link em um conjunto de dados de observabilidade, peça ao administrador para conceder a você o papel do IAM de Editor de observabilidade (roles/observability.editor) no 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.

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. Os dados de trace são armazenados em um conjunto de dados chamado Spans.
  • BUCKET_ID: o ID do bucket de observabilidade. Por exemplo, esse ID pode ser _Trace.
  • LOCATION: o local do bucket de observabilidade.
  • PROJECT_ID: o identificador do projeto.

Execute o comando gcloud observability buckets datasets links create:

Linux, macOS ou Cloud Shell

gcloud 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 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 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. Veja 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].

Terraform

Para criar um link em um conjunto de dados de observabilidade, use o recurso do Terraform google_observability_link e defina os seguintes campos:

  • project: o ID do seu projeto.
  • location: o local do link. Esse local precisa corresponder ao local do bucket de observabilidade.
  • bucket: o ID do bucket de observabilidade. Por exemplo, _Trace.
  • dataset: o ID do conjunto de dados de observabilidade. Por exemplo, Spans.
  • link_id: ID do conjunto de dados do BigQuery.

Também é possível atualizar e excluir links.

REST

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

É preciso especificar o parâmetro pai, 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, esse ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, esse ID pode ser Spans.

Esse comando requer um parâmetro de consulta e um corpo de 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 o projeto do Google Cloud , ser limitado a 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/datasets/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 de API Observability, consulte a documentação de referência da API Observability.

Se você encontrar erros de permissão ao criar um conjunto de dados vinculado, consulte Resolver erros de permissão.

A seguir