Crie e faça a gestão de âmbitos de registo

Este documento descreve como pode criar e gerir âmbitos de registo, que pode usar para ajudar a encontrar de forma eficiente as entradas de registo que quer ver ou analisar. Se quiser apenas ver e analisar as entradas de registo que têm origem num projeto, numa pasta ou numa organização, este documento não é para si. No entanto, se usar destinos de registo para encaminhar registos para outros projetos ou para contentores de registos definidos pelo utilizador, ou se usar vistas de registos, as informações neste documento podem ajudar a encontrar entradas de registo específicas de forma eficiente.

Este documento não descreve como ver os registos. Para ver informações sobre esse tópico, consulte o artigo Veja registos através do Explorador de registos.

Acerca dos âmbitos dos registos

Os âmbitos dos registos são recursos persistentes ao nível do projeto que apresentam um conjunto de recursos. Estes recursos podem ser projetos, pastas, organizações e visualizações de registos. Por exemplo, pode definir um âmbito de registo que liste os projetos que contêm recursos usados para produção ou um que liste as visualizações de registos que incluem entradas de registos para um tipo de recurso específico.

Quando cria um Trusted Cloud recurso de projeto, pasta ou organização, o Logging cria um âmbito de registo denominado _Default. Este âmbito inclui o projeto, a pasta ou a organização que foi criada. Quando um recurso pesquisado é um Trusted Cloud projeto, uma pasta ou uma organização, os resultados incluem as entradas de registo que têm origem no recurso e são, em seguida, armazenadas num contentor de registos. O contentor de registos pode estar em qualquer projeto. Quando um projeto é pesquisado, os resultados também incluem entradas de registo que são encaminhadas para o projeto por um destino noutro projeto e, em seguida, armazenadas num contentor de registos.

Pode criar âmbitos de registo. Também pode editar e eliminar os âmbitos de registo que criar. No entanto, não pode editar nem eliminar o âmbito do registo denominado _Default.

Usa um âmbito de registo para controlar os recursos que a página do Explorador de registos pesquisa para encontrar dados de registo. Quando abre essa página e seleciona um âmbito de registo, a página pesquisa os recursos listados nesse âmbito e, em seguida, atualiza a apresentação.

Para projetos, o âmbito do registo predefinido determina o conjunto de recursos que a página do Explorador de registos pesquisa quando é aberta. No entanto, as suas funções de gestão de identidade e de acesso (IAM) nos recursos pesquisados e a definição do intervalo de tempo determinam que entradas de registo são obtidas do armazenamento. Quando os projetos são criados, o âmbito do registo denominado _Default é designado como o âmbito do registo predefinido.

Como é que os âmbitos dos registos diferem do armazenamento de registos centralizado

O armazenamento de registos centralizado e os âmbitos de registos permitem-lhe ver dados de registos originários de diferentes projetos.

Quando centraliza o armazenamento de registos, configura os destinos numa organização ou numa pasta para encaminhar as entradas de registo para uma única localização de armazenamento. O armazenamento centralizado oferece um único local para consultar dados de registo, o que simplifica as suas consultas quando procura tendências ou investiga problemas. Do ponto de vista da segurança, também tem uma localização de armazenamento, o que simplifica as tarefas dos seus analistas de segurança.

Quando uma consulta é emitida para os recursos listados num âmbito do registo, os resultados da consulta individuais são combinados. Um âmbito de registo facilita a agregação em tempo de leitura dos dados de registo que podem ser armazenados em localizações diferentes. No entanto, um âmbito de registo também pode ser usado para fornecer acesso de leitura a uma ou mais vistas de registos num contentor de registos centralizado.

Quando a página do Explorador de registos é aberta, envia consultas aos recursos indicados no âmbito do registo predefinido. Por conseguinte, configure o âmbito predefinido para que a página lhe mostre os dados que normalmente quer ver. Por exemplo, pode definir o âmbito do registo predefinido para apresentar uma vista de registo que, quando consultada, devolve os dados de registo de uma aplicação do App Hub.

Práticas recomendadas

Uma vez que os âmbitos dos registos lhe permitem definir e guardar uma configuração para utilização futura, recomendamos que crie âmbitos dos registos para configurações de pesquisa complexas.

Por exemplo, suponha que está a resolver um problema e quer ver as entradas de registo de todas as instâncias de máquinas virtuais (VMs) pertencentes à sua equipa. Para concluir esta tarefa, pode fazer o seguinte:

  1. Determina que as entradas de registo que quer ver estão armazenadas em vários contentores de registos e em vários projetos. Para a maioria dos contentores de registos, existe uma vista de registos que inclui as entradas de registos que quer analisar. Quando não existir uma vista de registo, pode criar uma.

  2. Decide criar um âmbito de registo porque espera ter uma tarefa de resolução de problemas semelhante no futuro.

  3. Abra a página Explorador de registos na Trusted Cloud consola e, de seguida, use o menu Refinar âmbito para selecionar o novo âmbito do registo.

  4. Reveja as entradas do registo e encontre as informações de que precisa para resolver o problema que estava a investigar.

  5. Depois de resolver o problema, partilha a causa da falha com os seus colegas. Também partilha que espera ver falhas semelhantes no futuro, pelo que criou um âmbito de registo que lhe permite, ou a quem estiver a investigar a falha, encontrar rapidamente entradas de registo relevantes.

Aplicações do App Hub e âmbitos de registo

As suas aplicações do App Hub podem escrever dados de registo em vários projetos. Os seus dados de registo podem ser armazenados no projeto no qual têm origem ou um administrador da organização pode ter configurado o armazenamento centralizado. Para ver os dados de registo da sua aplicação, crie um âmbito de registo, configure-o para listar os projetos ou as visualizações de registos que armazenam os dados de registo da sua aplicação e, em seguida, configure-o como o âmbito de registo predefinido. Quando concluir esses passos, a página Explorador de registos apresenta automaticamente os dados escritos pela sua aplicação, mesmo quando esses dados são armazenados em projetos diferentes ou num contentor de registos centralizado.

Crie o âmbito do registo personalizado no projeto a partir do qual vai ver os dados de registo. Este projeto é o projeto anfitrião do App Hub ou o projeto de gestão da sua pasta com apps ativadas. Por exemplo, se o nome a apresentar da pasta for My Folder, o nome a apresentar do projeto de gestão é My Folder-mp.

Limitações

  • Não pode eliminar nem modificar o âmbito do registo denominado _Default.
  • Apenas os projetos do Trusted Cloud suportam um âmbito de registo predefinido.
  • Não pode adicionar pastas nem organizações a um âmbito de registo definido pelo utilizador.
  • Os âmbitos dos registos são criados na localização global.

Antes de começar

  1. In the Trusted Cloud console, on the project selector page, select or create a Trusted 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 (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 Trusted Cloud project.

  3. Para receber as autorizações de que precisa para criar e ver âmbitos de registo, peça ao seu administrador para lhe conceder as seguintes funções de IAM no seu projeto:

    Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Estas funções predefinidas contêm as autorizações necessárias para criar e ver âmbitos de registo. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

    Autorizações necessárias

    São necessárias as seguintes autorizações para criar e ver âmbitos de registo:

    • Para definir o âmbito do registo predefinido: observability.scopes.{get, update}
    • Para criar e gerir âmbitos de registo: logging.logScopes.{create, delete, get, list, update}

    Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

  4. Select the tab for how you plan to use the samples on this page:

    gcloud

    Instale a CLI Google Cloud e, em seguida, inicie sessão na CLI gcloud com a sua identidade federada. Depois de iniciar sessão, inicialize a CLI gcloud executando o seguinte comando: 

    gcloud init

    Terraform

    Para usar os exemplos do Terraform nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as credenciais predefinidas da aplicação com as suas credenciais de utilizador.

    1. Install the Google Cloud CLI.

    2. Configure a CLI gcloud para usar a sua identidade federada.

      Para mais informações, consulte o artigo Inicie sessão na CLI gcloud com a sua identidade federada.

    3. Create local authentication credentials for your user account: 

      gcloud auth application-default login

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Configure o ADC para um ambiente de desenvolvimento local na Trusted Cloud documentação de autenticação.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud e, em seguida, inicie sessão na CLI gcloud com a sua identidade federada.

    Para mais informações, consulte o artigo Autenticar para usar REST na Trusted Cloud documentação de autenticação.

    Apresente âmbitos de registo

    gcloud

    Para apresentar uma lista dos âmbitos de registo num projeto, use o comando gcloud logging scopes list:

     gcloud logging scopes list --project=PROJECT_ID

    Antes de executar o comando, atualize os seguintes campos:

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

    Para obter os detalhes de um âmbito de registo num projeto, use o comando gcloud logging scopes describe:

     gcloud logging scopes describe LOG_SCOPE_ID --project=PROJECT_ID

    Antes de executar o comando, atualize os seguintes campos:

    • PROJECT_ID: o identificador do projeto.
    • LOG_SCOPE_ID: o ID do âmbito do registo. Por exemplo, my-scope.

    Terraform

    Pode usar o Terraform para criar e modificar um âmbito de registo. No entanto, não pode usar o Terraform para listar âmbitos de registo.

    REST

    A API Cloud Logging contém comandos que listam os âmbitos de registo num recurso ou que comunicam os detalhes de um âmbito de registo específico. Para ver uma lista completa de comandos, consulte a documentação de referência da API.

    Para Trusted Cloud projetos, use os seguintes comandos:

    Nos comandos anteriores, o campo parent tem a seguinte sintaxe:

    projects/PROJECT_ID/locations/LOCATION_ID

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION_ID tem de ser definido como global.

    Crie um âmbito de registo

    Pode criar 100 âmbitos de registo por projeto. Um âmbito de registo pode incluir um total de 100 vistas de registos e projetos. No entanto, só pode incluir 5 projetos. Não pode adicionar pastas nem organizações a um âmbito de registo.

    gcloud

    Para criar um âmbito de registo num projeto, use o comando gcloud logging scopes create:

     gcloud logging scopes create LOG_SCOPE_ID --project=PROJECT_ID \
   --description=DESCRIPTION \
   --resource-names=RESOURCE_NAMES

    Antes de executar o comando, atualize os seguintes campos:

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOG_SCOPE_ID: o ID do âmbito do registo. Por exemplo, my-scope.

    • DESCRIPTION: opcional. A descrição do âmbito do registo. Formate a descrição como uma string.

    • RESOURCE_NAMES: Uma lista separada por vírgulas dos nomes totalmente qualificados de projetos ou visualizações de registos. Por exemplo, para incluir my-project no âmbito do registo, especifique projects/my-project.

    Terraform

    Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform. Para mais informações, consulte a Terraform documentação de referência do fornecedor.

    Para criar um âmbito de registo num projeto, numa pasta ou numa organização através do Terraform, use o recurso Terraform google_logging_log_scope.

    No comando, defina os seguintes campos:

    • parent: o nome completo do seu projeto, pasta ou organização. Por exemplo, pode definir este campo como "projects/PROJECT_ID", onde PROJECT_ID é o ID do seu Trusted Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • locations: definido como "global".

    • name: definido como o nome totalmente qualificado do âmbito do registo. Para projetos, o formato deste campo é:

      "projects/PROJECT_ID/locations/global/logScopes/LOG_SCOPE_ID"

      Na expressão anterior, LOG_SCOPE_ID é o nome de um âmbito de registo, como "produção".

    • resource_names: Uma matriz de projetos e visualizações de registos, em que cada projeto e visualização de registos são especificados através do respetivo nome totalmente qualificado.

    • description: uma breve descrição. Por exemplo, "Âmbito dos recursos de produção".

    REST

    A API Cloud Logging também suporta a criação de âmbitos de registo numa pasta ou organização. Para mais informações, consulte a documentação de referência da API.

    Para Trusted Cloud projetos, use o seguinte comando:

    Nos comandos anteriores, o campo parent tem a seguinte sintaxe:

    projects/PROJECT_ID/locations/LOCATION_ID

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION_ID tem de ser definido como global.

    Modifique ou elimine um âmbito do registo

    gcloud

    Para modificar a descrição da lista de recursos num âmbito de registo num projeto, use o comando gcloud logging scopes update:

     gcloud logging scopes update LOG_SCOPE_ID --project=PROJECT_ID \
   --description=DESCRIPTION \
   --resource-names=RESOURCE_NAMES

    Antes de executar o comando, atualize os seguintes campos:

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOG_SCOPE_ID: o ID do âmbito do registo. Por exemplo, my-scope.

    • DESCRIPTION: a descrição do âmbito do registo. Formate a descrição como uma string. Omita este campo quando não quiser alterar a descrição do âmbito do registo.

    • RESOURCE_NAMES: Uma lista separada por vírgulas dos nomes totalmente qualificados de projetos ou visualizações de registos. Omita este campo quando não quiser alterar a lista de recursos.

    Para eliminar um âmbito de registo num projeto, use o comando gcloud logging scopes delete:

     gcloud logging scopes delete LOG_SCOPE_ID --project=PROJECT_ID

    Antes de executar o comando, atualize os seguintes campos:

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOG_SCOPE_ID: o ID do âmbito do registo. Por exemplo, my-scope.

    Terraform

    Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform. Para mais informações, consulte a Terraform documentação de referência do fornecedor.

    Para modificar um âmbito de registo num projeto, numa pasta ou numa organização através do Terraform, use o recurso Terraform google_logging_log_scope.

    REST

    A API Cloud Logging contém comandos que podem modificar ou eliminar um âmbito de registo. Para ver uma lista completa de comandos, consulte a documentação de referência da API.

    Para Trusted Cloud projetos, use os seguintes comandos:

    Nos comandos anteriores, o campo parent tem a seguinte sintaxe:

    projects/PROJECT_ID/locations/LOCATION_ID/logScopes/LOG_SCOPE_ID

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

    • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
    • LOCATION_ID tem de ser definido como global.
    • LOG_SCOPE_ID: o ID do âmbito do registo. Por exemplo, my-scope.

    O que se segue?