Criar buckets de observabilidade

É possível criar manualmente o bucket de observabilidade _Trace antes que seu projeto receba dados de rastreamento 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 rastreamento antes da criação desse bucket, o Google Cloud Observability vai provisionar automaticamente o bucket usando as configurações padrão para buckets de observabilidade do projeto.

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 de 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 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 elemento pai ou em um ancestral hierárquico dele 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, é preciso 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 suas 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 principal do bucket de observabilidade.
  • Só é possível criar buckets de observabilidade em projetos Google Cloud .
  • 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 as funções

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

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

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

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

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

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

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

    8.

  8. Para receber as permissões necessárias para criar 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 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 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 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.iam.gserviceaccount.com \
--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 Identificar 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

gcloud

Incompatível.

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. Para mais informações, consulte 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 e 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.

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:

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

  • name: defina este campo como:

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

Você pode listar os intervalos de observabilidade para verificar se a solicitação de criação foi concluída.

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

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

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