Atualizar buckets de observabilidade

É possível atualizar o nome de exibição, a descrição ou a chave do Cloud Key Management Service de um bucket de observabilidade para refletir mudanças organizacionais ou alternar chaves de criptografia.

Não é possível usar essas operações de atualização para resolver problemas de compliance. Por exemplo, não é possível usar essas operações para mudar o local de um bucket de observabilidade ou aplicar uma chave do Cloud KMS a um bucket que usa a criptografia padrão do Google.

Efeitos da atualização de uma chave do Cloud KMS

A atualização da chave do Cloud KMS de um bucket de observabilidade não afeta os dados armazenados. Ou seja, antes da conclusão da atualização, a chave original criptografa novos dados. Depois que a atualização for concluída, a chave atualizada vai criptografar os novos dados.

Você pode continuar acessando e visualizando os dados armazenados desde que a chave original do Cloud KMS permaneça ativada e a conta de serviço do Google Cloud Observability mantenha as permissões de criptografia/descriptografia.

Se você desativar ou destruir a chave original do Cloud KMS, todos os dados gravados enquanto ela estava ativa vão ficar permanentemente inacessíveis e ilegíveis.

Limitações

As seguintes restrições são aplicadas:

• Não é possível modificar o local.
• Não é possível aplicar uma chave do Cloud KMS a um bucket de observabilidade que usa a criptografia padrão do Google.
• 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. É possível omitir o período de armazenamento ou defini-lo como 30.
• Se você atualizar a chave do Cloud KMS, o local dela precisará corresponder exatamente ao local principal do bucket de observabilidade.

Antes de começar

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

Configurar o projeto e as funções

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.

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

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 atualizar os intervalos de observabilidade, peça ao administrador para conceder a você o papel do IAM de Editor de observabilidade (roles/observability.editor) 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.

Configurar interfaces

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.

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 (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Para mais informações, consulte 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 nesta 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 atualizar a chave do Cloud KMS usada pelo bucket de observabilidade, faça o seguinte:

1. Ative a API Cloud Key Management Service.

   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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

2. Crie um keyring e uma chave.

   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 beta observability settings describe \
   --location=global --project=PROJECT_ID
   

   A resposta ao comando anterior lista o ID da conta de serviço do Google Cloud Observability.

4. Conceda o papel Criptografador/Descriptografador do Cloud KMS CryptoKey à 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 em execução no Cloud KMS. Para informações sobre como conseguir esse identificador, consulte Como identificar projetos.
   • service-PROJECT_NUMBER: o nome da conta de serviço do Google Cloud Observability listada na 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.

Atualizar um bucket de observabilidade

gcloud

Incompatível.

Terraform

Para atualizar o nome de exibição, a descrição ou a CMEK, 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. Para mais informações, consulte Locais.
• bucket_id: o ID do bucket de observabilidade. Esse campo precisa ser definido como _Trace.

É possível atualizar apenas a descrição, o nome de exibição e a CMEK. Para mais informações, consulte a documentação do recurso.

REST

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

É necessário especificar o parâmetro "parent", que identifica o bucket a ser atualizado. Esse parâmetro 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.

O parâmetro de consulta precisa especificar um campo updateMask, que identifica quais campos serão modificados. Exemplo:

• Para atualizar a descrição, use updateMask=description.
• Para atualizar a chave do Cloud KMS e a descrição, use updateMask=description,cmekSettings.kmsKey.

O corpo da solicitação é um objeto Bucket. É necessário preencher todos os campos especificados pela máscara de atualização. Não preencha campos que não estão sendo atualizados.

Por exemplo, para atualizar apenas o campo description, use o seguinte objeto Bucket:

{
    "description": "Updated description for my observability bucket."
}

A resposta é um objeto Operation. Normalmente, esse método leva menos de um minuto para ser concluído.

Normalmente, para determinar se um método que retorna um objeto Operation está concluído, você pesquisa o objeto chamando projects.locations.operations.get até que o campo Operation.done seja definido como true. Em seguida, use outros campos na estrutura Operation para determinar se o método foi bem-sucedido ou falhou.

No entanto, o método patch é concluído rapidamente. Portanto, uma alternativa é aguardar um minuto e verificar a atualização listando seus buckets de observabilidade.

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

gcloud

Observação: é preciso usar a CLI gcloud versão 563.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, 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

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.

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 seu 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 mais informações sobre o bucket com ID BUCKET_ID. Por exemplo, é possível listar os conjuntos de dados no bucket e as visualizações e links em cada conjunto. Para mais informações, consulte a documentação de referência da API Observability.

A seguir

• Ver e analisar a telemetria
• 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.