Como configurar o Cloud Logging para Node.js

É possível gravar registros de aplicativos em Node.js no Logging com nossos plug-ins Bunyan ou Winston. Outra opção é fazer isso diretamente por meio da biblioteca de cliente do Cloud Logging na API Cloud para Node.js.

Não é necessário instalar o agente do Logging para usar as bibliotecas Bunyan e Winston em uma instância de VM do Compute Engine.

Antes de começar

  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página do seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. Ative a Cloud Logging API.

    Ative a API

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

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

Como usar o 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.

Como instalar o plug-in

  1. A maneira mais fácil de instalar o plug-in Bunyan do Logging é com NPM:

    npm install --save 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 Stackdriver Logging client
    const loggingBunyan = new LoggingBunyan();
    
    // Create a Bunyan logger that streams to Stackdriver 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 Stackdriver 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 Stackdriver Logging, logging at 'info' and above
        loggingBunyan.stream('info'),
      ],
    });
    
    // Writes some log entries
    logger.error('warp nacelles offline');
    logger.info('shields at 99%');

Como configurar o plug-in

É possível personalizar o comportamento do plug-in Bunyan usando as mesmas opções de configuração suportadas pela 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.

Como usar o 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.

Como instalar o plug-in

  1. A maneira mais fácil de instalar o plug-in Winston do Logging é com NPM:

    npm install --save @google-cloud/logging-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 Stackdriver 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 Stackdriver Logging
        loggingWinston,
      ],
    });
    
    // Writes some log entries
    logger.error('warp nacelles offline');
    logger.info('shields at 99%');

Como configurar o plug-in

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

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.

Como usar a biblioteca de cliente do Cloud diretamente

Para informações sobre como usar diretamente a biblioteca de cliente do Cloud Logging para Node.js, consulte Bibliotecas de cliente do Cloud Logging.

Como executar no Google Cloud

O uso de bibliotecas do Cloud Logging para Node.js requer a Cloud IAM Papel da gravadora de registros no Google Cloud. A maioria dos ambientes do Google Cloud fornece esse papel por padrão.

App Engine

O App Engine 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.

O Cloud Logging é ativado automaticamente para aplicativos do App Engine. Nenhuma outra configuração é necessária.

Google Kubernetes Engine

No Google Kubernetes Engine, você precisa 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, é possível adicionar o escopo 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 o papel de gravador de registros foi concedido a ela na seção IAM e administrador do Console do Cloud.

Cloud Functions

O Cloud 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.

O Cloud Functions é configurado para usar o Cloud Logging automaticamente.

Execução local e em outro lugar

Para usar 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 provedor de nuvem, forneça o ID do projeto e as credenciais de conta de serviço corretas diretamente para as bibliotecas do Cloud Logging para Node.js.

É possível criar e receber credenciais da conta de serviço manualmente. Ao especificar o campo Papel, use o papel de gravador de registros. Para mais informações sobre os papéis do Cloud Identity and Access Management, acesse o Guia de controle de acesso.

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

Como 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 visualizar os registros

Após a implantação, é possível usar o visualizador de registros do Console do Cloud.

Acessar o visualizador de registros

No visualizador de registros, é preciso especificar um ou mais recursos, mas a escolha de recursos 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 da 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 o pacote de operações do Google Cloud legado e as soluções do Kubernetes Monitoring do pacote de operações do Google Cloud, e sobre como essas opções afetam o tipo de recurso, consulte Como migrar para o Kubernetes Monitoring do pacote de operações do Google Cloud.

  • 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 visualizador, para ver todas as entradas, alterne para o modo de consulta avançada e use uma consulta vazia.

    1. Para alternar para o modo de consulta avançada, clique no menu (▾) na parte superior do visualizador 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 visualizar registros e Consultas avançadas de registros.