Para aplicativos Node.js, os plug-ins são mantidos nas bibliotecas de geração de registros Winston e Bunyan. Winston é uma biblioteca de uso geral, que implementa uma variedade de formatadores e transportes de registro. Bunyan, que é especializado para registros JSON estruturados e dá suporte à formatação de registros fazendo o pipe para a linha de comando do Bunyan.
Também é possível usar a biblioteca de cliente do Logging para Node.js diretamente ou criar suas próprias integrações com a biblioteca de geração de registros preferida. Por exemplo, use o exemplo de framework de registro do Pino.
Não é necessário instalar o agente do Logging para usar o Winston ou o Bunyan em uma instância de máquina virtual (VM) do Compute Engine.
Antes de começar
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Enable the Cloud Logging API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
Enable the Cloud Logging API.
- Prepare o ambiente para o desenvolvimento do Node.js.
Configurar a geração de registros
Esta seção descreve como instalar e configurar os plug-ins da Winston e Bunyan (links em inglês). Para Bunyan, são fornecidas informações sobre como usar o Bunyan com um Node.js Express para o aplicativo.
É possível usar outras bibliotecas ou frameworks. Por exemplo, use o framework de registro de Pino. Para conferir um exemplo de código que usa o OpenTelemetry para coletar métricas e dados de rastreamento e o framework de registro Pino para coletar dados de registro, consulte Gerar rastros e métricas com o Node.js. Se você usar o Pino, deverá implementar um mapeamento entre o Pino os níveis de gravidade e os usados pelo Cloud Logging. Para conferir um exemplo de código, consulte Como mapear níveis de registro do Pino.
Instalar e configurar o plug-in Winston
O Cloud Logging fornece um plug-in para a biblioteca de geração de registros Node.js do Winston. O plug-in do Logging para Winston fornece uma camada mais simples e de nível superior para trabalhar com o Logging.
Para instalar e configurar o plug-in Winston, faça o seguinte:
Para instalar o Logging plug-in Winston, use npm:
npm install --save @google-cloud/logging-winston winston
Importe o plug-in e adicione-o à configuração do Winston:
Configure o plug-in.
Você pode personalizar o comportamento do plug-in Winston usando a mesma de configuração compatíveis com a biblioteca de cliente da API Cloud Logging do Cloud para Node.js. Essas opções podem ser transmitidas no objeto
options
para o construtor.
Instalar e configurar o plug-in do Bunyan
O Cloud Logging fornece um plug-in para a biblioteca de geração de registros Node.js do Bunyan. O plug-in do Logging para Bunyan fornece uma camada mais simples e de nível superior para trabalhar com o Logging.
Para instalar e configurar o plug-in do Bunyan, faça o seguinte:
Para instalar o Logging plug-in Bunyan, use npm:
npm install --save bunyan @google-cloud/logging-bunyan
Importe o plug-in e adicione-o à configuração do Bunyan:
Configure o plug-in.
É possível personalizar o comportamento do plug-in Bunyan usando as mesmas opções de configuração compatíveis com a biblioteca de cliente Cloud API do Cloud Logging para Node.js. Essas opções podem ser transmitidas no objeto
options
para o construtor.
Usar Bunyan e Express
É possível configurar e usar o Bunyan com o Logging em um aplicativo Node.js Express.
Para mais informações sobre a instalação, consulte a documentação para as bibliotecas do Cloud Logging para Node.js. Além disso, use o rastreador de problemas (em inglês) para informá-los.
Gravar registros com a biblioteca de cliente do Cloud Logging
Para informações sobre como usar diretamente a biblioteca de cliente do Cloud Logging para Node.js, consulte Bibliotecas de cliente do Cloud Logging.
Executar no Google Cloud
Para que um aplicativo grave registros usando as bibliotecas do Cloud Logging para Node.js, a
conta de serviço do recurso subjacente precisa ter a função do IAM gravadora de registros (roles/logging.logWriter
).
A maioria dos ambientes do Google Cloud configura automaticamente a conta de serviço padrão
para ter esse papel.
App Engine
O Cloud Logging é ativado automaticamente para o App Engine, e a conta de serviço padrão do aplicativo tem as permissões do IAM por padrão para gravar entradas de registro.
Para gravar entradas de registro do seu app, recomendamos que você use o Bunyan ou o Winston (links em inglês), conforme descrito nesta página.
Saiba mais em Gravar e visualizar registros.
Google Kubernetes Engine (GKE)
O GKE concede automaticamente a conta de serviço
o papel do IAM Gravador de registros (roles/logging.logWriter
).
Se você usar a
Federação de identidade da carga de trabalho para o GKE
com essa conta de serviço padrão para permitir que as cargas de trabalho acessem APIs
específicas do Google Cloud, nenhuma configuração adicional será necessária.
No entanto, se você usar a federação de identidade da carga de trabalho para o GKE com um
conta de serviço do IAM personalizada e garanta que o serviço personalizado
tem o papel de Gravador de registros (roles/logging.logWriter
).
Se necessário, também é possível usar o seguinte comando para adicionar o escopo de acesso logging.write
ao criar o cluster:
gcloud container clusters create example-cluster-name \
--scopes https://www.googleapis.com/auth/logging.write
Compute Engine
Ao usar instâncias de VM do Compute Engine, adicione o escopo de acesso cloud-platform
a cada instância. Ao criar uma nova instância por meio do
Console do Google Cloud, faça isso na seção Identidade e acesso à API.
do painel Criar instância. Use a conta de serviço padrão do Compute Engine ou outra de sua escolha e selecione Permitir acesso completo a todas as APIs do Cloud na seção Identidade e acesso à API. Seja qual for o serviço
da conta selecionada, verifique se ela recebeu o
Papel Gravador de registros no IAM e Admin da
console do Google Cloud.
Funções do Cloud Run
O Cloud Run Functions concede o papel de gravador de registros por padrão.
As bibliotecas do Cloud Logging para Node.js podem ser usadas sem a necessidade de fornecer credenciais explicitamente.
As funções do Cloud Run são configuradas para usar o Cloud Logging automaticamente.
Execute localmente e em outro lugar
Para usar as bibliotecas do Cloud Logging para Node.js fora do Google Cloud, faça o seguinte: incluindo a execução da biblioteca em sua própria estação de trabalho, no sistema computadores ou nas instâncias de VM de outro provedor de nuvem, é preciso informe o ID do projeto do Google Cloud e as permissões conta de serviço as credenciais diretamente para as bibliotecas do Cloud Logging para Node.js.
Para contas de serviço atuais, faça o seguinte:
Conceda à conta de serviço o IAM Papel do IAM Gravador de registros (
roles/logging.logWriter
). Para mais informações sobre o IAM, consulte Controle de acesso.
Se você não tiver uma conta de serviço, crie uma. Para saber mais sobre esse processo, consulte Criar contas de serviço.
Para informações gerais sobre os métodos que podem ser usados para autenticação, consulte Terminologia: contas de serviço.
Use o Winston:Use o Bunyan:
Visualize os registros
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 Logging.
No Explorador de registros, é preciso especificar um ou mais recursos, mas a escolha deles pode não ser óbvia. Veja a seguir algumas dicas para ajudar você a começar:
Se você estiver implantando seu aplicativo no App Engine ou usando as bibliotecas específicas dele, defina seu recurso como Aplicativo do GAE.
Se você estiver implantando seu aplicativo no Compute Engine, defina o recurso como Instância de VM do GCE.
Se você estiver implantando seu aplicativo no Google Kubernetes Engine, a configuração de geração de registros do cluster determinará o tipo de recurso das entradas de registro. Para um discussão sobre a observabilidade do Google Cloud legado e a observabilidade soluções do Kubernetes Monitoring e como elas afetam tipo de recurso, consulte Como migrar para o Google Cloud Observability Kubernetes Monitoring (em inglês).
Se o aplicativo estiver usando a API Cloud Logging diretamente, o recurso dependerá da API e da configuração. Por exemplo, no seu aplicativo, é possível especificar um recurso ou usar um recurso padrão.
Se você não vir registros no Explorador de registros, alterne para o modo de consulta avançada e use uma consulta vazia para ver todas as entradas de registro.
- Se quiser alternar para o modo de consulta avançada, clique no menu (▾) na parte superior do Explorador de registros e selecione Converter para filtro avançado.
- Limpe o conteúdo que aparece na caixa de filtro.
- Clique em Enviar filtro.
É possível examinar as entradas individuais para identificar seus recursos.
Para mais informações, consulte Como usar a Análise de registros.