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 da chave de criptografia gerenciada pelo cliente (CMEK). Se o seu Google Cloud projeto ingerir dados de trace antes da existência desse bucket, o Google Cloud Observability vai provisionar o bucket automaticamente 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 as 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 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 para 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 a 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 precisa 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 Google Cloud projetos.
  • Um Google Cloud projeto pode ter no máximo um bucket de observabilidade chamado _Trace.

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

    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 criar buckets de observabilidade, peça ao administrador para conceder a você o papel de Editor de observabilidade (roles/observability.editor) do IAM 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 receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Configurar interfaces

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

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 .

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.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter a 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, você pode receber essa permissão pelo papel de administrador de uso do serviço (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 beta 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 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:service-PROJECT_NUMBER@gcp-sa-observability. \
--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 Google Cloud projeto e um número atribuído aleatoriamente, do Google Cloud projeto que executa o Cloud KMS. Para informações sobre como receber esse identificador, consulte Identificação de projetos.
    • service-PROJECT_NUMBER: o nome da conta de serviço do Observability 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

REST

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

É necessário 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:

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

  • name: defina esse campo como o seguinte:

    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

  • Opcional: forneça 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, essa chave vai criptografar os dados armazenados. Caso contrário, a criptografia padrão do Google será usada.

A resposta é um Operation objeto. Consulte o projects.locations.operations.get método até que o Operation.done campo 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.

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 gcloud beta observability buckets list comando:

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

REST

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

É necessário 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 Bucket objetos. 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 pai 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
    }
  ]
}

É possível emitir comandos para outros endpoints da API Observability para receber mais informações sobre o bucket cujo ID é BUCKET_ID. Por exemplo, é possível listar os conjuntos de dados nesse bucket e as visualizações e 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.

A seguir