Criar buckets de observabilidade

É possível criar manualmente o bucket de observabilidade _Trace antes que o projeto receba dados de trace para personalizar o local de armazenamento e as configurações de chave de criptografia gerenciada pelo cliente (CMEK). Se o projeto do Google Cloud ingerir dados de trace antes que esse bucket exista, o Google Cloud Observability vai provisionar automaticamente o bucket usando as configurações padrão do projeto para buckets de observabilidade.

Para informações sobre como o Google Cloud Observability armazena dados, consulte Visão geral do armazenamento.

Interação com políticas da organização

Uma solicitação para criar um bucket de observabilidade verifica se os parâmetros do comando estão em conformidade com as políticas da organização. Por exemplo, se uma política da organização restringir os locais de recursos, a criação de um bucket vai falhar se você especificar um local restrito.

Interação com as configurações padrão dos buckets de observabilidade

Quando o Google Cloud Observability cria automaticamente um bucket de observabilidade devido à ingestão de dados, ele usa as configurações padrão para buckets de observabilidade que se aplicam ao recurso pai do bucket. Essas configurações padrão podem ser definidas no pai ou em um ancestral hierárquico do pai e especificam o seguinte:

• O local de armazenamento.
• A chave do Cloud KMS a ser usada para os dados armazenados.

Ao criar um bucket de observabilidade, é necessário especificar um local. O Google Cloud Observability aplica a chave do Cloud KMS definida nas configurações padrão, a menos que você especifique explicitamente uma chave diferente na solicitação de criação.

Não é possível criar um bucket com criptografia padrão do Google se as configurações padrão aplicáveis especificarem uma chave do Cloud KMS. Para usar a criptografia padrão do Google, verifique se nenhuma chave do Cloud KMS está configurada nas configurações padrão.

Para informações sobre as configurações padrão dos buckets de observabilidade, consulte Definir padrões para buckets de observabilidade.

Limitações

As seguintes restrições são aplicadas:

• É necessário especificar um local compatível.
• O BUCKET_ID deve ser _Trace.
• O nome de exibição não pode exceder 100 bytes codificados.
• A descrição não pode exceder 1.000 bytes codificados.
• Os dados são armazenados por 30 dias. É necessário omitir o período de armazenamento ou defini-lo como 30.
• Se você fornecer uma chave do Cloud KMS, o local dela precisará corresponder exatamente ao local pai do bucket de observabilidade.
• Só é possível criar buckets de observabilidade em projetos do Google Cloud .
• Um projeto do Google Cloud pode ter no máximo um bucket de observabilidade chamado _Trace.

Antes de começar

Configure o projeto e os papéis do IAM e selecione a interface que você planeja usar.

Configurar o projeto e os papéis

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

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.

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, 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

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.

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, 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

1. Para receber as permissões necessárias para criar buckets 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.

Configurar interfaces

gcloud

Observação: use a CLI gcloud versão 586.0.0 ou mais recente.

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do console do 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.

Terraform

Para usar os exemplos do Terraform nesta 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. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

   gcloud auth application-default login

   Não é necessário fazer isso se você estiver usando o Cloud Shell.

   Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), 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 CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro 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 .

Configurar a chave do Cloud KMS

Opcional. Se você planeja criar um bucket de observabilidade e especificar uma chave do Cloud KMS, faça o seguinte:

1. Ative a API Cloud Key Management Service, se ainda não estiver ativada.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

2. Crie um keyring e chaves.

   O local do bucket de observabilidade precisa corresponder ao local da chave.

3. Substitua PROJECT_ID pelo ID do projeto e execute o seguinte comando:

   gcloud observability settings describe \
   --location=global --project=PROJECT_ID
   

   O comando anterior verifica se você configurou um local de armazenamento padrão. Ele também cria a conta de serviço do Google Cloud Observability quando ela não existe. A resposta do comando lista o ID da conta de serviço.

4. Conceda o papel Criptografador/Descriptografador de CryptoKey do Cloud KMS à conta de serviço do Google Cloud Observability.

   gcloud kms keys add-iam-policy-binding \
   --project=KMS_PROJECT_ID \
   --member=serviceAccount:[e-mail] \
   --role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
   --location=KMS_KEY_LOCATION \
   --keyring=KMS_KEY_RING \
   KMS_KEY_NAME
   

   Antes de executar o comando anterior, faça as seguintes substituições:

   • KMS_PROJECT_ID: o identificador alfanumérico exclusivo, composto pelo nome do projeto do Google Cloud e um número atribuído aleatoriamente, do projeto do Google Cloud que executa o Cloud KMS. Para saber como conseguir esse identificador, consulte Como identificar projetos.
   • service-PROJECT_NUMBER: o nome da conta de serviço de observabilidade que foi listada na resposta da etapa anterior.
   • KMS_KEY_LOCATION: a região da chave do Cloud KMS.
   • KMS_KEY_RING: o nome do keyring do Cloud KMS.
   • KMS_KEY_NAME: o nome da chave do Cloud KMS. Ele é formatado assim: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

Criar um bucket de observabilidade

gcloud

Observação: use a CLI gcloud versão 586.0.0 ou mais recente.

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.

O comando da CLI gcloud também oferece opções para definir o nome de exibição, a descrição e a chave do Cloud KMS. Para ver mais informações, consulte gcloud observability buckets create.

Execute o comando gcloud observability buckets create:

Linux, macOS ou Cloud Shell

gcloud observability buckets create BUCKET_ID \
 --location=LOCATION --project=PROJECT_ID

Windows (PowerShell)

gcloud observability buckets create BUCKET_ID `
 --location=LOCATION --project=PROJECT_ID

Windows (cmd.exe)

gcloud observability buckets create BUCKET_ID ^
 --location=LOCATION --project=PROJECT_ID

O comando create inicia uma operação de longa duração e bloqueia até que ela seja concluída. Confira a seguir um exemplo de resposta quando o comando é bem-sucedido:

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

Terraform

Para criar um bucket de observabilidade, use o recurso do Terraform google_observability_bucket e defina os seguintes campos:

• project: o ID do seu projeto.
• location: o local do bucket de observabilidade. Saiba mais em Locais.
• bucket_id: o ID do bucket de observabilidade. Esse campo precisa ser definido como _Trace.

Também é possível definir uma descrição e um nome de exibição, além de fornecer uma CMEK. Para mais informações, consulte a documentação do recurso.

REST

Para criar um bucket de observabilidade, envie uma solicitação para projects.locations.buckets.create.

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

O corpo da solicitação é um objeto Bucket. Preencha os seguintes campos:

• name: defina esse campo como:

  projects/PROJECT_ID/locations/LOCATION/buckets/_Trace
  

• Opcional: informe valores para os campos displayName e description.

• Opcional: forneça uma CMEK. Quando especificada, essa chave criptografa os dados armazenados.

  Se você não fornecer uma CMEK, as configurações padrão que se aplicam ao recurso pai do bucket vão determinar a chave de criptografia. Se as configurações padrão especificarem uma chave do Cloud KMS, ela criptografará os dados armazenados. Caso contrário, a criptografia padrão do Google será usada.

A resposta é um objeto Operation. Pesquise o método projects.locations.operations.get até que o campo Operation.done seja definido como true. Outros campos na estrutura Operation fornecem informações sobre o sucesso ou a falha da solicitação.

Listar buckets de observabilidade

É possível listar os buckets de observabilidade para verificar se a solicitação de criação foi concluída.

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

Observação: use a CLI gcloud versão 586.0.0 ou mais recente.

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.

A seguir

• Encontrar e analisar traces

• Consultar e analisar traces com SQL

• Definir padrões para buckets de observabilidade: configure um local de armazenamento padrão e uma chave de criptografia gerenciada pelo cliente (CMEK) padrão para seus buckets de observabilidade.