Gravar e consultar entradas de registros com a gcloud CLI
Este documento apresenta alguns dos recursos do Cloud Logging e mostra como fazer o seguinte:
- Gravar entradas de registro usando a Google Cloud CLI.
- Listar entradas de registro usando a CLI gcloud.
- listar entradas de registro usando a API Logging;
- visualizar e consultar entradas de registros usando o Logs Explorer.
Antes de começar
Você precisa ter um projeto do Google Cloud com faturamento ativado para concluir este guia de início rápido. Se você não tiver um projeto do Google Cloud ou não tiver o faturamento ativado para seu projeto do Google Cloud, faça o seguinte:- Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, 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.
-
No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
Como começar
A CLI gcloud tem um grupo de comandos, gcloud logging
, que fornece uma interface de linha de comando para a API Cloud Logging.
É possível usar o ambiente do Cloud Shell ou uma instância de máquina virtual (VM) do Compute Engine para os comandos da CLI gcloud neste guia de início rápido. A CLI gcloud vem pré-instalada no ambiente do Cloud Shell.
Cloud Shell
Verifique se a CLI gcloud está configurada para usar o projeto correto do Google Cloud:
No console do Google Cloud, clique em Ativar o Cloud Shell:
O Cloud Shell é aberto em uma janela e exibe uma mensagem de boas-vindas: A mensagem de boas-vindas reflete o ID do projeto configurado:
Se você quiser usar um projeto do Google Cloud diferente do listado na mensagem de boas-vindas, execute o seguinte comando depois de substituir PROJECT_ID pelo ID do projeto:
gcloud config set project PROJECT_ID
Para encontrar o ID do projeto, consulte Como identificar projetos.
Instância de VM
Para criar uma instância de VM do Compute Engine no console do Google Cloud, siga estas etapas:
No console do Google Cloud, selecione Compute Engine e, em seguida, Instâncias de VM.
Selecione Criar instância.
Em Identidade e acesso à API, em Escopos de acesso, selecione Definir acesso para cada API.
Percorra a listagem até encontrar a API Stackdriver Logging. Mude o acesso para Full.
Deixe todas as outras configurações nos valores padrão e clique em Criar. A instância da sua VM está pronta para uso.
Clique em SSH para se conectar ao shell da instância de VM. Após um momento, um shell do Debian GNU/Linux será aberto em uma janela e exibirá uma mensagem de boas-vindas.
Execute o seguinte comando para verificar se a CLI gcloud está configurada para seu projeto do Compute Engine:
gcloud config list
Se você quiser usar outro projeto do Google Cloud, execute o seguinte comando depois de substituir PROJECT_ID pelo ID do projeto:
gcloud config set project PROJECT_ID
Para conseguir o ID do projeto, consulte Como identificar projetos.
Gravar entradas de registro usando a CLI gcloud
A geração de registros aceita entradas de registro com dados estruturados e não estruturados. Os dados estruturados consistem em uma estrutura de dados JSON, por exemplo,
{"weather": "partly cloudy"}
. Os dados não estruturados são uma string de caracteres (por exemplo, "A simple entry"
).
Nas próximas etapas, você usará a CLI gcloud para gravar uma entrada de registro com dados não estruturados e uma entrada de registro com dados estruturados:
Grave uma entrada de registro com dados não estruturados no registro
my-test-log
:gcloud logging write my-test-log "A simple entry."
Depois que o comando for concluído, você verá a mensagem:
Created log entry
.Grave uma entrada de registro com dados estruturados no registro
my-test-log
:gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
Ao gravar uma entrada de registro com dados estruturados, é preciso incluir
--payload-type=json
. Se você omitir esse campo, o Logging interpretará o payload como dados não estruturados.
Se my-test-log
não existir, o Logging criará o registro quando a entrada for recebida.
Listar entradas de registro usando a CLI gcloud
É possível recuperar entradas de registro do Logging e exibi-las
usando a CLI gcloud. Por exemplo, para recuperar e exibir as entradas de registro com um tipo de recurso global
, execute o seguinte comando:
gcloud logging read "resource.type=global"
O comando retorna 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'
Listar entradas de registro usando o APIs Explorer
Para executar os métodos da API Logging sem escrever códigos, consulte Como usar o APIs Explorer. Para ler uma lista de entradas de registro do Logging, faça o seguinte:
Acesse a página de referência da API sobre o método de 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 da etapa anterior e cole-o no campo Corpo da solicitação do APIs Explorer.
Clique em Executar.
O método retorna 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" } ] }
Ver entradas de registro no Explorador de registros
Para visualizar entradas de registro no console do Google Cloud, use a Análise de registros. A maioria dos projetos do Google Cloud armazena um grande número de registros. É possível selecionar determinadas entradas de registro gravando uma consulta.
Para visualizar as entradas de registro que você gravou usando a Análise de registros, faça o seguinte:
-
No console do Google Cloud, acesse a página Análise de registros:
Acessar a Análise de registros
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Geração de registros.
Verifique se o projeto do Google Cloud está selecionado na barra de navegação do Google Cloud. Se necessário, use a lista suspensa do projeto do Google Cloud para selecionar o projeto do Google Cloud.
No menu Recurso, selecione Global.
Se a opção de menu Global ou as entradas de registro não forem exibidas, aguarde alguns minutos e atualize a página. Pode demorar alguns minutos para o Logging receber entradas de registro.
Para ver os detalhes de uma entrada de registro, clique no chevron_right Menu correspondente.
A primeira entrada de registro tem os dados armazenados em
textPayload
. A segunda entrada de registro contém dados estruturados armazenados emjsonPayload
. O payload estruturado contém as chavesmessage
eweather
.
Para informações sobre o formato de dados das entradas de registro, consulte o
tipo LogEntry
.
Consultar entradas de registro no Explorador de registros
Você pode consultar entradas de registro usando o editor de consultas e, com registros estruturados, pela chave e pelo valor. Por exemplo, para exibir todas as entradas de registro que contêm o texto simple
, faça o seguinte:
-
No console do Google Cloud, acesse a página Análise de registros:
Acessar a Análise de registros
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Geração de registros.
No menu Recurso, selecione Global.
No Editor de consultas, insira a string
simple
entre aspas. Apenas a entrada de registroA simple entry.
será exibida.Depois de visualizar o registro, remova a string de consulta adicionada e clique em Executar consulta. As entradas de registro são reexibidas na tela.
Para exibir todas as entradas de registro 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"
. Digite este comando:jsonPayload.weather:partly
Clique em Executar consulta. O resultado é a única entrada de registro
My second entry
.
O Explorador de registros também oferece consultas salvas, sugeridas e recentes. Para mais informações sobre consultas, acesse Criar consultas no Explorador de registros.
Para ver exemplos de consultas, veja Amostra de consultas usando o Explorador de registros.
Solução de problemas
Erros tipográficos e nomes de campo desconhecidos fazem com que os comandos da CLI gcloud sejam preenchidos com mensagens de argumento inválido. Por exemplo, se você esquecer o ponto em
resource.type
, isso resultará no erro:ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
Quando o Cloud Logging não recebeu as permissões de acesso necessárias, os comandos da CLI gcloud são concluídos com mensagens de permissão negada. Por exemplo, se uma instância de VM do Compute Engine estiver configurada com as configurações padrão da API, o comando
list
será concluído com um erro de permissão negada:ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
Para corrigir essa condição, modifique as permissões da instância de VM do Compute Engine para conceder permissão de leitura ao Cloud Logging fazendo o seguinte:
- Acesse a página Detalhes da instância de VM. Clique em Interromper. Essa ação pode levar um ou dois minutos para ser concluída.
- Para modificar a configuração, clique em Editar.
- Pesquise o cabeçalho Escopos de acesso da API Cloud e clique em Detalhes para exibir as configurações de cada API. Altere a entrada da API Cloud Logging para Total. Clique em Salvar.
- Para reiniciar a instância de VM, clique em Iniciar. Depois de alguns momentos, sua VM estará pronta para uso.
Quando não consegue concluir seu comando ou requer outras autorizações, as APIs Explorer exibe uma mensagem ou um código de erro:
- Código de resposta 200 e nenhuma entrada: se a mensagem
nextPageToken
for exibida, isso indica que o APIs Explorer não teve tempo para concluir a pesquisa. Adicione umpageToken
à solicitação, defina o valor para ser o mesmo fornecido com a chavenextPageToken
e, em seguida, tente executar o comando novamente. - Código de resposta 400: o valor da consulta é inválido. Por exemplo, se você
escreveu
global
comogloobal
, a mensagem seráUnsupported resource type: gloobal
. - Código de resposta 404: o código do projeto é inválido. Verifique a ortografia do identificador de projeto.
- Você pode ser solicitado a fazer login na conta do Google e permitir que as APIs Explorer acessem a conta.
- Código de resposta 200 e nenhuma entrada: se a mensagem
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta página, siga as etapas a seguir.
(Opcional) Para excluir as entradas de registro que você criou, execute o seguinte comando do
gcloud
:gcloud logging logs delete my-test-log
Se você não excluir suas entradas de registro, elas expirarão e serão removidas. Para mais informações, consulte Cotas e limites.
A seguir
- Para detalhes sobre a interface de linha de comando do Logging, leia as
páginas de referência para o grupo de comandos
gcloud logging
. - Para ver a documentação sobre a API Logging, leia API Cloud Logging.
- Para detalhes sobre a Análise de registros, consulte Como usar a Análise de registros.
- Para saber como coletar entradas de registro das suas instâncias de VM no Logging, consulte Agentes de observabilidade do Google Cloud.