CORE-SLOGGER

Objetivo

Provê um middleware de publicação de logs instalável em qualquer projeto Node.js.

Visa realizar uma integração simples entre os projetos Sossego com os serviços de logging no BigQuery.

A versão atual não suporta mais o uso do Sentry

Instalação

1. Configure as Variáveis de Ambiente

No arquivo .env do projeto, adicione as seguintes variáveis:

# Certifique-se que o env do NodeJS está presente
NODE_ENV='production/staging/development'

# • Slogger Host: URL da API Slogger usada para integrações
SLOGGER_HOST='https://slogger-xxx.app'

# • Slogger Auth: Valor a ser enviado como Authorization nos Headers
SLOGGER_AUTH='xyz'

# • Slogger Project: Nome do projeto usado para integrações
SLOGGER_PROJECT='<nome-do-projeto-git>'

2. Instale o Pacote Slogger

No diretório do projeto execute o comando:

npm i git+https://gitlab.com/sossego/packages/slogger.git

Regras

A aplicação irá extrair o ambiente de execução de acordo com a variável NODE_ENV.

O comportamento durante utilização está predefinido para as seguintes regras:

Desenvolvimento

• Imprime todos os logs no stdout e aplica cor na fonte de acordo com o método
• Não realiza integração com a API

Homologação

• Imprime apenas severidade WARNING+ e utiliza o stderr
• Envia os logs de severidade INFO+ para a API com a tag de ambiente STAGING

Produção

• Imprime apenas severidade WARNING+ e utiliza o stderr
• Envia os logs de severidade INFO+ para a API com a tag de ambiente PRODUCTION

Utilização

Importação utilizando GitHub packages

Em qualquer módulo do projeto adicione ao topo:

const { slogger } = require('@sossego/core-slogger'); // JavaScript

import { slogger } from '@sossego/core-slogger'; // TypeScript

O objeto slogger conterá o singleton da aplicação.

Métodos

Os métodos disponíveis para registro de eventos são em ordem de criticidade:

slogger.debug();    // Level 500
slogger.info();     // Level 400
slogger.warning();  // Level 300
slogger.error();    // Level 200
slogger.critical(); // Level 100

Todos os métodos aceitam os mesmo dois parâmetros:

error(message: string | Error, data?: any): Promise<void>;

Parâmetro | Mandatório | Descrição :-- | :-- | :-- message | Sim | Uma mensagem de texto ou objeto de erro data | Não | Um objeto qualquer contendo dados relevantes para o log

Embora o parâmetro message aceite uma string, no caso dos métodos error e critical ele será automaticamente convertido em um objeto Error para podermos usufruir do stack.

Exemplo

import { slogger } from '@sossego/core-slogger'; // TypeScript

const documento = {
  nome: "JOSÉ PAULO",
  cpf: "123.456.789-00",
};

try {
  slogger.debug("Gravando documento...");

// ...

  slogger.success("Documento gravado com sucesso!");
} catch (e) {
  slogger.error(e, documento);
}

Boas Práticas

1. Não envie o objeto de erro como dado

Incorreto

try {
  // ...
} catch (e) {
  // Aqui como o 1º param é um string será criado outro objeto erro
  slogger.error("deu erro", e);
}

Correto

try {
  // ...
} catch (e) {
  slogger.error(e);
}

2. Não faça log de uma string caso tenha o objeto de erro em mãos

Incorreto

const arrayFinal = [];

try {
  const array1 = await httpService.get("abc");
  const array2 = await httpService.get("xyz");
  arrayFinal = array1.concat(array2);
} catch (e) {
  // Ao fazer isto não saberemos se o problema ocorreu ao dar o GET
  // no array1, no array2, ou durante a concatenação
  slogger.error("falha ao concatenar array", arrayFinal);
}

Correto

const arrayFinal = [];

try {
  const array1 = await httpService.get("abc");
  const array2 = await httpService.get("xyz");
  arrayFinal = array1.concat(array2);
} catch (e) {
  // Se for crucial ter uma mensagem customizada, altere a msg de erro:
  // e.message = `Falha ao concatenar array: ${e.message}`;
  // Se não, simplesmente utilize conforme (em geral isto é suficiente):
  slogger.error(e, arrayFinal);
}

** NPM do GitHub**

Para instalação do pacote a partir do GitHub é necessário a configuração do Personal Access Token (https://github.com/settings/personal-access-tokens/new).

Este token deve ter permissão de leitura de packages "read:packages"

# Informe o seu usuário do github "Sossego", e-mail e token gerado no passo anterior
npm login --scope=sossego --registry=https://npm.pkg.github.com

npm install @sossego/core-slogger@latest

Para instalar uma versão anterior informe o número da versão na instalação

# npm install @sossego/[email protected]

Referência: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#installing-a-package

** Notas sobre as versões anteriores **

v0.2.5 - atualizadas dependencias

v0.2.4 - removido o uso do Sentry

v0.2.3 - continua compatível com o Sentry e foram atualizadas as dependências para versões mais novas

v0.2.2 - continua compatível com o Sentry e com os mesmo packages, A versão anterior continua pública no Gitlab (https://gitlab.com/sossego/packages/slogger)