Esta página foi traduzida pela API Cloud Translation.

Escreva e consulte entradas de registo com a CLI gcloud

Este documento apresenta algumas das capacidades do Cloud Logging e mostra-lhe como fazer o seguinte:

Escrever entradas de registo através da CLI do Google Cloud.
Liste as entradas do registo através da CLI gcloud.
Liste as entradas do registo através da API Logging.
Veja e consulte entradas de registo através do Explorador de registos.

Antes de começar

Tem de ter um Google Cloud projeto com a faturação ativada para concluir este início rápido. Se não tiver um Google Cloud projeto ou se não tiver a faturação ativada para o seu Google Cloud projeto, faça o seguinte:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Escreva entradas de registo com a CLI gcloud

O registo suporta entradas de registo com dados estruturados e não estruturados. Os dados estruturados consistem numa estrutura de dados JSON; por exemplo, {"weather": "partly cloudy"}. Os dados não estruturados são uma sequência de carateres; por exemplo, "A simple entry".

Nos passos seguintes, vai usar a CLI gcloud para escrever uma entrada de registo com dados não estruturados e uma entrada de registo com dados estruturados. A CLI gcloud oferece uma interface de linhas de comando para a API Cloud Logging.

Escreva uma entrada de registo com dados não estruturados no registo my-test-log, execute o comando gcloud logging write:
```
gcloud logging write my-test-log "A simple entry."
```
Quando o comando estiver concluído, é apresentada a mensagem: Created log entry.
Escreva uma entrada de registo com dados estruturados no registo my-test-log:
```
gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
```
Quando escreve uma entrada de registo com dados estruturados, tem de incluir --payload-type=json. Se omitir este campo, o Logging interpreta a carga útil como dados não estruturados.

Se o registo my-test-log não existir, o Logging cria o registo quando a entrada de registo é recebida.

Liste as entradas do registo através da CLI gcloud

Pode obter entradas de registo do Logging e apresentá-las através da CLI gcloud. Por exemplo, para obter e apresentar as entradas de registo com um tipo de recurso de global, execute o seguinte comando:

gcloud logging read "resource.type=global"

O comando devolve um resultado semelhante ao seguinte:

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

Para obter informações sobre a leitura de registos, consulte a documentação de referência gcloud logging read.

Liste as entradas do registo através do Explorador de APIs

Para executar métodos da API Logging sem escrever código, consulte o artigo Usar o Explorador de APIs. Para ler uma lista de entradas de registo do Logging, faça o seguinte:

Aceda à página de referência da API para o método da API entries.list:

Aceda à página da API entries.list

Configure e execute o comando da API:

Substitua PROJECT_ID no seguinte texto:

"resourceNames": [
"projects/PROJECT_ID"
],
"filter": "resource.type=global",
"orderBy": "timestamp desc"

Copie o texto atualizado do passo anterior e cole-o no campo Corpo do pedido do APIs Explorer.
Clique em Executar.

O método devolve uma resposta semelhante à seguinte:

{
  "entries": [
    {
      "textPayload": "A simple entry",
      "insertId": "vd4m1if7h7u1a",
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:19.718100792Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
    },
    {
      "insertId": "jpj9zjf73t1mn",
      "jsonPayload": {
        "message": "My second entry",
        "weather": "partly cloudy"
      },
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "myloggingproject"
        }
      },
      "timestamp": "2018-11-01T18:39:31.114507977Z",
      "logName": "projects/myloggingproject/logs/my-test-log",
      "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
    }
  ]
}

Veja entradas do registo no Explorador de registos

Para ver as entradas de registo na Google Cloud consola, pode usar o Explorador de registos. A maioria dos Google Cloud projetos armazena um grande número de registos; pode selecionar determinadas entradas de registo escrevendo uma consulta.

Para ver as entradas do registo que escreveu com o Explorador de registos, faça o seguinte:

Na Google Cloud consola, aceda à página Explorador de registos:
Aceda ao Explorador de registos

Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

Certifique-se de que o Google Cloud projeto está selecionado na Google Cloud barra de navegação. Se necessário, use a Google Cloud lista pendente de projetos para selecionar o seu Google Cloud projeto.
No menu Recurso, selecione Global.

Se não vir a opção de menu Global ou se não vir as suas entradas de registo, aguarde alguns minutos e atualize a página. O Logging pode demorar alguns minutos a receber entradas de registo.
Para ver os detalhes de uma entrada do registo, clique no respetivo menu.

A primeira entrada do registo tem os respetivos dados armazenados em textPayload. A segunda entrada do registo contém dados estruturados que são armazenados em jsonPayload. O payload estruturado contém as chaves message e weather.

Nota: quando message é uma chave para uma entrada de registo estruturada, o registo usa-a como o resumo da entrada de registo quando a entrada não é expandida.

Para ver informações sobre o formato de dados das entradas do registo, consulte o tipo LogEntry.

Consultar entradas de registo no Explorador de registos

Pode consultar entradas de registo através do editor de consultas e, com registos estruturados, pela chave e pelo valor. Por exemplo, para apresentar todas as entradas de registo que contêm o texto simple, faça o seguinte:

Na Google Cloud consola, aceda à página Explorador de registos:
Aceda ao Explorador de registos

Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.
No menu Recurso, selecione Global.
No editor de consultas, introduza a string simple entre aspas. A apresentação dos registos mostra apenas a entrada de registo A simple entry.
Depois de ver o registo, remova a string de consulta que adicionou e clique em Executar consulta. Ambas as entradas do registo reaparecem no ecrã.

Para apresentar todas as entradas de registo com dados estruturados que tenham uma chave de weather em que o campo value contém partly, faça o seguinte:

O editor de consultas contém a linha resource.type="global". Introduza o seguinte comando:
```
jsonPayload.weather:partly
```
Clique em Executar consulta. O resultado é a única entrada de registo My second entry.

O Explorador de registos também oferece consultas guardadas, sugeridas e recentes. Para mais informações sobre consultas, consulte o artigo Crie consultas no Explorador de registos.

Para consultas de exemplo, consulte o artigo Consultas de exemplo com o Explorador de registos.

Resolução de problemas

Os erros tipográficos e os nomes de campos desconhecidos fazem com que os comandos da CLI gcloud sejam concluídos com mensagens de argumento inválido. Por exemplo, se se esquecer do ponto final em resource.type, recebe o seguinte erro:
```
 ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
```
Quando não são concedidas as autorizações de acesso necessárias ao Cloud Logging, os comandos da CLI gcloud são concluídos com mensagens de autorização recusada. Por exemplo, se uma instância de VM do Compute Engine estiver configurada com as predefinições da API, o comando list é concluído com um erro de acesso negado:
```
 ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
```
Para corrigir esta condição, modifique as autorizações da instância de VM do Compute Engine para conceder autorização de leitura do Cloud Logging da seguinte forma:
1. Aceda à página Detalhes da instância de VM da sua instância de VM. Clique em Parar. Esta ação pode demorar um ou dois minutos a ser concluída.
2. Para modificar a configuração, clique em Editar.
3. Pesquise o cabeçalho Âmbitos de acesso da API Cloud e clique em Detalhes para apresentar as definições de cada API. Altere a entrada da API Cloud Logging para Completo. Clique em Guardar.
4. Para reiniciar a instância de VM, clique em Iniciar. Após alguns momentos, a VM está pronta a usar.

Quando o APIs Explorer não consegue concluir o seu comando ou requer autorização adicional, apresenta uma mensagem ou um código de erro:
- Código de resposta 200 e sem entradas: se a mensagem nextPageToken for apresentada, significa que o APIs Explorer não teve tempo para concluir a pesquisa. Adicione um pageToken ao seu pedido, defina o valor para que seja igual ao valor indicado com a chave nextPageToken e, em seguida, tente novamente o comando.
- Código de resposta 400: o valor da consulta é inválido. Por exemplo, se escrever global incorretamente como gloobal, a mensagem é Unsupported resource type: gloobal.
- Código de resposta 404: o ID do projeto é inválido. Verifique a ortografia do identificador do projeto.
- Pode ser-lhe pedido que inicie sessão no seuGoogle Cloud projeto e permita que o Explorador de APIs aceda à sua conta.

Limpar

Para evitar incorrer em custos na sua Google Cloud conta pelos recursos usados nesta página, elimine o Google Cloud projeto com os recursos.

(Opcional) Para eliminar as entradas de registo que criou, execute o seguinte comando:gcloud
```
gcloud logging logs delete my-test-log
```
Se não eliminar as entradas do registo, estas expiram e são removidas. Para ver informações sobre a retenção, consulte o artigo Quotas e limites.

O que se segue?

Para ver detalhes sobre a interface de linhas de comando de registo, leia as páginas de referência do grupo de comandos gcloud logging.
Para consultar a documentação sobre a API Logging, consulte a API Cloud Logging.
Para ver detalhes sobre o Explorador de registos, consulte o artigo Usar o Explorador de registos.

Para saber como recolher entradas de registo das suas instâncias de VM no Logging, consulte os agentes de observabilidade do Google Cloud.