Como configurar o Cloud Logging para Node.js

Para aplicativos Node.js, os plug-ins são mantidos nas bibliotecas de geração de registros já conhecidas Winston e Bunyan. Winston é uma biblioteca de uso geral que implementa uma variedade de formatadores e transportes de registro. O Bunyan, que é especializado em registros JSON estruturados, oferece suporte à formatação de registros por 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 Pino log framework.

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

  1. 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.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Cloud Logging API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Cloud Logging API.

    Enable the API

    8.
  8. Prepare o ambiente para o desenvolvimento do Node.js.

    Acessar o guia de configuração do Node.js

    9. Configurar a geração de registros

    Nesta seção, descrevemos como instalar e configurar os plug-ins para as bibliotecas de geração de registros Winston e Bunyan. Para o Bunyan, informações são fornecidas sobre como usar o Bunyan com um aplicativo Node.js Express.

    Você pode usar outras bibliotecas ou frameworks. Por exemplo, use o framework de registro Pino. Para ver 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 Exemplo de instrumentação do Node.js. Se você usa o Pino, implemente um mapeamento entre os níveis de gravidade do Pino e os usados pelo Cloud Logging. Para um exemplo de código, consulte Mapeamento de 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 do Winston, faça o seguinte:

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

      npm install @google-cloud/logging-winston winston

    2. Importe o plug-in e adicione-o à 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.

      É possível personalizar o comportamento do plug-in Winston usando as mesmas opções de configuração compatíveis com a biblioteca de cliente da API Cloud do Cloud Logging para Node.js. Essas opções podem ser transmitidas no objeto options para o construtor do plug-in.

    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:

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

      npm install bunyan @google-cloud/logging-bunyan

    2. Importe o plug-in e adicione-o à 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.

      É possível personalizar o comportamento do plug-in Bunyan usando as mesmas opções de configuração compatíveis com a biblioteca de cliente da Cloud API do Cloud Logging para Node.js. Essas opções podem ser transmitidas no objeto options para o construtor do plug-in.

    Usar o Bunyan e o Express

    É possível configurar e usar o Bunyan com o Logging em um 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 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 em 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 o papel Gravador de registros (roles/logging.logWriter) do IAM. 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.

    Para mais informações, consulte Gravar e visualizar registros.

    Google Kubernetes Engine (GKE)

    O GKE concede automaticamente à conta de serviço padrão o papel do IAM de Gravador de registros (roles/logging.logWriter). Se você usar a Federação de identidade da carga de trabalho para GKE com essa conta de serviço padrão para permitir que as cargas de trabalho acessem APIs específicas doGoogle Cloud , nenhuma configuração adicional será necessária. No entanto, se você usar a Federação de Identidade da Carga de Trabalho para GKE com uma conta de serviço personalizada do IAM, verifique se ela tem a função 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 pelo console doGoogle 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 a conta de serviço selecionada, verifique se ela recebeu o papel de gravador de registros na seção IAM e administrador doGoogle Cloud console.

    Funções do Cloud Run

    As funções do Cloud Run concedem 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, incluindo a execução da biblioteca na sua estação de trabalho, nos computadores do seu data center ou nas instâncias de VM de outro provedor de nuvem, configure o Application Default Credentials (ADC) no seu ambiente local para autenticar as bibliotecas do Cloud Logging para Node.js.

    Para mais informações, consulte Configurar o ADC para um ambiente local ou outro provedor de nuvem.

    Usar 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',
});

    Como usar 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',
});

    Visualize os registros

    No console 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 uma discussão detalhada sobre as soluções do Legacy Google Cloud Observability e do Kubernetes Monitoring do Google Cloud Observability e como essas opções afetam o tipo de recurso, consulte Como migrar para o Kubernetes Monitoring do Google Cloud Observability.

    • 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.

      1. 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.
      2. Limpe o conteúdo que aparece na caixa de filtro.
      3. Clique em Enviar filtro.

      É possível examinar as entradas individuais para identificar seus recursos.

    Para mais informações, consulte Como usar o Explorador de registros.