Gerenciar buckets de observabilidade

Este documento descreve como usar a API Observability para receber informações sobre seus buckets 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 trace são armazenados em buckets de observabilidade. Este documento descreve como gerenciar o armazenamento dos dados de trace, mas não descreve o formato dos dados armazenados. Para informações sobre esse tópico, consulte Esquema de trace.

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

Antes de começar

  1. Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

  2. Instale a Google Cloud CLI.

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

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

    gcloud init

  5. Crie ou selecione um Google Cloud projeto.

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar 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 resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Crie um Google Cloud projeto:

      gcloud projects create PROJECT_ID

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

    • Selecione o Google Cloud projeto que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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

  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 de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis. 

    gcloud services enable observability.googleapis.com

  8. Conceda 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 que você concede à sua conta de usuário.

  9. Instale a Google Cloud CLI.

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

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

    gcloud init

  12. Crie ou selecione um Google Cloud projeto.

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar 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 resourcemanager.projects.create permissão. Saiba como conceder papéis.

    • Crie um Google Cloud projeto:

      gcloud projects create PROJECT_ID

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

    • Selecione o Google Cloud projeto que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do Google Cloud projeto.

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

  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 de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis. 

    gcloud services enable observability.googleapis.com

  15. Conceda 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 que você concede à 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 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 seu 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.

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 projects.locations.buckets.datasets.list endpoint.

É necessário especificar o parâmetro pai, 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, esse ID pode ser _Trace.

A resposta é uma matriz de Dataset objetos. 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 pai 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",
    }
  ]
}

É possível emitir comandos para outros endpoints da API Observability para receber informações sobre o conjunto de dados cujo ID é DATASET_ID. Por exemplo, é possível listar 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.

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 projects.locations.buckets.datasets.views.list endpoint.

É necessário especificar o parâmetro pai, 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, esse ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, esse ID pode ser Spans.

A resposta é uma matriz de View objetos. Para cada objeto, o valor do campo name tem o seguinte formato:

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID

Na expressão 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 pai 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 para o projects.locations.buckets.datasets.links.list endpoint.

É necessário especificar o parâmetro pai, 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, esse ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, esse ID pode ser Spans.

A resposta é uma matriz de Link objetos. 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 o Google Cloud projeto.

Por exemplo, quando um comando foi emitido para o endpoint buckets.datasets.links.list com o parâmetro pai 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 que os dados de trace sejam consultados no BigQuery. Também é possível excluir o Link objeto 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 personalizados papéis ou outros predefinidos papéis.

Criar um conjunto de dados vinculado do BigQuery

REST

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

É necessário especificar o parâmetro pai, 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, esse ID pode ser _Trace.
  • DATASET_ID: o ID do conjunto de dados que está sendo consultado. Por exemplo, esse ID pode ser Spans.

Esse comando exige 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 o Google Cloud projeto, e limitado a 100 caracteres, podendo incluir apenas letras, dígitos e sublinhados.

  • O corpo da solicitação é um Link objeto. 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 Operation objeto. 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 Visualizar e analisar a telemetria.