Compartir tecnología

Elasticsearch: Registro ECS de Node.js - Winston

2024-07-12

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

Esta es una continuación del artículo anterior "Elasticsearch: Registro ECS de Node.js - Pino” continuación de Continuamos el artículo anterior para hablar sobre el uso del paquete Winston para apuntar. Node.js La aplicación genera ECS para coincidir con el día.Este paquete Node.js esregistrador winstonSe proporciona un formateador, con Registro de esquema común elástico (ECS) compatible.combinarArchivo Beat Remitente, puede monitorear todos los registros desde un solo lugar en el Elastic Stack. Admite la versión winston 3.x >=3.3.3.

configuración

Instalar

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

Configuración

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') });
  • Pase el formateador ECS a winston.

El resultado de ejecutar el código anterior es:

Configurar filebeat

Filebeat 7.16+

archivobeat.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. Utilice la entrada de flujo de archivos para leer líneas de un archivo de registro activo.
  2. Si ocurre un conflicto, los valores del objeto JSON decodificado sobrescribirán los campos que Filebeat normalmente agrega (tipo, fuente, desplazamiento, etc.).
  3. Si se produce un error de resolución de JSON, Filebeat agregará las claves "error.message" y "error.type: json".
  4. Filebeat eliminará recursivamente las claves de puntos del JSON decodificado y lo expandirá en una estructura de objetos jerárquica.
  5. Los procesadores mejoran sus datos.Verprocesadores aprender más.

Archivo Beat < 7.16

archivobeat.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 más información, ver Referencia de filebeat。

cómo utilizar

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. Vea las opciones disponibles a continuación.
node winston-logging.js | jq .

Ejecute este script (disponible enaquíobtenido) producirá una salida de registro similar a la anterior.

El formateador es responsable de serializar los datos en JSON, por lo que no es necesario agregar json Formateador.Además, el formateador genera automáticamente la marca de tiempo, por lo que no es necesario agregarmarca de tiempo Formateador.

Registro de errores

De forma predeterminada, el formateador convierte el metacampo err de una instancia de Error en Campo de error ECSEr .Por ejemploejemplo：

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

El manejo especial del metacampo err se puede desactivar mediante la opción 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 solicitudes y respuestas HTTP

Usando la opción convertReqRes: true, el formateador convertirá automáticamente el núcleo de Node.js cuando se pase como metacampos req y res respectivamente. pedido yrespuesta 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. Utilice la opción convertReqRes
  2. Grabar metacampos req y/o res

Esto usará Campos HTTP de ECS Genera un registro que contiene información de solicitud y respuesta.Por ejemploejemplo：

Arriba, necesitamos acceder http://localhost:3000 Sólo entonces podrá ver la información del día que se muestra arriba.

Utilice APM para la correlación de registros

este Sistema de clasificación electrónica formateador de registros conAPM elástica integrado.Si su aplicación Node está utilizandoAgente APM elástico de Node.js, se agregan varios campos al registro para correlacionar el servicio APM o los datos de seguimiento y registro:

  • Las declaraciones de registro (como logger.info(...)) llamadas cuando se rastrea actualmente un intervalo incluiráncampos de seguimiento— trace.id, transacción.id, span.id.
  • Múltiples campos de identificador de servicio, determinados o configurados en el agente APM, permiten el enlace cruzado entre servicios y registros en Kibana: nombre.servicio, versión.servicio, entorno.servicio, nombre.nodo.
  • event.dataset está habilitado en aplicaciones de Elastic ObservabilityDetección de anomalías en la tasa de registro。

Por ejemplo, ejecutar ejemplos/http-con-elastic-apm.js ycurl -i localhost:3000/ Se genera un registro que contiene el siguiente contenido:

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

Estos ID coinciden con los datos de seguimiento informados por el agente de APM.

La integración con Elastic APM se puede deshabilitar explícitamente mediante la opción apmIntegration: false, por ejemplo:

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

Limitaciones y notas

especificación de registro ecs Se recomienda que los primeros tres campos del registro sean @timestamp, log.level y message. A partir de la versión 1.5.0, este formateador no sigue esta recomendación. Esto es posible pero requiere la creación de un nuevo objeto en ecsFields para cada registro. Dado que el orden de los campos de registro ecs es para facilitar la lectura y no afecta la interoperabilidad, se decidió priorizar el rendimiento.

Referirse a

ecsFormat([opciones])

  • opciones {tipo-objeto} admite las siguientes opciones:
    • convertErr {type-boolean} Si se debe convertir el campo de error del registro en el campo de error de ECS.valor por defecto:verdadero.
    • convertReqRes {type-boolean} Si se deben registrar los campos de solicitud y respuesta HTTP req y res en los campos HTTP, User-Agent y URL de ECS.valor por defecto:FALSO.
    • apmIntegration {type-boolean} Si se debe habilitar la integración del agente APM.valor por defecto:verdadero.
    • serviceName {tipo-cadena} valor "service.name". Si se especifica, anula cualquier valor del agente APM activo.
    • serviceVersion {tipo-cadena} valor "service.version". Si se especifica, anula cualquier valor del agente APM activo.
    • serviceEnvironment {tipo-cadena} valor "servicio.entorno". Si se especifica, anula cualquier valor del agente APM activo.
    • serviceNodeName {tipo-cadena} valor "service.node.name". Si se especifica, se sobrescribirá cualquier valor del agente APM activo.
    • eventDataset {tipo-cadena} valor "event.dataset". Si se especifica, se anulará el valor predeterminado de usar ${serviceVersion}.

Cree un formateador para Winston que emita el formato de registro ECS.Este es un tratamientoecsFields([opciones]) yecsStringify([opciones]) formato único. Los dos siguientes son 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([opciones])

  • opciones {tipo-objeto} admite las siguientes opciones:
    • convertErr {type-boolean} Si se debe convertir el campo de error del registro en el campo de error de ECS.valor por defecto:verdadero.
    • convertReqRes {type-boolean} Si se deben registrar los campos de solicitud y respuesta HTTP req y res en los campos HTTP, User-Agent y URL de ECS.valor por defecto:FALSO.
    • apmIntegration {type-boolean} Si se debe habilitar la integración del agente APM.valor por defecto:verdadero.
    • serviceName {tipo-cadena} valor "service.name". Si se especifica, anula cualquier valor del agente APM activo.
    • serviceVersion {tipo-cadena} valor "service.version". Si se especifica, anula cualquier valor del agente APM activo.
    • serviceEnvironment {tipo-cadena} valor "servicio.entorno". Si se especifica, anula cualquier valor del agente APM activo.
    • serviceNodeName {tipo-cadena} valor "service.node.name". Si se especifica, se sobrescribirá cualquier valor del agente APM activo.
    • eventDataset {tipo-cadena} valor "event.dataset". Si se especifica, se anulará la configuración predeterminada de uso de ${serviceVersion}.

Cree un formateador para Winston que convierta los campos del objeto de información de registro al formato de registro ECS.

ecsStringify([opciones])

Cree un formateador para que Winston encadene/serialice registros de registro en JSON.

Esto es similar a logform.json(). Ambos usan el paquete safe-stable-stringify para generar JSON. Algunas diferencias:

  • Este stringificador omite la serialización del campo de nivel porque no es un campo ECS.
  • Winston proporciona un sustituto que convierte bigint en cadena. La razón de esto es que el analizador JSON de JavaScript pierde precisión al analizar bigints. La objeción es que BigInt cambia el tipo a cadena en lugar de número. Actualmente, este stringificador no convierte BitInt en cadena.

Perfil personal

Se ha dedicado a la investigación de tecnología durante más de 30 años y domina varios lenguajes como java, linux, javascript, php, css, etc. Ha realizado muchas contribuciones en el campo del código abierto. Estación de documentación para desarrolladores para compartir algunos problemas en el desarrollo de tecnología para referencia futura.

Mi informacion de contacto

Correo