Compartilhamento de tecnologia

Elasticsearch: registro ECS do Node.js - Winston

2024-07-12

한어Русский языкEnglishFrançaisIndonesianSanskrit日本語DeutschPortuguêsΕλληνικάespañolItalianoSuomalainenLatina

Esta é uma continuação do artigo anterior "Elasticsearch: registro ECS do Node.js - Pino”Continuação de. Continuamos o artigo anterior para falar sobre o uso do pacote Winston para direcionar. Node.js O aplicativo gera ECS para combinar com o dia.Este pacote Node.js éregistrador de WinstonUm formatador é fornecido, com Criação de log do Elastic Common Schema (ECS) compatível.combinarBatida de arquivo Remetente, você pode monitorar todos os logs de um só lugar no Elastic Stack. Suporte à versão Winston 3.x> = 3.3.3.

configurar

Instalar

  1. npm install @elastic/ecs-winston-format
  2. npm install winston

Configuração

winston-logging.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3.  
  4. const logger = winston.createLogger({
  5.   format: ecsFormat(/* options */),  // 1
  6.   transports: [
  7.     new winston.transports.Console()
  8.   ]
  9. });
  10.  
  11. logger.info('hi');
  12. logger.error('oops there is a problem', { err: new Error('boom') });
  • Passe o formatador ECS para Winston.

O resultado da execução do código acima é:

Configurar o Filebeat

Filebeat 7.16+

arquivobeat.yml

  1. filebeat.inputs:
  2. - type: filestream     # 1
  3.   paths: /path/to/logs.json
  4.   parsers:
  5.     - ndjson:
  6.       overwrite_keys: true # 2
  7.       add_error_key: true  # 3
  8.       expand_keys: true    # 4
  9.  
  10. processors: // 5
  11.   - add_host_metadata: ~
  12.   - add_cloud_metadata: ~
  13.   - add_docker_metadata: ~
  14.   - add_kubernetes_metadata: ~
  1. Use a entrada filestream para ler linhas de um arquivo de log ativo.
  2. Se ocorrer um conflito, os valores do objeto JSON decodificado substituirão os campos que o Filebeat normalmente adiciona (tipo, origem, deslocamento, etc.).
  3. Se ocorrer um erro de desempacotamento de JSON, o Filebeat adicionará as chaves "error.message" e "error.type: json".
  4. O Filebeat removerá recursivamente as chaves de ponto do JSON decodificado e o expandirá em uma estrutura de objeto hierárquica.
  5. Os processadores aprimoram seus dados.Verprocessadores aprender mais.

Filebeat < 7,16

arquivobeat.yml

  1. filebeat.inputs:
  2. - type: log
  3.   paths: /path/to/logs.json
  4.   json.keys_under_root: true
  5.   json.overwrite_keys: true
  6.   json.add_error_key: true
  7.   json.expand_keys: true
  8.  
  9. processors:
  10. - add_host_metadata: ~
  11. - add_cloud_metadata: ~
  12. - add_docker_metadata: ~
  13. - add_kubernetes_metadata: ~

Para mais informações, veja Referência do Filebeat。

Como usar

winston-logging.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3.  
  4. const logger = winston.createLogger({
  5.   level: 'info',
  6.   format: ecsFormat(/* options */), // 1
  7.   transports: [
  8.     new winston.transports.Console()
  9.   ]
  10. });
  11.  
  12. logger.info('hi');
  13. logger.error('oops there is a problem', { foo: 'bar' });
  1. Veja as opções disponíveis abaixo.
node winston-logging.js | jq .

Execute este script (disponível emaquiobtido) produzirá uma saída de log semelhante à acima.

O formatador é responsável por serializar os dados em JSON, então você não precisa adicionar json Formatador.Além disso, o formatador gera automaticamente o carimbo de data/hora, então você não precisa adicionarcarimbo de data/hora Formatador.

Registro de erros

Por padrão, o formatador converte o metacampo err de uma instância Error para Campo ECSError .Por exemploexemplo：

winston-logging.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3. const logger = winston.createLogger({
  4.   format: ecsFormat(), 
  5.   transports: [
  6.     new winston.transports.Console()
  7.   ]
  8. });
  9.  
  10. const myErr = new Error('boom');
  11. logger.info('oops', { err: myErr });

O tratamento especial do metacampo err pode ser desabilitado através da opção convertErr: false:

winston-logging.js

  1. const winston = require('winston');
  2. const { ecsFormat } = require('@elastic/ecs-winston-format');
  3. const logger = winston.createLogger({
  4.   format: ecsFormat({convertErr: false} ), 
  5.   transports: [
  6.     new winston.transports.Console()
  7.   ]
  8. });
  9.  
  10. const myErr = new Error('boom');
  11. logger.info('oops', { err: myErr });

Registro de solicitação e resposta HTTP

Usando a opção convertReqRes: true, o formatador converterá automaticamente o núcleo do Node.js quando passado como metacampos req e res, respectivamente. solicitar eresposta objeto.

winston-logging.js

  1. const http = require('http');
  2. const winston = require('winston');
  3. const { ecsFormat } = require('@elastic/ecs-winston-format');
  4.  
  5. const logger = winston.createLogger({
  6.   level: 'info',
  7.   format: ecsFormat({ convertReqRes: true }), // 1
  8.   transports: [
  9.     new winston.transports.Console()
  10.   ]
  11. });
  12.  
  13. const server = http.createServer(handler);
  14. server.listen(3000, () => {
  15.   logger.info('listening at http://localhost:3000')
  16. });
  17.  
  18. function handler (req, res) {
  19.   res.setHeader('Foo', 'Bar');
  20.   res.end('ok');
  21.   logger.info('handled request', { req, res }); // 2
  22. }
  1. Use a opção convertReqRes
  2. Registrar metacampos req e/ou res

Isso usará Campos HTTP do ECS Gera um log contendo informações de solicitação e resposta.Por exemploexemplo：

Acima, precisamos acessar http://localhost:3000 Só então você poderá ver as informações do dia mostradas acima.

Use APM para correlação de log

esse ECS formatador de log comAPM elástico integrado.Se o seu aplicativo Node estiver usandoAgente Node.js Elastic APM, vários campos são incluídos no registro de log para correlacionar o serviço APM ou rastrear e registrar dados:

  • Instruções de log (como logger.info(...)) chamadas ao rastrear atualmente um intervalo incluirãocampos de rastreamento— trace.id, transação.id, span.id.
  • Vários campos de identificação de serviço, determinados ou configurados no agente APM, permitem a ligação cruzada entre serviços e logs no Kibana — service.name, service.version, service.environment, service.node.name.
  • event.dataset está habilitado em aplicativos Elastic ObservabilityDetecção de anomalia na taxa de registro。

Por exemplo, execute exemplos/http-com-elastic-apm.js ecurl -i localhost:3000/ Um registro de log contendo o seguinte conteúdo é produzido:

  1. % node examples/http-with-elastic-apm.js | jq .
  2. ...
  3.   "service.name": "http-with-elastic-apm",
  4.   "service.version": "1.4.0",
  5.   "service.environment": "development",
  6.   "event.dataset": "http-with-elastic-apm"
  7.   "trace.id": "7fd75f0f33ff49aba85d060b46dcad7e",
  8.   "transaction.id": "6c97c7c1b468fa05"
  9. }

Esses IDs correspondem aos dados de rastreamento relatados pelo agente APM.

A integração com o Elastic APM pode ser explicitamente desabilitada por meio da opção apmIntegration: false, por exemplo:

  1. const logger = winston.createLogger({
  2.   format: ecsFormat({ apmIntegration: false }),
  3.   // ...
  4. })

Limitações e Notas

especificação de registro ecs Recomenda-se que os três primeiros campos do registro de log sejam @timestamp, log.level e mensagem. A partir da versão 1.5.0, este formatador não segue esta recomendação. Isso é possível, mas requer a criação de um novo objeto em ecsFields para cada registro de log. Dado que a ordenação dos campos ecs-logging é para facilitar a leitura e não afeta a interoperabilidade, decidiu-se priorizar o desempenho.

referir-se

ecsFormat([opções])

  • options {type-object} suporta as seguintes opções:
    • convertErr {type-boolean} Se o campo err do registro deve ser convertido no campo de erro do ECS.valor padrão:verdadeiro.
    • convertReqRes {type-boolean} Se deve registrar os campos de solicitação e resposta HTTP req e res nos campos HTTP, Agente do usuário e URL do ECS.valor padrão:falso.
    • apmIntegration {type-boolean} Se a integração do agente APM deve ser habilitada.valor padrão:verdadeiro.
    • serviceName {type-string} valor "service.name". Se especificado, substitui qualquer valor do agente APM ativo.
    • serviceVersion {type-string} valor "service.version". Se especificado, substitui qualquer valor do agente APM ativo.
    • serviceEnvironment {type-string} valor "service.environment". Se especificado, substitui qualquer valor do agente APM ativo.
    • serviceNodeName {type-string} valor "service.node.name". Se especificado, qualquer valor do agente APM ativo será substituído.
    • eventDataset {type-string} valor "event.dataset". Se especificado, o valor padrão de uso de ${serviceVersion} será substituído.

Crie um formatador para o Winston que emita o formato de log do ECS.Este é um tratamentoecsFields([opções]) eecsStringify([opções]) formato único. Os dois seguintes são equivalentes:

  1. const { ecsFormat, ecsFields, ecsStringify } = require('@elastic/ecs-winston-format');
  2. const winston = require('winston');
  3.  
  4. const logger = winston.createLogger({
  5.   format: ecsFormat(/* options */),
  6.   // ...
  7. });
  8.  
  9. const logger = winston.createLogger({
  10.   format: winston.format.combine(
  11.     ecsFields(/* options */),
  12.     ecsStringify()
  13.   ),
  14.   // ...
  15. });

ecsFields([opções])

  • options {type-object} suporta as seguintes opções:
    • convertErr {type-boolean} Se o campo err do registro deve ser convertido no campo de erro do ECS.valor padrão:verdadeiro.
    • convertReqRes {type-boolean} Se deve registrar os campos de solicitação e resposta HTTP req e res nos campos HTTP, Agente do usuário e URL do ECS.valor padrão:falso.
    • apmIntegration {type-boolean} Se a integração do agente APM deve ser habilitada.valor padrão:verdadeiro.
    • serviceName {type-string} valor "service.name". Se especificado, substitui qualquer valor do agente APM ativo.
    • serviceVersion {type-string} valor "service.version". Se especificado, substitui qualquer valor do agente APM ativo.
    • serviceEnvironment {type-string} valor "service.environment". Se especificado, substitui qualquer valor do agente APM ativo.
    • serviceNodeName {type-string} valor "service.node.name". Se especificado, qualquer valor do agente APM ativo será substituído.
    • eventDataset {type-string} valor "event.dataset". Se especificado, a configuração padrão de uso de ${serviceVersion} será substituída.

Crie um formatador para o Winston que converta os campos no objeto de informações de log para o formato de log do ECS.

ecsStringify([opções])

Crie um formatador para o Winston para stringificar/serializar registros de log para JSON.

Isso é semelhante a logform.json(). Ambos usam o pacote safe-stable-stringify para gerar JSON. Algumas diferenças:

  • Este stringifier ignora a serialização do campo de nível porque não é um campo ECS.
  • Winston fornece um substituto que converte bigint em string. A razão para isso é que o analisador JavaScript JSON perde precisão ao analisar bigints. A objeção é que BigInt altera o tipo para string em vez de número. Atualmente, este stringifier não converte BitInt em string.

Perfil pessoal

Ele se dedica à pesquisa de tecnologia há mais de 30 anos e é proficiente em diversas linguagens como java, linux, javascript, php, css, etc. estação de documentação do desenvolvedor para compartilhar alguns problemas no desenvolvimento de tecnologia para referência futura.

minhas informações de contato

Correspondência