Gerenciar buckets de observabilidade

Este documento descreve como usar a API Observability para receber informações sobre seus intervalos de observabilidade. Ele também inclui informações sobre como listar conjuntos de dados, links e visualizações. Para saber mais sobre como o Google Cloud Observability armazena dados, consulte Visão geral do armazenamento.

Os dados de rastreamento são armazenados em buckets de observabilidade. Este documento descreve como gerenciar o armazenamento dos dados de rastreamento, mas não o formato dos dados armazenados. Para informações sobre esse tópico, consulte Esquema de rastreamento.

Este documento não se aplica ao armazenamento de dados de registros ou métricas. Os dados de registros e métricas não são armazenados em buckets de observabilidade.

Antes de começar

  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. Instale a CLI do Google Cloud.

  3. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  4. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  5. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

    • Selecione o projeto Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  6. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  7. Ative a API Observability:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

    gcloud services enable observability.googleapis.com

  8. Atribua papéis à sua conta de usuário. Execute o seguinte comando uma vez para cada um dos seguintes papéis do IAM: roles/observability.viewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • USER_IDENTIFIER: o identificador da sua conta de usuário . Por exemplo, myemail@example.com.
    • ROLE: o papel do IAM concedido à sua conta de usuário.

  9. Instale a CLI do Google Cloud.

  10. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

  11. Para inicializar a gcloud CLI, execute o seguinte comando: 

    gcloud init

  12. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

    • Selecione o projeto Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  13. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  14. Ative a API Observability:

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

    gcloud services enable observability.googleapis.com

  15. Atribua papéis à sua conta de usuário. Execute o seguinte comando uma vez para cada um dos seguintes papéis do IAM: roles/observability.viewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • USER_IDENTIFIER: o identificador da sua conta de usuário . Por exemplo, myemail@example.com.
    • ROLE: o papel do IAM concedido à sua conta de usuário.
    16.

Listar buckets de observabilidade

REST

Para listar os buckets de observabilidade que estão no seu projeto e em um local específico, envie uma solicitação ao endpoint 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 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

Por exemplo, quando um comando foi emitido para o endpoint buckets.list com o parâmetro "parent" 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
    }
  ]
}

Você pode emitir comandos para outros endpoints da API Observability para receber mais informações sobre o bucket com o ID BUCKET_ID. Por exemplo, é possível listar os conjuntos de dados no bucket e as visualizações e links em cada conjunto. Para uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

Listar conjuntos de dados em um bucket de observabilidade

REST

Para listar os conjuntos de dados de um bucket de observabilidade, envie uma solicitação para o endpoint projects.locations.buckets.datasets.list.

Você precisa especificar o parâmetro "parent", 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, o 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/dataset/DATASET_ID

Por exemplo, quando um comando foi emitido para o endpoint buckets.datasets.list com o parâmetro "parent" definido como projects/my-project/locations/us/buckets/_Trace, a resposta foi:

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

Você pode emitir comandos para outros endpoints da API Observability para receber informações sobre o conjunto de dados com ID DATASET_ID. Por exemplo, é possível listar as visualizações e os 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.

Listar visualizações em um conjunto de dados

REST

Para listar as visualizações em um conjunto de dados, envie uma solicitação para o endpoint projects.locations.buckets.datasets.views.list.

Você precisa especificar o parâmetro "parent", 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, o ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, o 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/views/OBS_VIEW_ID

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

Por exemplo, quando um comando foi emitido para o endpoint buckets.datasets.views.list com o parâmetro "parent" definido como projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views, a resposta foi:

{
  "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 uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

REST

Para listar os links em um conjunto de dados, envie uma solicitação ao endpoint projects.locations.buckets.datasets.links.list.

Você precisa especificar o parâmetro "parent", 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, o ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, o 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/links/LINK_ID

O LINK_ID é o nome do conjunto de dados do BigQuery. Esse campo é globalmente exclusivo para seu projeto Google Cloud .

Por exemplo, quando um comando foi emitido para o endpoint buckets.datasets.links.list com o parâmetro "parent" definido como projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links, a resposta foi:

{
  "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 uma lista completa de endpoints da API Observability, consulte a documentação de referência da API Observability.

É possível criar um link em um conjunto de dados, o que permite consultar os dados de rastreamento no BigQuery. Também é possível excluir o objeto Link anexado a um conjunto de dados.

Para receber as permissões necessárias para criar um link em um conjunto de dados, peça ao administrador para conceder a você os seguintes papéis 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 conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar um conjunto de dados vinculado do BigQuery

REST

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

Você precisa especificar o parâmetro "parent", que tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

Os campos na expressão anterior têm o seguinte significado:

  • 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.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, o ID pode ser Spans.

Esse comando requer um parâmetro de consulta e um corpo da 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 seu projeto Google Cloud , ter no máximo 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/dataset/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 da API Observability, consulte a documentação de referência da API Observability.

A seguir

Para saber como consultar sua telemetria, consulte Ver e analisar a telemetria.