Configurar o Cloud Logging para Node.js

Para aplicações Node.js, os plug-ins são mantidos para as bibliotecas de registo populares Winston e Bunyan. O Winston é uma biblioteca de utilização geral que implementa uma variedade de formatadores e transportes de registos. O Bunyan, que é especializado em registos JSON estruturados, suporta a formatação de registos através do comando Bunyan.

Também pode usar a biblioteca cliente de registo para Node.js diretamente ou criar as suas próprias integrações com a sua biblioteca de registo preferida. Por exemplo, pode usar o exemplo da estrutura de registo Pino.

Não tem de instalar o agente Logging para usar o Winston ou o Bunyan numa 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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. Prepare o seu ambiente para o desenvolvimento de Node.js.

   Aceda ao guia de configuração do Node.js

Configure o registo

Esta secção descreve como instalar e configurar os plug-ins para as bibliotecas de registo Winston e Bunyan. Para o Bunyan, são fornecidas informações sobre como usar o Bunyan com uma aplicação Node.js Express.

Pode usar outras bibliotecas ou frameworks. Por exemplo, pode usar a estrutura de registo Pino. Para ver um exemplo de código que usa o OpenTelemetry para recolher métricas e dados de rastreio, e a framework de registo Pino para recolher dados de registo, consulte o exemplo de instrumentação do Node.js. Se usar o Pino, tem de implementar um mapeamento entre os níveis de gravidade do Pino e os usados pelo Cloud Logging. Para ver um código de exemplo, consulte o artigo Mapeamento dos níveis de registo do Pino.

Instale e configure o plug-in Winston

O Cloud Logging fornece um plug-in para a biblioteca de registo do Winston Node.js. O plug-in Logging para Winston oferece 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:

1. Para instalar o plug-in Logging Winston, use o npm:

   npm install @google-cloud/logging-winston winston

2. Importe o plug-in e adicione-o à sua configuração do Winston:

   const winston = require('winston');
   
   // Imports the Google Cloud client library for Winston
   const {LoggingWinston} = require('@google-cloud/logging-winston');
   
   const loggingWinston = new LoggingWinston();
   
   // Create a Winston logger that streams to Cloud Logging
   // Logs will be written to: "projects/YOUR_PROJECT_ID/logs/winston_log"
   const logger = winston.createLogger({
     level: 'info',
     transports: [
       new winston.transports.Console(),
       // Add Cloud Logging
       loggingWinston,
     ],
   });
   
   // Writes some log entries
   logger.error('warp nacelles offline');
   logger.info('shields at 99%');

3. Configure o plug-in.

   Pode personalizar o comportamento do plug-in Winston através das mesmas opções de configuração suportadas pela biblioteca cliente da API Cloud Logging para Node.js. Estas opções podem ser transmitidas no objeto options transmitido ao construtor do plug-in.

Instale e configure o plug-in Bunyan

O Cloud Logging fornece um plug-in para a biblioteca de registo do Bunyan Node.js. O plug-in Logging para Bunyan oferece uma camada mais simples e de nível superior para trabalhar com o Logging.

Para instalar e configurar o plug-in Bunyan, faça o seguinte:

1. Para instalar o plug-in Logging Bunyan, use o npm:

   npm install bunyan @google-cloud/logging-bunyan

2. Importe o plugin e adicione-o à sua configuração do Bunyan:

   const bunyan = require('bunyan');
   
   // Imports the Google Cloud client library for Bunyan
   const {LoggingBunyan} = require('@google-cloud/logging-bunyan');
   
   // Creates a Bunyan Cloud Logging client
   const loggingBunyan = new LoggingBunyan();
   
   // Create a Bunyan logger that streams to Cloud Logging
   // Logs will be written to: "projects/YOUR_PROJECT_ID/logs/bunyan_log"
   const logger = bunyan.createLogger({
     // The JSON payload of the log as it appears in Cloud Logging
     // will contain "name": "my-service"
     name: 'my-service',
     streams: [
       // Log to the console at 'info' and above
       {stream: process.stdout, level: 'info'},
       // And log to Cloud Logging, logging at 'info' and above
       loggingBunyan.stream('info'),
     ],
   });
   
   // Writes some log entries
   logger.error('warp nacelles offline');
   logger.info('shields at 99%');

3. Configure o plug-in.

   Pode personalizar o comportamento do plug-in Bunyan usando as mesmas opções de configuração suportadas pela biblioteca cliente do Google Cloud Logging API para Node.js. Estas opções podem ser transmitidas no objeto options transmitido ao construtor do plug-in.

Use o Bunyan e o Express

Pode configurar e usar o Bunyan com o registo num aplicativo Node.js Express.

// Imports the Google Cloud client library for Bunyan.
const lb = require('@google-cloud/logging-bunyan');

// Import express module and create an http server.
const express = require('express');

async function startServer() {
  const {logger, mw} = await lb.express.middleware({
    logName: 'samples_express',
  });
  const app = express();

  // Install the logging middleware. This ensures that a Bunyan-style `log`
  // function is available on the `request` object. This should be the very
  // first middleware you attach to your app.
  app.use(mw);

  // Setup an http route and a route handler.
  app.get('/', (req, res) => {
    // `req.log` can be used as a bunyan style log method. All logs generated
    // using `req.log` use the current request context. That is, all logs
    // corresponding to a specific request will be bundled in the Stackdriver
    // UI.
    req.log.info('this is an info log message');
    res.send('hello world');
  });

  const port = process.env.PORT || 8080;

  // `logger` can be used as a global logger, one not correlated to any specific
  // request.
  logger.info({port}, 'bonjour');

  // Start listening on the http server.
  const server = app.listen(port, () => {
    console.log(`http server listening on port ${port}`);
  });

  app.get('/shutdown', (req, res) => {
    res.sendStatus(200);
    server.close();
  });
}

startServer();

Para mais informações sobre a instalação, consulte a documentação das bibliotecas do Cloud Logging para Node.js. Também pode comunicar problemas através do relatório de erros.

Escreva registos com a biblioteca de cliente do Cloud Logging

Para obter informações sobre a utilização direta da biblioteca cliente do Cloud Logging para Node.js, consulte o artigo Bibliotecas cliente do Cloud Logging.

Executar em Google Cloud

Para que uma aplicação escreva registos através das bibliotecas do Cloud Logging para Node.js, a conta de serviço do recurso subjacente tem de ter a função do IAM (roles/logging.logWriter) escritor de registos. A maioria dos Google Cloud ambientes configura automaticamente a conta de serviço predefinida para ter esta função.

App Engine

O Cloud Logging é ativado automaticamente para o App Engine, e a conta de serviço predefinida da sua app tem as autorizações de IAM predefinidas para escrever entradas de registo.

Para escrever entradas de registo a partir da sua app, recomendamos que use o Bunyan ou o Winston, conforme descrito nesta página.

Para mais informações, consulte o artigo Escrever e ver registos.

Google Kubernetes Engine (GKE)

O GKE concede automaticamente à conta de serviço predefinida a função do IAM Logs Writer (roles/logging.logWriter). Se usar a Workload Identity Federation para o GKE com esta conta de serviço predefinida para permitir que as cargas de trabalho acedam a Google Cloud APIs específicas, não é necessária nenhuma configuração adicional. No entanto, se usar a Workload Identity Federation para o GKE com uma conta de serviço do IAM personalizada, certifique-se de que a conta de serviço personalizada tem a função de escritor de registos (roles/logging.logWriter).

Se necessário, também pode usar o seguinte comando para adicionar o logging.write âmbito de acesso ao criar o cluster:

gcloud container clusters create example-cluster-name \
    --scopes https://www.googleapis.com/auth/logging.write

Compute Engine

Nota: para usar as bibliotecas do Cloud Logging para Node.js numa instância de MV do Compute Engine, não precisa de instalar o agente do Cloud Logging.

Quando usar instâncias de VM do Compute Engine, adicione o cloud-platform âmbito de acesso a cada instância. Quando cria uma nova instância através da Google Cloud consola, pode fazê-lo na secção Identidade e acesso à API do painel Criar instância. Use a conta de serviço predefinida do Compute Engine ou outra conta de serviço à sua escolha e selecione Permitir acesso total a todas as APIs Cloud na secção Identidade e acesso à API. Qualquer que seja a conta de serviço que selecionar, certifique-se de que lhe foi concedida a função Logs Writer na secção IAM e administrador daGoogle Cloud consola.

Funções do Cloud Run

As funções do Cloud Run concedem o papel Logs Writer por predefinição.

As bibliotecas do Cloud Logging para Node.js podem ser usadas sem ter de fornecer explicitamente credenciais.

As funções do Cloud Run estão configuradas para usar o Cloud Logging automaticamente.

Nota: os registos escritos em stdout e stderr são enviados automaticamente para o Cloud Logging, sem necessidade de usar as bibliotecas do Cloud Logging para Node.js.

Executar localmente e noutro local

Para usar as bibliotecas do Cloud Logging para Node.js fora do Google Cloud, incluindo a execução da biblioteca na sua própria estação de trabalho, nos computadores do seu centro de dados ou nas instâncias de VM de outro fornecedor de nuvem, tem de configurar as credenciais predefinidas da aplicação (ADC) no seu ambiente local para autenticar nas bibliotecas do Cloud Logging para Node.js.

Para mais informações, consulte o artigo Configure o ADC para um ambiente no local ou outro fornecedor de nuvem.

Use o Winston:
// Imports the Google Cloud client library for Winston
const {LoggingWinston} = require('@google-cloud/logging-winston');

// Creates a client
const loggingWinston = new LoggingWinston({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

Use o Bunyan:

// Imports the Google Cloud client library for Bunyan
const {LoggingBunyan} = require('@google-cloud/logging-bunyan');

// Creates a client
const loggingBunyan = new LoggingBunyan({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

Ver os registos

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 Explorador de registos, tem de especificar um ou mais recursos, mas a seleção de recursos pode não ser óbvia. Seguem-se algumas sugestões para ajudar a começar:

• Se estiver a implementar a sua aplicação no App Engine ou a usar as bibliotecas específicas do App Engine, defina o seu recurso como Aplicação GAE.

• Se estiver a implementar a sua aplicação no Compute Engine, defina o recurso como GCE VM Instance.

• Se estiver a implementar a sua aplicação no Google Kubernetes Engine, a configuração de registo do cluster determina o tipo de recurso das entradas de registo. Para uma discussão detalhada sobre o Google Cloud Observability antigo e as soluções de monitorização do Kubernetes do Google Cloud Observability, e como essas opções afetam o tipo de recurso, consulte o artigo Migrar para a monitorização do Kubernetes do Google Cloud Observability.

• Se a sua aplicação estiver a usar a API Cloud Logging diretamente, o recurso depende da API e da sua configuração. Por exemplo, na sua aplicação, pode especificar um recurso ou usar um recurso predefinido.

• Se não vir registos no Explorador de registos, para ver todas as entradas de registo, mude para o modo de consulta avançado e use uma consulta vazia.

  1. Para mudar para o modo de consulta avançado, clique no menu (▾) na parte superior do Explorador de registos e, em seguida, selecione Converter em filtro avançado.
  2. Limpar o conteúdo apresentado na caixa de filtro.
  3. Clique em Enviar filtro.

  Pode examinar as entradas individuais para identificar os seus recursos.

Para mais informações, consulte o artigo Usar o Explorador de registos.